Disques externes pour stocker des données

Les données traitées dans ClickHouse sont généralement stockées dans le système de fichiers local de la machine sur laquelle s’exécute le serveur ClickHouse. Cela nécessite des disques de grande capacité, qui peuvent être coûteux. Pour éviter de stocker les données localement, plusieurs options de stockage sont prises en charge :

Le stockage objet Amazon S3.
Azure Blob Storage.
Non pris en charge : Hadoop Distributed File System (HDFS)

Configurer le stockage externe

Les moteurs de table des familles MergeTree et Log peuvent stocker les données dans S3, AzureBlobStorage, HDFS (non pris en charge) en utilisant respectivement un disque de type s3, azure_blob_storage, hdfs (non pris en charge).

La configuration du disque nécessite :

Une section type, égale à l'une des valeurs s3, azure_blob_storage, hdfs (non pris en charge), local_blob_storage, web.
La configuration d'un type spécifique de stockage externe.

À partir de la version 24.1 de ClickHouse, il est possible d'utiliser une nouvelle option de configuration. Elle nécessite de spécifier :

Un type égal à object_storage
object_storage_type, égal à l'une des valeurs s3, azure_blob_storage (ou simplement azure à partir de 24.3), hdfs (non pris en charge), local_blob_storage (ou simplement local à partir de 24.3), web.

Il est également possible de spécifier metadata_type (sa valeur par défaut est local) ; il peut aussi être défini sur plain, web et, à partir de 24.4, plain_rewritable. L'utilisation du type de métadonnées plain est décrite dans la section sur le stockage simple. Le type de métadonnées web ne peut être utilisé qu'avec le type de stockage objet web. Le type de métadonnées local stocke les fichiers de métadonnées localement (chaque fichier de métadonnées contient la correspondance avec les fichiers du stockage objet, ainsi que des méta-informations supplémentaires à leur sujet).

Par exemple :

<s3>
    <type>s3</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3>

correspond à la configuration suivante (depuis la version 24.1) :

<s3>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>local</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3>

La configuration suivante :

<s3_plain>
    <type>s3_plain</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

est égal à :

<s3_plain>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>plain</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

Voici un exemple de configuration complète du stockage :

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
                <use_environment_credentials>1</use_environment_credentials>
            </s3>
        </disks>
        <policies>
            <s3>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3>
        </policies>
    </storage_configuration>
</clickhouse>

À partir de la version 24.1, cela peut aussi se présenter ainsi :

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>object_storage</type>
                <object_storage_type>s3</object_storage_type>
                <metadata_type>local</metadata_type>
                <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
                <use_environment_credentials>1</use_environment_credentials>
            </s3>
        </disks>
        <policies>
            <s3>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3>
        </policies>
    </storage_configuration>
</clickhouse>

Pour définir un type de stockage spécifique comme option par défaut pour toutes les tables MergeTree, ajoutez la section suivante au fichier de configuration :

<clickhouse>
    <merge_tree>
        <storage_policy>s3</storage_policy>
    </merge_tree>
</clickhouse>

Si vous souhaitez configurer une politique de stockage spécifique pour une table particulière, vous pouvez la définir dans les paramètres lors de la création de la table :

CREATE TABLE test (a Int32, b String)
ENGINE = MergeTree() ORDER BY a
SETTINGS storage_policy = 's3';

Vous pouvez aussi utiliser disk à la place de storage_policy. Dans ce cas, il n'est pas nécessaire d'inclure la section storage_policy dans le fichier de configuration : une section disk suffit.

CREATE TABLE test (a Int32, b String)
ENGINE = MergeTree() ORDER BY a
SETTINGS disk = 's3';

refresh_parts_interval et table_disk

Ce paramètre est destiné aux tables MergeTree non-Replicated, lorsque des parts peuvent être écrites en externe et que les métadonnées doivent être rechargées depuis le stockage.

Le paramètre MergeTree refresh_parts_interval active le rechargement périodique de la liste des data parts depuis le stockage sous-jacent (par ex. pour prendre en compte des parts écrites en externe). La distinction essentielle est la suivante : métadonnées partagées entre les répliques vs métadonnées locales à chaque réplique (par ex. S3 avec des métadonnées locales par réplique). Les nouvelles parts ne seront visibles par toutes les répliques que si les métadonnées sont partagées. Le simple recours au stockage objet n'implique pas des métadonnées partagées.

