`.
Remarque : lors de l’utilisation de la stratégie de partitionnement `HIVE`, le paramètre `use_hive_partitioning` n’a aucun effet.
Exemple de stratégie de partitionnement `HIVE` :
```sql theme={null}
arthur :) CREATE TABLE t_03363_parquet (year UInt16, country String, counter UInt8)
ENGINE = S3(s3_conn, filename = 't_03363_parquet', format = Parquet, partition_strategy='hive')
PARTITION BY (year, country);
arthur :) INSERT INTO t_03363_parquet VALUES
(2022, 'USA', 1),
(2022, 'Canada', 2),
(2023, 'USA', 3),
(2023, 'Mexico', 4),
(2024, 'France', 5),
(2024, 'Germany', 6),
(2024, 'Germany', 7),
(1999, 'Brazil', 8),
(2100, 'Japan', 9),
(2024, 'CN', 10),
(2025, '', 11);
arthur :) select _path, * from t_03363_parquet;
┌─_path──────────────────────────────────────────────────────────────────────┬─year─┬─country─┬─counter─┐
1. │ test/t_03363_parquet/year=2100/country=Japan/7329604473272971264.parquet │ 2100 │ Japan │ 9 │
2. │ test/t_03363_parquet/year=2024/country=France/7329604473323302912.parquet │ 2024 │ France │ 5 │
3. │ test/t_03363_parquet/year=2022/country=Canada/7329604473314914304.parquet │ 2022 │ Canada │ 2 │
4. │ test/t_03363_parquet/year=1999/country=Brazil/7329604473289748480.parquet │ 1999 │ Brazil │ 8 │
5. │ test/t_03363_parquet/year=2023/country=Mexico/7329604473293942784.parquet │ 2023 │ Mexico │ 4 │
6. │ test/t_03363_parquet/year=2023/country=USA/7329604473319108608.parquet │ 2023 │ USA │ 3 │
7. │ test/t_03363_parquet/year=2025/country=/7329604473327497216.parquet │ 2025 │ │ 11 │
8. │ test/t_03363_parquet/year=2024/country=CN/7329604473310720000.parquet │ 2024 │ CN │ 10 │
9. │ test/t_03363_parquet/year=2022/country=USA/7329604473298137088.parquet │ 2022 │ USA │ 1 │
10. │ test/t_03363_parquet/year=2024/country=Germany/7329604473306525696.parquet │ 2024 │ Germany │ 6 │
11. │ test/t_03363_parquet/year=2024/country=Germany/7329604473306525696.parquet │ 2024 │ Germany │ 7 │
└────────────────────────────────────────────────────────────────────────────┴──────┴─────────┴─────────┘
```
### Interroger des données partitionnées
Cet exemple utilise la [recette Docker Compose](https://github.com/ClickHouse/examples/tree/5fdc6ff72f4e5137e23ea075c88d3f44b0202490/docker-compose-recipes/recipes/ch-and-minio-S3), qui intègre ClickHouse et MinIO. Vous devriez pouvoir reproduire les mêmes requêtes avec S3 en remplaçant les valeurs de l'endpoint et de l'authentification.
Notez que l'endpoint S3 dans la configuration `ENGINE` utilise le jeton de paramètre `{_partition_id}` comme partie de l'objet S3 (nom de fichier), et que les requêtes SELECT portent sur les noms d'objet ainsi générés (par exemple, `test_3.csv`).
Comme le montre l'exemple, l'interrogation de tables S3 partitionnées
n'est pas directement prise en charge pour le moment, mais peut être réalisée en interrogeant les partitions individuelles
à l'aide de la fonction de table S3.
Le principal cas d'usage de l'écriture de
données partitionnées dans S3 est de permettre le transfert de ces données vers un autre
système ClickHouse (par exemple, lors d'une migration d'un environnement on-prem vers ClickHouse
Cloud). Comme les jeux de données ClickHouse sont souvent très volumineux et que la fiabilité du
réseau n'est pas toujours parfaite, il est logique de transférer les jeux de données
par sous-ensembles, d'où l'intérêt des écritures partitionnées.
#### Créer la table
```sql highlight={8} theme={null}
CREATE TABLE p
(
`column1` UInt32,
`column2` UInt32,
`column3` UInt32
)
ENGINE = S3(
'http://minio:10000/clickhouse//test_{_partition_id}.csv',
'minioadmin',
'minioadminpassword',
'CSV')
PARTITION BY column3
```
#### Insérer des données
```sql theme={null}
INSERT INTO p VALUES (1, 2, 3), (3, 2, 1), (78, 43, 45)
```
#### Sélectionner dans la partition 3
Cette requête utilise la fonction de table S3
```sql theme={null}
SELECT *
FROM s3('http://minio:10000/clickhouse//test_3.csv', 'minioadmin', 'minioadminpassword', 'CSV')
```
```response theme={null}
┌─c1─┬─c2─┬─c3─┐
│ 1 │ 2 │ 3 │
└────┴────┴────┘
```
#### Sélectionner dans la partition 1
```sql theme={null}
SELECT *
FROM s3('http://minio:10000/clickhouse//test_1.csv', 'minioadmin', 'minioadminpassword', 'CSV')
```
```response theme={null}
┌─c1─┬─c2─┬─c3─┐
│ 3 │ 2 │ 1 │
└────┴────┴────┘
```
#### Sélectionner dans la partition 45
```sql theme={null}
SELECT *
FROM s3('http://minio:10000/clickhouse//test_45.csv', 'minioadmin', 'minioadminpassword', 'CSV')
```
```response theme={null}
┌─c1─┬─c2─┬─c3─┐
│ 78 │ 43 │ 45 │
└────┴────┴────┘
```
#### Limitation
Vous serez peut-être tenté d’essayer `Select * from p`, mais, comme indiqué ci-dessus, cette requête échouera ; utilisez plutôt la requête précédente.
```sql theme={null}
SELECT * FROM p
```
```response theme={null}
Received exception from server (version 23.4.1):
Code: 48. DB::Exception: Received from localhost:9000. DB::Exception: Reading from a partitioned S3 storage is not implemented yet. (NOT_IMPLEMENTED)
```
## Insérer des données
Notez que les lignes ne peuvent être insérées que dans de nouveaux fichiers. Il n’existe ni cycles de fusion ni opérations de fractionnement de fichiers. Une fois un fichier écrit, les insertions ultérieures échouent. Pour éviter cela, vous pouvez utiliser les paramètres `s3_truncate_on_insert` et `s3_create_new_file_on_insert`. Voir plus de détails [ici](/fr/integrations/connectors/data-ingestion/AWS/integrating-s3-with-clickhouse#inserting-data).
## Colonnes virtuelles
* `_path` — Chemin du fichier. Type : `LowCardinality(String)`.
* `_file` — Nom du fichier. Type : `LowCardinality(String)`.
* `_size` — Taille du fichier en octets. Type : `Nullable(UInt64)`. Si la taille est inconnue, la valeur est `NULL`.
* `_time` — Date et heure de dernière modification du fichier. Type : `Nullable(DateTime)`. Si l'heure est inconnue, la valeur est `NULL`.
* `_etag` — ETag du fichier. Type : `LowCardinality(String)`. Si l'ETag est inconnu, la valeur est `NULL`.
* `_tags` — Tags du fichier. Type : `Map(String, String)`. S'il n'existe aucun tag, la valeur est une map vide \`{}'.
Pour plus d'informations sur les colonnes virtuelles, consultez [ici](/fr/reference/engines/table-engines/index#table_engines-virtual_columns).
## Détails d’implémentation
* Les lectures et les écritures peuvent s’effectuer en parallèle
* Non pris en charge :
* Les opérations `ALTER` et `SELECT...SAMPLE`.
* Les index.
* La réplication [zero-copy](/fr/concepts/features/configuration/server-config/storing-data#zero-copy) est possible, mais n’est pas prise en charge.
**La réplication zero-copy n’est pas prête pour un usage en 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.
## Caractères génériques dans le chemin
L’argument `path` peut spécifier plusieurs fichiers à l’aide de caractères génériques de type bash. Pour être traité, un fichier doit exister et correspondre au motif de chemin complet. La liste des fichiers est déterminée lors du `SELECT` (et non au moment du `CREATE`).
* `*` — Remplace n’importe quelle suite de caractères, à l’exception de `/`, y compris la chaîne vide.
* `**` — Remplace n’importe quelle suite de caractères, y compris `/`, y compris la chaîne vide.
* `?` — Remplace un seul caractère quelconque.
* `{some_string,another_string,yet_another_one}` — Remplace l’une des chaînes `'some_string', 'another_string', 'yet_another_one'`.
* `{N..M}` — Remplace n’importe quel nombre dans l’intervalle de N à M, bornes incluses. N et M peuvent comporter des zéros initiaux, par exemple `000..078`.
Les constructions avec `{}` sont similaires à la fonction de table [remote](/fr/reference/functions/table-functions/remote).
Si la liste des fichiers contient des intervalles numériques avec des zéros initiaux, utilisez la construction avec des accolades pour chaque chiffre séparément ou utilisez `?`.
**Exemple avec des caractères génériques 1**
Créez une table avec des fichiers nommés `file-000.csv`, `file-001.csv`, ... , `file-999.csv` :
```sql theme={null}
CREATE TABLE big_table (name String, value UInt32)
ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/my_folder/file-{000..999}.csv', 'CSV');
```
**Exemple avec des caractères génériques 2**
Supposons que nous ayons plusieurs fichiers au format CSV avec les URI suivantes sur S3 :
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_1.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_1.csv\');
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_2.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_2.csv\');
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_3.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/some\_folder/some\_file\_3.csv\');
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_1.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_1.csv\');
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_2.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_2.csv\');
* '[https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_3.csv\'](https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/another\_folder/some\_file\_3.csv\');
Il existe plusieurs façons de créer une table à partir de ces six fichiers :
1. Indiquez une plage de suffixes de fichiers :
```sql theme={null}
CREATE TABLE table_with_range (name String, value UInt32)
ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/some_file_{1..3}', 'CSV');
```
2. Prenez tous les fichiers portant le préfixe `some_file_` (il ne doit y avoir aucun fichier supplémentaire portant ce préfixe dans les deux dossiers) :
```sql theme={null}
CREATE TABLE table_with_question_mark (name String, value UInt32)
ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/some_file_?', 'CSV');
```
3. Prenez tous les fichiers dans les deux dossiers (tous les fichiers doivent respecter le format et le schéma décrits dans la requête) :
```sql theme={null}
CREATE TABLE table_with_asterisk (name String, value UInt32)
ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/*', 'CSV');
```
## Paramètres de stockage
* [s3\_truncate\_on\_insert](/fr/reference/settings/session-settings#s3_truncate_on_insert) - permet de tronquer le fichier avant d’y effectuer une insertion. Désactivé par défaut.
* [s3\_create\_new\_file\_on\_insert](/fr/reference/settings/session-settings#s3_create_new_file_on_insert) - permet de créer un nouveau fichier à chaque insertion si le format comporte un suffixe. Désactivé par défaut.
* [s3\_skip\_empty\_files](/fr/reference/settings/session-settings#s3_skip_empty_files) - permet d’ignorer les fichiers vides lors de la lecture. Activé par défaut.
## Paramètres liés à S3
Les paramètres suivants peuvent être définis avant l’exécution de la requête ou placés dans le fichier de configuration.
* `s3_max_single_part_upload_size` — Taille maximale de l’objet à téléverser vers S3 en une seule partie. La valeur par défaut est `32Mb`.
* `s3_min_upload_part_size` — Taille minimale de la partie à téléverser lors d’un téléversement multipartie vers [S3 Multipart upload](https://docs.aws.amazon.com/AmazonS3/latest/dev/uploadobjusingmpu.html). La valeur par défaut est `16Mb`.
* `s3_max_redirects` — Nombre maximal de redirections S3 autorisées. La valeur par défaut est `10`.
* `s3_single_read_retries` — Nombre maximal de tentatives pour une lecture unique. La valeur par défaut est `4`.
* `s3_max_put_rps` — Taux maximal de requêtes PUT par seconde avant limitation. La valeur par défaut est `0` (illimité).
* `s3_max_put_burst` — Nombre maximal de requêtes pouvant être émises simultanément avant d’atteindre la limite de requêtes par seconde. Par défaut (valeur `0`), il est égal à `s3_max_put_rps`.
* `s3_max_get_rps` — Taux maximal de requêtes GET par seconde avant limitation. La valeur par défaut est `0` (illimité).
* `s3_max_get_burst` — Nombre maximal de requêtes pouvant être émises simultanément avant d’atteindre la limite de requêtes par seconde. Par défaut (valeur `0`), il est égal à `s3_max_get_rps`.
* `s3_upload_part_size_multiply_factor` - Multiplie `s3_min_upload_part_size` par ce facteur chaque fois que `s3_multiply_parts_count_threshold` parties ont été téléversées à partir d’une seule écriture vers S3. La valeur par défaut est `2`.
* `s3_upload_part_size_multiply_parts_count_threshold` - Chaque fois que ce nombre de parties a été téléversé vers S3, `s3_min_upload_part_size` est multiplié par `s3_upload_part_size_multiply_factor`. La valeur par défaut est `500`.
* `s3_max_inflight_parts_for_one_file` - Limite le nombre de requêtes PUT pouvant être exécutées simultanément pour un objet. Cette valeur doit être limitée. La valeur `0` signifie illimité. La valeur par défaut est `20`. Chaque partie en cours de transfert utilise un tampon de taille `s3_min_upload_part_size` pour les `s3_upload_part_size_multiply_factor` premières parties, puis davantage lorsque le fichier est suffisamment volumineux, voir `upload_part_size_multiply_factor`. Avec les paramètres par défaut, un fichier téléversé ne consomme pas plus de `320Mb` pour un fichier de moins de `8G`. La consommation est plus élevée pour un fichier plus volumineux.
Considération de sécurité : si un utilisateur malveillant peut spécifier des URL S3 arbitraires, `s3_max_redirects` doit être défini sur zéro afin d’éviter les attaques [SSRF](https://en.wikipedia.org/wiki/Server-side_request_forgery) ; sinon, `remote_host_filter` doit être spécifié dans la configuration du serveur.
## Paramètres propres à l’endpoint
Les paramètres suivants peuvent être spécifiés dans le fichier de configuration pour un endpoint donné (qui sera mis en correspondance avec le préfixe exact d’une URL) :
* `endpoint` — Spécifie le préfixe d’un endpoint. Obligatoire.
* `access_key_id` et `secret_access_key` — Spécifie les identifiants à utiliser avec l’endpoint donné. Facultatif.
* `use_environment_credentials` — Si défini sur `true`, le client S3 tentera d’obtenir les identifiants à partir des variables d’environnement et des métadonnées [Amazon EC2](https://en.wikipedia.org/wiki/Amazon_Elastic_Compute_Cloud) pour l’endpoint donné. Facultatif, la valeur par défaut est `false`.
* `region` — Spécifie le nom de la région S3. Facultatif.
* `use_insecure_imds_request` — Si défini sur `true`, le client S3 utilisera une requête IMDS non sécurisée lors de l’obtention des identifiants à partir des métadonnées Amazon EC2. Facultatif, la valeur par défaut est `false`.
* `expiration_window_seconds` — Période de grâce permettant de vérifier si des identifiants expirables ont expiré. Facultatif, la valeur par défaut est `120`.
* `no_sign_request` - Ignore tous les identifiants afin que les requêtes ne soient pas signées. Utile pour accéder à des buckets publics.
* `header` — Ajoute l’en-tête HTTP spécifié à une requête vers l’endpoint donné. Facultatif, peut être spécifié plusieurs fois.
* `access_header` - Ajoute l’en-tête HTTP spécifié à une requête vers l’endpoint donné lorsqu’aucun autre identifiant n’est disponible depuis une autre source.
* `server_side_encryption_customer_key_base64` — Si spécifié, les en-têtes requis pour accéder à des objets S3 avec un chiffrement SSE-C seront définis. Facultatif.
* `server_side_encryption_kms_key_id` - Si spécifié, les en-têtes requis pour accéder à des objets S3 avec le [chiffrement SSE-KMS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html) seront définis. Si une chaîne vide est spécifiée, la clé S3 gérée par AWS sera utilisée. Facultatif.
* `server_side_encryption_kms_encryption_context` - Si spécifié avec `server_side_encryption_kms_key_id`, l’en-tête de contexte de chiffrement fourni pour SSE-KMS sera défini. Facultatif.
* `server_side_encryption_kms_bucket_key_enabled` - Si spécifié avec `server_side_encryption_kms_key_id`, l’en-tête permettant d’activer les clés de bucket S3 pour SSE-KMS sera défini. Facultatif, peut être `true` ou `false`, et n’a pas de valeur par défaut (correspond au paramètre défini au niveau du bucket).
* `max_single_read_retries` — Nombre maximal de tentatives lors d’une lecture unique. La valeur par défaut est `4`. Facultatif.
* `max_put_rps`, `max_put_burst`, `max_get_rps` et `max_get_burst` - Paramètres de limitation de débit (voir la description ci-dessus) à utiliser pour un endpoint spécifique plutôt que par query. Facultatif.
**Exemple :**
```xml theme={null}
https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/
```
## Utilisation des archives
Supposons que nous disposions de plusieurs fichiers d’archive avec les URI suivantes sur S3 :
* '[https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-10.csv.zip\'](https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-10.csv.zip\');
* '[https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-11.csv.zip\'](https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-11.csv.zip\');
* '[https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-12.csv.zip\'](https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-12.csv.zip\');
Il est possible d’extraire des données de ces archives à l’aide de ::. Des globs peuvent être utilisés aussi bien dans la partie URL que dans la partie située après :: (qui correspond au nom d’un fichier à l’intérieur de l’archive).
```sql theme={null}
SELECT *
FROM s3(
'https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-1{0..2}.csv.zip :: *.csv'
);
```
ClickHouse prend en charge trois formats d’archive :
ZIP
TAR
7Z
Si les archives ZIP et TAR sont accessibles depuis n’importe quel emplacement de stockage pris en charge, les archives 7Z ne peuvent être lues que depuis le système de fichiers local sur lequel ClickHouse est installé.
## Accès aux buckets publics
ClickHouse essaie de récupérer des identifiants à partir de nombreux types de sources.
Cela peut parfois poser des problèmes lors de l'accès à certains buckets publics et amener le client à renvoyer le code d'erreur `403`.
Vous pouvez éviter ce problème en utilisant le mot-clé `NOSIGN`, qui force le client à ignorer tous les identifiants et à ne pas signer les requêtes.
```sql theme={null}
CREATE TABLE big_table (name String, value UInt32)
ENGINE = S3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv', NOSIGN, 'CSVWithNames');
```
## Optimisation des performances
Pour en savoir plus sur l’optimisation des performances de la fonction s3, consultez [notre guide détaillé](/fr/integrations/connectors/data-ingestion/AWS/performance).
## Accès basé sur les rôles
Dans ClickHouse Cloud, vous pouvez utiliser l’accès basé sur les rôles pour vous authentifier auprès de S3 au lieu d’utiliser des clés d’accès. Consultez [Secure S3](/fr/products/cloud/guides/data-sources/accessing-s3-data-securely) pour suivre les étapes de configuration.
Une fois la configuration effectuée, un `roleARN` peut être transmis via le paramètre `extra_credentials` :
```sql theme={null}
CREATE TABLE my_s3_table(name String, value UInt32)
ENGINE = S3('https://my-bucket.s3.amazonaws.com/data/*.csv', extra_credentials(role_arn = 'arn:aws:iam::111111111111:role/ClickHouseAccessRole-001'), 'CSV')
```
Un `external_id` facultatif peut également être fourni avec `role_arn`. Il est transmis en tant que paramètre `ExternalId` dans l’appel AWS STS `AssumeRole`, ce qui permet à la policy de confiance du rôle d’exiger un secret partagé afin d’atténuer le [problème du deputy confus](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) :
```sql theme={null}
CREATE TABLE my_s3_table(name String, value UInt32)
ENGINE = S3('https://my-bucket.s3.amazonaws.com/data/*.csv', extra_credentials(role_arn = 'arn:aws:iam::111111111111:role/ClickHouseAccessRole-001', external_id = 'my-external-id'), 'CSV')
```
## Voir aussi
* [fonction de table S3](/fr/reference/functions/table-functions/s3)
* [Intégration de S3 avec ClickHouse](/fr/integrations/connectors/data-ingestion/AWS/integrating-s3-with-clickhouse)