Disques externes pour stocker des données

Documentation de highlight-next-line

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 :

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

ClickHouse prend également en charge des moteurs de table externes, qui diffèrent de l’option de stockage externe décrite sur cette page, car ils permettent de lire des données stockées dans un format de fichier générique (comme Parquet). Cette page décrit la configuration du stockage pour les tables de la famille MergeTree ou de la famille Log.

1. pour utiliser des données stockées sur des disques Amazon S3, utilisez le moteur de table S3.
2. pour utiliser des données stockées dans Azure Blob Storage, utilisez le moteur de table AzureBlobStorage.
3. pour utiliser des données dans Hadoop Distributed File System (non pris en charge), utilisez le moteur de table 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 :

1. Une section type, égale à l’une des valeurs s3, azure_blob_storage, hdfs (non pris en charge), local_blob_storage, web.
2. 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 :

1. Un type égal à object_storage
2. 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 plain. 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.

refresh_parts_interval n’est pas utilisé pour les tables ReplicatedMergeTree. Les tables répliquées synchronisent déjà les parts via le mécanisme de réplication. Ce paramètre s’applique uniquement aux tables MergeTree non répliquées dans lesquelles des parts sont écrites en externe et où un rechargement des métadonnées est nécessaire.

​

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.

L’exemple utilise type=web, mais tout type de disque peut être configuré comme dynamique, y compris un disque local. Les disques locaux exigent qu’un argument path soit défini dans le paramètre de config du server custom_local_disks_base_directory, qui n’a pas de valeur par défaut ; définissez donc également ce paramètre lorsque vous utilisez un disque local.

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 le point de terminaison 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
read_resource	Nom de la ressource pour les requêtes de lecture ordonnancement.	Chaîne vide (désactivé)
write_resource	Nom de la ressource pour les requêtes d’écriture ordonnancement.	Chaîne vide (désactivé)
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.	-

Google Cloud Storage (GCS) est également pris en charge via le type s3. Voir GCS backed MergeTree.

​

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
read_resource	Nom de la ressource pour l’ordonnancement des requêtes de lecture.	Chaîne vide (désactivé)
write_resource	Nom de la ressource pour l’ordonnancement des requêtes d’écriture.	Chaîne vide (désactivé)
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).

La réplication zero-copy n’est pas prête pour la production

La réplication zero-copy est désactivée par défaut dans ClickHouse version 22.8 et ultérieure. Cette fonctionnalité n’est pas recommandée pour une utilisation en production.

​

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

Les paramètres de configuration du cache et les paramètres de requête du cache correspondent à la dernière version de ClickHouse ; certaines fonctionnalités peuvent ne pas être prises en charge dans les versions antérieures.

​

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)

Query

SHOW FILESYSTEM CACHES

Response

┌─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)

Query

DESCRIBE FILESYSTEM CACHE 's3_cache'

Response

┌────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>

Le stockage peut aussi être configuré temporairement dans une requête. Si un jeu de données web n’est pas destiné à être utilisé régulièrement, consultez la configuration dynamique et évitez de modifier le fichier de configuration.

Un jeu de données de démonstration est hébergé sur GitHub. Pour préparer vos propres tables pour le stockage web, consultez l’outil clickhouse-static-files-uploader

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.

La réplication zero-copy n’est pas prête pour la production

La réplication zero-copy est désactivée par défaut dans ClickHouse version 22.8 et ultérieure. Cette fonctionnalité n’est pas recommandée en production.