Le stockage objet (par ex. disk = 's3') n'implique pas des métadonnées partagées. Lorsque les métadonnées sont stockées localement sur chaque réplique (par défaut), chaque réplique gère indépendamment ses pointeurs vers les blobs du stockage objet. Les modifications effectuées sur une réplique ne sont pas visibles sur les autres. Dans ce cas, refresh_parts_interval ne rend pas les nouvelles parts visibles d'une réplique à l'autre, car les métadonnées lues par chaque réplique sont locales.
Le rechargement automatique des parts exige que les métadonnées du filesystem soient partagées (ou que la table utilise des métadonnées readonly propres à la table, afin que ce rechargement soit applicable). Définir table_disk = true avec un disque local à la table (par ex. SETTINGS disk = disk(type=object_storage, ...), table_disk = true) est un moyen d'obtenir la sémantique correcte : la table gère le cycle de vie des métadonnées et le stockage est traité comme readonly ; ainsi, refresh_parts_interval s'exécute et les parts ajoutées en externe peuvent être découvertes.
Avec un disque défini globalement (par ex. disk = 's3' dans storage_configuration) et les métadonnées locales par défaut, chaque réplique possède son propre état de métadonnées. Même si les blobs se trouvent dans S3, le stockage n'est pas considéré comme partagé du point de vue de refresh_parts_interval, et les nouvelles parts créées en dehors de ClickHouse ou sur une autre réplique ne seront pas détectées.

Pour le rechargement automatique des parts, assurez-vous que les métadonnées sont partagées ou utilisez un disque au niveau de la table avec table_disk = true, comme ci-dessus. Si vous vous appuyez uniquement sur refresh_parts_interval avec des métadonnées locales à chaque réplique, les parts ne seront pas rechargées comme prévu.

Configuration dynamique

Il est également possible de spécifier une configuration du stockage sans disque prédéfini dans un fichier de configuration, mais aussi de la définir dans les paramètres de requête CREATE/ATTACH.

La requête d’exemple suivante s’appuie sur la configuration dynamique des disques ci-dessus et montre comment utiliser un disque local pour mettre en cache les données d’une table stockée à une URL.

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
    type=web,
    endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
  );

L’exemple ci-dessous ajoute un cache au stockage externe.

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
    type=cache,
    max_size='1Gi',
    path='/var/lib/clickhouse/custom_disk_cache/',
    disk=disk(
      type=web,
      endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
      )
  );

Dans les paramètres mis en évidence ci-dessous, notez que le disque de type=web est imbriqué dans le disque de type=cache.

Une combinaison d’une configuration basée sur la config et d’une configuration définie en SQL est également possible :

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
    type=cache,
    max_size='1Gi',
    path='/var/lib/clickhouse/custom_disk_cache/',
    disk=disk(
      type=web,
      endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
      )
  );

où web est issu du fichier de configuration du serveur :

<storage_configuration>
    <disks>
        <web>
            <type>web</type>
            <endpoint>'https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'</endpoint>
        </web>
    </disks>
</storage_configuration>

Utiliser le stockage S3

Paramètres requis

Paramètre	Description
`endpoint`	URL de l'endpoint S3 de type `path` ou `virtual hosted` styles. Elle doit inclure le bucket et le chemin racine de stockage des données.
`access_key_id`	ID de la clé d'accès S3 utilisée pour l'authentification.
`secret_access_key`	Clé d'accès secrète S3 utilisée pour l'authentification.

Paramètres facultatifs

Paramètre	Description	Valeur par défaut
`region`	Nom de la région S3.	-
`support_batch_delete`	Détermine s’il faut vérifier la prise en charge de la suppression par lot. Définissez cette option sur `false` lorsque vous utilisez Google Cloud Storage (GCS), car GCS ne prend pas en charge les suppressions par lot.	`true`
`use_environment_credentials`	Lit les identifiants AWS à partir des variables d’environnement `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` et `AWS_SESSION_TOKEN` si elles existent. Remarque : les identifiants d’environnement sont partagés entre tous les disques S3. Pour utiliser des identifiants différents selon les disques, spécifiez plutôt explicitement `access_key_id` et `secret_access_key` pour chaque disque.	`false`
`use_insecure_imds_request`	Si `true`, utilise une requête IMDS non sécurisée lors de l’obtention des identifiants à partir des métadonnées Amazon EC2.	`false`
`expiration_window_seconds`	Délai de grâce (en secondes) pour vérifier si des identifiants basés sur l’expiration ont expiré.	`120`
`proxy`	Configuration du proxy pour l’endpoint S3. Chaque élément `uri` à l’intérieur du bloc `proxy` doit contenir une URL de proxy.	-
`connect_timeout_ms`	Délai d’expiration de connexion du socket, en millisecondes.	`10000` (10 secondes)
`request_timeout_ms`	Délai d’expiration de la requête, en millisecondes.	`5000` (5 secondes)
`retry_attempts`	Nombre de tentatives de réessai pour les requêtes ayant échoué.	`10`
`single_read_retries`	Nombre de tentatives de réessai en cas de coupure de connexion pendant la lecture.	`4`
`min_bytes_for_seek`	Nombre minimal d’octets pour utiliser une opération de seek au lieu d’une lecture séquentielle.	`1 MB`
`metadata_path`	Chemin du système de fichiers local où stocker les fichiers de métadonnées S3.	`/var/lib/clickhouse/disks/<disk_name>/`
`skip_access_check`	Si `true`, ignore les vérifications d’accès au disque au démarrage.	`false`
`header`	Ajoute l’en-tête HTTP spécifié aux requêtes. Peut être spécifié plusieurs fois.	-
`server_side_encryption_customer_key_base64`	En-têtes requis pour accéder aux objets S3 avec le chiffrement SSE-C.	-
`server_side_encryption_kms_key_id`	En-têtes requis pour accéder aux objets S3 avec le chiffrement SSE-KMS. Une chaîne vide utilise la clé S3 gérée par AWS.	-
`server_side_encryption_kms_encryption_context`	En-tête de contexte de chiffrement pour SSE-KMS (utilisé avec `server_side_encryption_kms_key_id`).	-
`server_side_encryption_kms_bucket_key_enabled`	Active les clés de bucket S3 pour SSE-KMS (utilisé avec `server_side_encryption_kms_key_id`).	Correspond au paramètre au niveau du bucket
`s3_max_put_rps`	Nombre maximal de PUT request par seconde avant limitation du débit.	`0` (illimité)
`s3_max_put_burst`	Nombre maximal de PUT request simultanées avant d’atteindre la limite RPS.	Identique à `s3_max_put_rps`
`s3_max_get_rps`	Nombre maximal de GET request par seconde avant limitation du débit.	`0` (illimité)
`s3_max_get_burst`	Nombre maximal de GET request simultanées avant d’atteindre la limite RPS.	Identique à `s3_max_get_rps`
`key_template`	Définit le format de génération des clés d’objet à l’aide de la syntaxe re2. Nécessite l’indicateur `storage_metadata_write_full_object_key`. Incompatible avec `root path` dans `endpoint`. Nécessite `key_compatibility_prefix`.	-
`key_compatibility_prefix`	Requis avec `key_template`. Spécifie l’ancien `root path` de `endpoint` pour lire les anciennes versions des métadonnées.	-
`read_only`	Autorise uniquement la lecture à partir du disque.	-

