> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Documentation de highlight-next-line
# 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 :
1. Le stockage objet [Amazon S3](https://aws.amazon.com/s3/).
2. [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs).
3. Non pris en charge : Hadoop Distributed File System ([HDFS](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/HdfsDesign.html))
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](/fr/reference/engines/table-engines/integrations/s3).
2. pour utiliser des données stockées dans Azure Blob Storage, utilisez le moteur de table [AzureBlobStorage](/fr/reference/engines/table-engines/integrations/azureBlobStorage).
3. pour utiliser des données dans Hadoop Distributed File System (non pris en charge), utilisez le moteur de table [HDFS](/fr/reference/engines/table-engines/integrations/hdfs).
## Configurer le stockage externe
Les moteurs de table des familles [`MergeTree`](/fr/reference/engines/table-engines/mergetree-family/mergetree) et [`Log`](/fr/reference/engines/table-engines/log-family/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](/fr/concepts/features/configuration/server-config/storing-data#plain-storage). 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 :
```xml theme={null}
s3
https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/
1
```
correspond à la configuration suivante (depuis la version `24.1`) :
```xml theme={null}
object_storage
s3
local
https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/
1
```
La configuration suivante :
```xml theme={null}
s3_plain
https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/
1
```
est égal à :
```xml theme={null}
object_storage
s3
plain
https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/
1
```
Voici un exemple de configuration complète du stockage :
```xml theme={null}
s3
https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/
1
s3
```
À partir de la version 24.1, cela peut aussi se présenter ainsi :
```xml theme={null}
object_storage
s3
local
https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/
1
s3
```
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 :
```xml theme={null}
s3
```
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 :
```sql theme={null}
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.
```sql theme={null}
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.
```sql highlight={20-23} theme={null}
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.
```sql highlight={20-28} theme={null}
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 :
```sql highlight={20-28} theme={null}
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 :
```xml theme={null}
web
'https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
```
### Utiliser le stockage S3
#### Paramètres requis
| Paramètre | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `endpoint` | URL de l'endpoint S3 de type `path` ou `virtual hosted` [styles](https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html). 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//` |
| `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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html). 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](/fr/concepts/features/configuration/server-config/workload-scheduling). | Chaîne vide (désactivé) |
| `write_resource` | Nom de la ressource pour les requêtes d’écriture [ordonnancement](/fr/concepts/features/configuration/server-config/workload-scheduling). | 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](https://github.com/google/re2/wiki/Syntax). 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](/fr/integrations/connectors/data-sources/gcs).
### 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 :
```xml theme={null}
s3_plain
https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/
1
```
À 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 :
```xml theme={null}
object_storage
azure
plain
https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/
1
```
### 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](/fr/reference/statements/alter/index#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 :
```xml theme={null}
s3_plain_rewritable
https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/
1
```
est égal à
```xml theme={null}
object_storage
s3
plain_rewritable
https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/
1
```
À 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](https://azure.microsoft.com/en-us/services/storage/blobs/)
à l’aide d’un disque de type `azure_blob_storage`.
Configuration :
```xml theme={null}
...
azure_blob_storage
http://account.blob.core.windows.net
container
account
pass123
/var/lib/clickhouse/disks/blob_storage_disk/
/var/lib/clickhouse/disks/blob_storage_disk/cache/
false
...
```
#### 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//` |
| `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](/fr/concepts/features/configuration/server-config/workload-scheduling) des requêtes de lecture. | Chaîne vide (désactivé) |
| `write_resource` | Nom de la ressource pour l’[ordonnancement](/fr/concepts/features/configuration/server-config/workload-scheduling) 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](https://github.com/ClickHouse/ClickHouse/blob/master/tests/integration/test_merge_tree_azure_blob_storage/configs/config.d/storage_conf.xml) ou [test\_azure\_blob\_storage\_zero\_copy\_replication](https://github.com/ClickHouse/ClickHouse/blob/master/tests/integration/test_azure_blob_storage_zero_copy_replication/configs/config.d/storage_conf.xml)).
**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.
```xml theme={null}
hdfs
hdfs://hdfs1:9000/clickhouse/
true
local
/
hdfs
hdd
```
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](/fr/reference/engines/table-engines/mergetree-family/mergetree#table_engine-mergetree-s3) ou [HDFS](#using-hdfs-storage-unsupported) (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 :
```xml theme={null}
local
/path1/
encrypted
disk1
path2/
_16_ascii_chars_
```
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 :
```xml theme={null}
s3
...
encrypted
disk_s3
AES_128_CTR
00112233445566778899aabbccddeeff
ffeeddccbbaa99887766554433221100
1
```
### 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 :
```xml theme={null}
s3
...
... s3 configuration ...
cache
s3
/s3_cache/
10Gi
cache
```
Exemple de configuration pour les versions antérieures à 22.8 :
```xml theme={null}
s3
...
... s3 configuration ...
1
10737418240
s3
```
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 () (ON CLUSTER)` -- `ON CLUSTER`
Cette commande n’est prise en charge que si aucun `` 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`)
```sql title="Query" theme={null}
SHOW FILESYSTEM CACHES
```
```text title="Response" theme={null}
┌─Caches────┐
│ s3_cache │
└───────────┘
```
##### `DESCRIBE FILESYSTEM CACHE ''`
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`)
```sql title="Query" theme={null}
DESCRIBE FILESYSTEM CACHE 's3_cache'
```
```text title="Response" theme={null}
┌────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`](/fr/reference/statements/create/table),
[`ALTER TABLE`](/fr/reference/statements/alter/index), [`RENAME TABLE`](/fr/reference/statements/rename#rename-table),
[`DETACH TABLE`](/fr/reference/statements/detach) et [`TRUNCATE TABLE`](/fr/reference/statements/truncate).
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é
```xml theme={null}
web
http://nginx:80/test1/
cache
web
cached_web_cache/
100000000
web
cached_web
```
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](#dynamic-configuration) et évitez
de modifier le fichier de configuration.
Un [jeu de données de démonstration](https://github.com/ClickHouse/web-tables-demo) est hébergé sur GitHub. Pour préparer vos propres tables pour le
stockage web, consultez l’outil [clickhouse-static-files-uploader](/fr/concepts/features/tools-and-utilities/static-files-disk-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.
```sql highlight={1,20-23} theme={null}
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 :
```xml theme={null}
web
https://clickhouse-datasets.s3.yandex.net/disk-with-static-files-tests/test-hits/
web
```
Ensuite, exécutez cette requête :
```sql theme={null}
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](/fr/reference/settings/session-settings#http_connection_timeout), [http\_receive\_timeout](/fr/reference/settings/session-settings#http_receive_timeout), [keep\_alive\_timeout](/fr/reference/settings/server-settings/settings#keep_alive_timeout).
Pour obtenir les fichiers à téléverser, exécutez :
`clickhouse static-files-disk-uploader --metadata-path --output-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 `/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](/fr/concepts/features/configuration/server-config/storing-data#web-storage) 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.