Utilisation du stockage simple

Dans 22.10, un nouveau type de disque s3_plain a été introduit. Il fournit un stockage en écriture unique. Ses paramètres de configuration sont les mêmes que pour le type de disque s3. Contrairement au type de disque s3, il stocke les données telles quelles. Autrement dit, au lieu d'utiliser des noms de blob générés aléatoirement, il utilise des noms de fichiers classiques (de la même manière que ClickHouse stocke les fichiers sur un disque local) et ne stocke aucune métadonnée localement. Par exemple, ces métadonnées sont déduites des données sur s3.

Ce type de disque permet de conserver une version statique de la table, car il ne permet pas d'exécuter de merges sur les données existantes et n'autorise pas l'insertion de nouvelles données. Un cas d'utilisation de ce type de disque consiste à y créer des sauvegardes, ce qui peut être fait via BACKUP TABLE data TO Disk('plain_disk_name', 'backup_name'). Ensuite, vous pouvez exécuter RESTORE TABLE data AS data_restored FROM Disk('plain_disk_name', 'backup_name') ou utiliser ATTACH TABLE data (...) ENGINE = MergeTree() SETTINGS disk = 'plain_disk_name'.

Configuration :

<s3_plain>
    <type>s3_plain</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

À partir de 24.1, il est possible de configurer n’importe quel disque de stockage objet (s3, azure, hdfs (non pris en charge), local) à l’aide du type de métadonnées plain.

Configuration :

<s3_plain>
    <type>object_storage</type>
    <object_storage_type>azure</object_storage_type>
    <metadata_type>plain</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

Utilisation du stockage S3 Plain Rewritable

Un nouveau type de disque s3_plain_rewritable a été introduit dans 24.4. Comme le type de disque s3_plain, il ne nécessite pas de stockage supplémentaire pour les fichiers de métadonnées. À la place, les métadonnées sont stockées dans S3. Contrairement au type de disque s3_plain, s3_plain_rewritable permet d’exécuter des merges et prend en charge les opérations INSERT. Les mutations et la réplication des tables ne sont pas prises en charge.

Un cas d’usage de ce type de disque concerne les tables MergeTree non répliquées. Bien que le type de disque s3 convienne aux tables MergeTree non répliquées, vous pouvez opter pour le type de disque s3_plain_rewritable si vous n’avez pas besoin de métadonnées locales pour la table et acceptez un ensemble d’opérations limité. Cela peut être utile, par exemple, pour les tables système.

Configuration :

<s3_plain_rewritable>
    <type>s3_plain_rewritable</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain_rewritable>

est égal à

<s3_plain_rewritable>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>plain_rewritable</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain_rewritable>

À partir de 24.5, il est possible de configurer n’importe quel disque de stockage objet (s3, azure, local) avec le type de métadonnées plain_rewritable.

Utilisation d’Azure Blob Storage

Les moteurs de table de la famille MergeTree peuvent stocker des données dans Azure Blob Storage à l’aide d’un disque de type azure_blob_storage.

Configuration :

<storage_configuration>
    ...
    <disks>
        <blob_storage_disk>
            <type>azure_blob_storage</type>
            <storage_account_url>http://account.blob.core.windows.net</storage_account_url>
            <container_name>container</container_name>
            <account_name>account</account_name>
            <account_key>pass123</account_key>
            <metadata_path>/var/lib/clickhouse/disks/blob_storage_disk/</metadata_path>
            <cache_path>/var/lib/clickhouse/disks/blob_storage_disk/cache/</cache_path>
            <skip_access_check>false</skip_access_check>
        </blob_storage_disk>
    </disks>
    ...
</storage_configuration>

Paramètres de connexion

Paramètre	Description	Valeur par défaut
`storage_account_url` (Obligatoire)	URL du compte de stockage Azure Blob Storage. Exemples : `http://account.blob.core.windows.net` ou `http://azurite1:10000/devstoreaccount1`.	-
`container_name`	Nom du conteneur cible.	`default-container`
`container_already_exists`	Contrôle le comportement lors de la création du conteneur : - `false` : crée un nouveau conteneur - `true` : se connecte directement à un conteneur existant - Non défini : vérifie si le conteneur existe et le crée si nécessaire	-

Paramètres d’authentification (le disque tentera d’utiliser toutes les méthodes disponibles ainsi que Managed Identity Credential) :

Paramètre	Description
`connection_string`	Pour l’authentification à l’aide d’une chaîne de connexion.
`account_name`	Pour l’authentification avec Shared Key (utilisé avec `account_key`).
`account_key`	Pour l’authentification avec Shared Key (utilisé avec `account_name`).

Paramètres de limitation

Parameter	Description
`s3_max_single_part_upload_size`	Taille maximale d’un téléversement en un seul bloc vers Blob Storage.
`min_bytes_for_seek`	Taille minimale d’une zone autorisant un seek.
`max_single_read_retries`	Nombre maximal de tentatives de lecture d’un bloc de données depuis Blob Storage.
`max_single_download_retries`	Nombre maximal de tentatives de téléchargement d’un tampon lisible depuis Blob Storage.
`thread_pool_size`	Nombre maximal de threads pour l’instanciation de `IDiskRemote`.
`s3_max_inflight_parts_for_one_file`	Nombre maximal de requêtes PUT simultanées pour un même objet.

Autres paramètres

Paramètre	Description	Valeur par défaut
`metadata_path`	Chemin du système de fichiers local où stocker les fichiers de métadonnées de Blob Storage.	`/var/lib/clickhouse/disks/<disk_name>/`
`skip_access_check`	Si `true`, ignore les vérifications d’accès au disque au démarrage.	`false`
`metadata_keep_free_space_bytes`	Quantité d’espace disque libre à réserver pour les métadonnées.	-

Vous trouverez des exemples de configurations fonctionnelles dans le répertoire des tests d’intégration (voir p. ex. test_merge_tree_azure_blob_storage ou test_azure_blob_storage_zero_copy_replication).

Utilisation du stockage HDFS (non pris en charge)

Dans cet exemple de configuration :

le disque est de type hdfs (non pris en charge)
les données sont hébergées à l’emplacement hdfs://hdfs1:9000/clickhouse/

À noter que HDFS n’est pas pris en charge et que son utilisation peut donc entraîner des problèmes. N’hésitez pas à soumettre une pull request avec le correctif si un problème survient.

<clickhouse>
    <storage_configuration>
        <disks>
            <hdfs>
                <type>hdfs</type>
                <endpoint>hdfs://hdfs1:9000/clickhouse/</endpoint>
                <skip_access_check>true</skip_access_check>
            </hdfs>
            <hdd>
                <type>local</type>
                <path>/</path>
            </hdd>
        </disks>
        <policies>
            <hdfs>
                <volumes>
                    <main>
                        <disk>hdfs</disk>
                    </main>
                    <external>
                        <disk>hdd</disk>
                    </external>
                </volumes>
            </hdfs>
        </policies>
    </storage_configuration>
</clickhouse>

Gardez à l’esprit que HDFS peut ne pas fonctionner dans certains cas particuliers.

Utilisation du chiffrement des données

Vous pouvez chiffrer les données stockées sur des disques externes S3 ou HDFS (non pris en charge), ou sur un disque local. Pour activer le mode de chiffrement, vous devez définir dans le fichier de configuration un disque de type encrypted et choisir le disque sur lequel les données seront stockées. Un disque encrypted chiffre à la volée tous les fichiers qui y sont écrits et, lorsque vous lisez des fichiers depuis un disque encrypted, il les déchiffre automatiquement. Vous pouvez donc utiliser un disque encrypted comme un disque normal.

Exemple de configuration de disque :

<disks>
  <disk1>
    <type>local</type>
    <path>/path1/</path>
  </disk1>
  <disk2>
    <type>encrypted</type>
    <disk>disk1</disk>
    <path>path2/</path>
    <key>_16_ascii_chars_</key>
  </disk2>
</disks>

Par exemple, lorsque ClickHouse écrit des données d’une table dans le fichier store/all_1_1_0/data.bin sur disk1, ce fichier est en réalité écrit sur le disque physique au chemin /path1/store/all_1_1_0/data.bin.

Lors de l’écriture du même fichier sur disk2, il est en réalité écrit sur le disque physique au chemin /path1/path2/store/all_1_1_0/data.bin, en mode chiffré.

Paramètres requis

Paramètre	Type	Description
`type`	String	Doit être défini sur `encrypted` pour créer un disque chiffré.
`disk`	String	Type de disque à utiliser pour le stockage sous-jacent.
`key`	Uint64	Clé de chiffrement et de déchiffrement. Peut être spécifiée en hexadécimal à l’aide de `key_hex`. Plusieurs clés peuvent être spécifiées via l’attribut `id`.

Paramètres facultatifs

Paramètre	Type	Par défaut	Description
`path`	String	Répertoire racine	Emplacement sur le disque où les données seront enregistrées.
`current_key_id`	String	-	ID de la clé utilisée pour le chiffrement. Toutes les clés indiquées peuvent être utilisées pour le déchiffrement.
`algorithm`	Enum	`AES_128_CTR`	Algorithme de chiffrement. Options : - `AES_128_CTR` (clé de 16 octets) - `AES_192_CTR` (clé de 24 octets) - `AES_256_CTR` (clé de 32 octets)

Exemple de configuration du disque :

<clickhouse>
    <storage_configuration>
        <disks>
            <disk_s3>
                <type>s3</type>
                <endpoint>...
            </disk_s3>
            <disk_s3_encrypted>
                <type>encrypted</type>
                <disk>disk_s3</disk>
                <algorithm>AES_128_CTR</algorithm>
                <key_hex id="0">00112233445566778899aabbccddeeff</key_hex>
                <key_hex id="1">ffeeddccbbaa99887766554433221100</key_hex>
                <current_key_id>1</current_key_id>
            </disk_s3_encrypted>
        </disks>
    </storage_configuration>
</clickhouse>

Utilisation du cache local

Il est possible de configurer un cache local pour les disques dans la configuration de stockage à partir de la version 22.3. Pour les versions 22.3 à 22.7, le cache n’est pris en charge que pour le type de disque s3. Pour les versions >= 22.8, le cache est pris en charge pour tous les types de disque : S3, Azure, Local, Encrypted, etc. Pour les versions >= 23.5, le cache n’est pris en charge que pour les types de disque distants : S3, Azure, HDFS (non pris en charge). Le cache utilise la politique de cache LRU.

Exemple de configuration pour les versions supérieures ou égales à 22.8 :

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>...</endpoint>
                ... s3 configuration ...
            </s3>
            <cache>
                <type>cache</type>
                <disk>s3</disk>
                <path>/s3_cache/</path>
                <max_size>10Gi</max_size>
            </cache>
        </disks>
        <policies>
            <s3_cache>
                <volumes>
                    <main>
                        <disk>cache</disk>
                    </main>
                </volumes>
            </s3_cache>
        <policies>
    </storage_configuration>

Exemple de configuration pour les versions antérieures à 22.8 :

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>...</endpoint>
                ... s3 configuration ...
                <data_cache_enabled>1</data_cache_enabled>
                <data_cache_max_size>10737418240</data_cache_max_size>
            </s3>
        </disks>
        <policies>
            <s3_cache>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3_cache>
        <policies>
    </storage_configuration>

Paramètres de configuration du disque pour File Cache :

Ces paramètres doivent être définis dans la section de configuration du disque.

Parameter	Type	Default	Description
`path`	String	-	Obligatoire. Chemin du répertoire où le cache sera stocké.
`max_size`	Size	-	Obligatoire. Taille maximale du cache en octets ou dans un format lisible (par ex. `10Gi`). Les fichiers sont retirés du cache selon la politique LRU lorsque la limite est atteinte. Prend en charge les formats `ki`, `Mi`, `Gi` (depuis v22.10).
`cache_on_write_operations`	Boolean	`false`	Active le cache en écriture directe pour les requêtes `INSERT` et les merges en arrière-plan. Peut être remplacé au niveau de chaque requête avec `enable_filesystem_cache_on_write_operations`.
`enable_filesystem_query_cache_limit`	Boolean	`false`	Active des limites de taille du cache par requête basées sur `max_query_cache_size`.
`enable_cache_hits_threshold`	Boolean	`false`	Lorsqu'il est activé, les données ne sont mises en cache qu'après avoir été lues plusieurs fois.
`cache_hits_threshold`	Integer	`0`	Nombre de lectures requis avant la mise en cache des données (nécessite `enable_cache_hits_threshold`).
`enable_bypass_cache_with_threshold`	Boolean	`false`	Ignore le cache pour les grandes plages de lecture.
`bypass_cache_threshold`	Size	`256Mi`	Taille de plage de lecture qui déclenche le contournement du cache (nécessite `enable_bypass_cache_with_threshold`).
`max_file_segment_size`	Size	`8Mi`	Taille maximale d'un fichier de cache unique en octets ou dans un format lisible.
`max_elements`	Integer	`10000000`	Nombre maximal de fichiers de cache.
`load_metadata_threads`	Integer	`16`	Nombre de threads utilisés pour charger les métadonnées du cache au démarrage.
`use_split_cache`	Boolean	`false`	Sépare les fichiers système des fichiers de données.
`split_cache_ratio`	Double	`0.1`	Ratio du segment système par rapport à la taille totale du cache pour split_cache.

Remarque : les valeurs de taille prennent en charge des unités comme ki, Mi, Gi, etc. (par ex. 10Gi).

Paramètres de requête/profil de File Cache

Paramètre	Type	Par défaut	Description
`enable_filesystem_cache`	Boolean	`true`	Active ou désactive l’utilisation du cache pour chaque requête, même avec un type de disque `cache`.
`read_from_filesystem_cache_if_exists_otherwise_bypass_cache`	Boolean	`false`	Lorsqu’il est activé, utilise le cache uniquement si les données existent ; les nouvelles données ne seront pas mises en cache.
`enable_filesystem_cache_on_write_operations`	Boolean	`false` (Cloud : `true`)	Active le cache en écriture. Nécessite `cache_on_write_operations` dans la configuration du cache.
`enable_filesystem_cache_log`	Boolean	`false`	Active la journalisation détaillée de l’utilisation du cache dans `system.filesystem_cache_log`.
`filesystem_cache_allow_background_download`	Boolean	`true`	Permet de terminer en arrière-plan les segments partiellement téléchargés. Désactivez cette option pour que les téléchargements restent au premier plan pour la requête/session en cours.
`max_query_cache_size`	Size	`false`	Taille maximale du cache par requête. Nécessite `enable_filesystem_query_cache_limit` dans la configuration du cache.
`filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit`	Boolean	`true`	Contrôle le comportement lorsque `max_query_cache_size` est atteint : - `true` : arrête le téléchargement de nouvelles données - `false` : évince les anciennes données pour libérer de l’espace pour les nouvelles données

Tables système du cache du système de fichiers

Nom de la table	Description	Prérequis
`system.filesystem_cache`	Affiche l’état actuel du cache du système de fichiers.	Aucun
`system.filesystem_cache_log`	Fournit des statistiques détaillées sur l’utilisation du cache par requête.	Nécessite `enable_filesystem_cache_log = true`

Commandes du cache

`SYSTEM CLEAR|DROP FILESYSTEM CACHE (<cache_name>) (ON CLUSTER)` – `ON CLUSTER`

Cette commande n’est prise en charge que si aucun <cache_name> n’est spécifié.

`SHOW FILESYSTEM CACHES`

Affiche la liste des caches du système de fichiers configurés sur le serveur. (Pour les versions inférieures ou égales à 22.8, la commande s'appelle SHOW CACHES)

Querysql

SHOW FILESYSTEM CACHES

Responsetext

┌─Caches────┐
│ s3_cache  │
└───────────┘

`DESCRIBE FILESYSTEM CACHE '<cache_name>'`

Affiche la configuration du cache et quelques statistiques générales pour un cache donné. Le nom du cache peut être obtenu à l’aide de la commande SHOW FILESYSTEM CACHES. (Pour les versions inférieures ou égales à 22.8, la commande s’appelle DESCRIBE CACHE)

Querysql

DESCRIBE FILESYSTEM CACHE 's3_cache'

Responsetext

┌────max_size─┬─max_elements─┬─max_file_segment_size─┬─boundary_alignment─┬─cache_on_write_operations─┬─cache_hits_threshold─┬─current_size─┬─current_elements─┬─path───────┬─background_download_threads─┬─enable_bypass_cache_with_threshold─┐
│ 10000000000 │      1048576 │             104857600 │            4194304 │                         1 │                    0 │         3276 │               54 │ /s3_cache/ │                           2 │                                  0 │
└─────────────┴──────────────┴───────────────────────┴────────────────────┴───────────────────────────┴──────────────────────┴──────────────┴──────────────────┴────────────┴─────────────────────────────┴────────────────────────────────────┘

Métriques actuelles du cache	Métriques asynchrones du cache	Événements de profilage du cache
`FilesystemCacheSize`	`FilesystemCacheBytes`	`CachedReadBufferReadFromSourceBytes`, `CachedReadBufferReadFromCacheBytes`
`FilesystemCacheElements`	`FilesystemCacheFiles`	`CachedReadBufferReadFromSourceMicroseconds`, `CachedReadBufferReadFromCacheMicroseconds`
		`CachedReadBufferCacheWriteBytes`, `CachedReadBufferCacheWriteMicroseconds`
		`CachedWriteBufferCacheWriteBytes`, `CachedWriteBufferCacheWriteMicroseconds`

Utilisation du stockage Web statique (lecture seule)

Il s’agit d’un disque en lecture seule. Ses données sont uniquement consultées et ne sont jamais modifiées. Une nouvelle table est chargée sur ce disque via la requête ATTACH TABLE (voir l’exemple ci-dessous). Le disque local n’est en fait pas utilisé : chaque requête SELECT entraîne une requête http pour récupérer les données nécessaires. Toute modification des données de la table entraîne une exception, c.-à-d. que les types de requêtes suivants ne sont pas autorisés : CREATE TABLE, ALTER TABLE, RENAME TABLE, DETACH TABLE et TRUNCATE TABLE. Le stockage Web peut être utilisé en lecture seule. Il peut par exemple servir à héberger des données d’exemple ou à migrer des données. Il existe un outil clickhouse-static-files-uploader, qui prépare un répertoire de données pour une table donnée (SELECT data_paths FROM system.tables WHERE name = 'table_name'). Pour chaque table dont vous avez besoin, vous obtenez un répertoire de fichiers. Ces fichiers peuvent être téléversés vers, par exemple, un serveur web servant des fichiers statiques. Après cette préparation, vous pouvez charger cette table sur n’importe quel serveur ClickHouse via DiskWeb.

Dans cet exemple de configuration :

le disque est de type web
les données sont hébergées à http://nginx:80/test1/
un cache sur le stockage local est utilisé

<clickhouse>
    <storage_configuration>
        <disks>
            <web>
                <type>web</type>
                <endpoint>http://nginx:80/test1/</endpoint>
            </web>
            <cached_web>
                <type>cache</type>
                <disk>web</disk>
                <path>cached_web_cache/</path>
                <max_size>100000000</max_size>
            </cached_web>
        </disks>
        <policies>
            <web>
                <volumes>
                    <main>
                        <disk>web</disk>
                    </main>
                </volumes>
            </web>
            <cached_web>
                <volumes>
                    <main>
                        <disk>cached_web</disk>
                    </main>
                </volumes>
            </cached_web>
        </policies>
    </storage_configuration>
</clickhouse>

Dans cette requête ATTACH TABLE, le UUID fourni correspond au nom du répertoire de données, et l’endpoint est l’URL du contenu brut de GitHub.

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
      type=web,
      endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
      );

Un cas de test prêt à l’emploi. Vous devez ajouter cette configuration à la config :

<clickhouse>
    <storage_configuration>
        <disks>
            <web>
                <type>web</type>
                <endpoint>https://clickhouse-datasets.s3.yandex.net/disk-with-static-files-tests/test-hits/</endpoint>
            </web>
        </disks>
        <policies>
            <web>
                <volumes>
                    <main>
                        <disk>web</disk>
                    </main>
                </volumes>
            </web>
        </policies>
    </storage_configuration>
</clickhouse>

Ensuite, exécutez cette requête :

ATTACH TABLE test_hits UUID '1ae36516-d62d-4218-9ae3-6516d62da218'
(
    WatchID UInt64,
    JavaEnable UInt8,
    Title String,
    GoodEvent Int16,
    EventTime DateTime,
    EventDate Date,
    CounterID UInt32,
    ClientIP UInt32,
    ClientIP6 FixedString(16),
    RegionID UInt32,
    UserID UInt64,
    CounterClass Int8,
    OS UInt8,
    UserAgent UInt8,
    URL String,
    Referer String,
    URLDomain String,
    RefererDomain String,
    Refresh UInt8,
    IsRobot UInt8,
    RefererCategories Array(UInt16),
    URLCategories Array(UInt16),
    URLRegions Array(UInt32),
    RefererRegions Array(UInt32),
    ResolutionWidth UInt16,
    ResolutionHeight UInt16,
    ResolutionDepth UInt8,
    FlashMajor UInt8,
    FlashMinor UInt8,
    FlashMinor2 String,
    NetMajor UInt8,
    NetMinor UInt8,
    UserAgentMajor UInt16,
    UserAgentMinor FixedString(2),
    CookieEnable UInt8,
    JavascriptEnable UInt8,
    IsMobile UInt8,
    MobilePhone UInt8,
    MobilePhoneModel String,
    Params String,
    IPNetworkID UInt32,
    TraficSourceID Int8,
    SearchEngineID UInt16,
    SearchPhrase String,
    AdvEngineID UInt8,
    IsArtifical UInt8,
    WindowClientWidth UInt16,
    WindowClientHeight UInt16,
    ClientTimeZone Int16,
    ClientEventTime DateTime,
    SilverlightVersion1 UInt8,
    SilverlightVersion2 UInt8,
    SilverlightVersion3 UInt32,
    SilverlightVersion4 UInt16,
    PageCharset String,
    CodeVersion UInt32,
    IsLink UInt8,
    IsDownload UInt8,
    IsNotBounce UInt8,
    FUniqID UInt64,
    HID UInt32,
    IsOldCounter UInt8,
    IsEvent UInt8,
    IsParameter UInt8,
    DontCountHits UInt8,
    WithHash UInt8,
    HitColor FixedString(1),
    UTCEventTime DateTime,
    Age UInt8,
    Sex UInt8,
    Income UInt8,
    Interests UInt16,
    Robotness UInt8,
    GeneralInterests Array(UInt16),
    RemoteIP UInt32,
    RemoteIP6 FixedString(16),
    WindowName Int32,
    OpenerName Int32,
    HistoryLength Int16,
    BrowserLanguage FixedString(2),
    BrowserCountry FixedString(2),
    SocialNetwork String,
    SocialAction String,
    HTTPError UInt16,
    SendTiming Int32,
    DNSTiming Int32,
    ConnectTiming Int32,
    ResponseStartTiming Int32,
    ResponseEndTiming Int32,
    FetchTiming Int32,
    RedirectTiming Int32,
    DOMInteractiveTiming Int32,
    DOMContentLoadedTiming Int32,
    DOMCompleteTiming Int32,
    LoadEventStartTiming Int32,
    LoadEventEndTiming Int32,
    NSToDOMContentLoadedTiming Int32,
    FirstPaintTiming Int32,
    RedirectCount Int8,
    SocialSourceNetworkID UInt8,
    SocialSourcePage String,
    ParamPrice Int64,
    ParamOrderID String,
    ParamCurrency FixedString(3),
    ParamCurrencyID UInt16,
    GoalsReached Array(UInt32),
    OpenstatServiceName String,
    OpenstatCampaignID String,
    OpenstatAdID String,
    OpenstatSourceID String,
    UTMSource String,
    UTMMedium String,
    UTMCampaign String,
    UTMContent String,
    UTMTerm String,
    FromTag String,
    HasGCLID UInt8,
    RefererHash UInt64,
    URLHash UInt64,
    CLID UInt32,
    YCLID UInt64,
    ShareService String,
    ShareURL String,
    ShareTitle String,
    ParsedParams Nested(
        Key1 String,
        Key2 String,
        Key3 String,
        Key4 String,
        Key5 String,
        ValueDouble Float64),
    IslandID FixedString(16),
    RequestNum UInt32,
    RequestTry UInt8
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(EventDate)
ORDER BY (CounterID, EventDate, intHash32(UserID))
SAMPLE BY intHash32(UserID)
SETTINGS storage_policy='web';

Paramètres requis

Paramètre	Description
`type`	`web`. Sinon, le disque n’est pas créé.
`endpoint`	L’URL de l’endpoint au format `path`. L’URL de l’endpoint doit contenir un chemin racine pour stocker les données à l’endroit où elles ont été téléversées.

Paramètres facultatifs

Paramètre	Description	Valeur par défaut
`min_bytes_for_seek`	Le nombre minimal d’octets pour utiliser l’opération de seek au lieu d’une lecture séquentielle	`1` MB
`remote_fs_read_backoff_threashold`	Le temps d’attente maximal lors d’une tentative de lecture de données depuis le disque distant	`10000` secondes
`remote_fs_read_backoff_max_tries`	Le nombre maximal de tentatives de lecture avec backoff	`5`

Si une requête échoue avec une exception DB:Exception Unreachable URL, vous pouvez essayer d’ajuster les paramètres suivants : http_connection_timeout, http_receive_timeout, keep_alive_timeout.

Pour obtenir les fichiers à téléverser, exécutez : clickhouse static-files-disk-uploader --metadata-path <path> --output-dir <dir> (--metadata-path peut être trouvé dans la requête SELECT data_paths FROM system.tables WHERE name = 'table_name').

Lors du chargement des fichiers via endpoint, ils doivent être chargés dans le chemin <endpoint>/store/, mais la configuration ne doit contenir que endpoint.

Si l’URL n’est pas accessible lors du chargement du disque pendant le démarrage des tables par le serveur, toutes les erreurs sont interceptées. Si, dans ce cas, des erreurs se sont produites, les tables peuvent être rechargées (et redevenir visibles) via DETACH TABLE table_name -> ATTACH TABLE table_name. Si les métadonnées ont été chargées avec succès au démarrage du serveur, les tables sont alors disponibles immédiatement.

Utilisez le paramètre http_max_single_read_retries pour limiter le nombre maximal de tentatives pendant une seule lecture HTTP.

Réplication zero-copy (pas prête pour la production)

La réplication zero-copy est possible, mais déconseillée, avec les disques S3 et HDFS (non pris en charge). La réplication zero-copy signifie que, si les données sont stockées à distance sur plusieurs machines et doivent être synchronisées, seules les métadonnées sont répliquées (les chemins d'accès aux parties de données), et non les données elles-mêmes.

Disques externes pour stocker des données

Configurer le stockage externe

refresh_parts_interval et table_disk

Configuration dynamique

Utiliser le stockage S3

Paramètres requis

Paramètres facultatifs

Utilisation du stockage simple

Utilisation du stockage S3 Plain Rewritable

Utilisation d’Azure Blob Storage

Paramètres de connexion

Paramètres de limitation

Autres paramètres

Utilisation du stockage HDFS (non pris en charge)

Utilisation du chiffrement des données

Paramètres requis

Paramètres facultatifs

Utilisation du cache local

Paramètres de requête/profil de File Cache

Tables système du cache du système de fichiers

Commandes du cache

SYSTEM CLEAR|DROP FILESYSTEM CACHE (<cache_name>) (ON CLUSTER) – ON CLUSTER

SHOW FILESYSTEM CACHES

DESCRIBE FILESYSTEM CACHE '<cache_name>'

Utilisation du stockage Web statique (lecture seule)

Paramètres requis

Paramètres facultatifs

Réplication zero-copy (pas prête pour la production)

`SYSTEM CLEAR|DROP FILESYSTEM CACHE (<cache_name>) (ON CLUSTER)` – `ON CLUSTER`

`SHOW FILESYSTEM CACHES`

`DESCRIBE FILESYSTEM CACHE '<cache_name>'`