> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Fournit une interface de type table pour `SELECT` et `INSERT` de données depuis Google Cloud Storage. Nécessite le rôle IAM `Storage Object User`. # gcs Fournit une interface de type table pour `SELECT` et `INSERT` de données depuis [Google Cloud Storage](https://cloud.google.com/storage/). Nécessite le [rôle IAM `Storage Object User`](https://cloud.google.com/storage/docs/access-control/iam-roles). Il s'agit d'un alias de la [fonction de table s3](/fr/reference/functions/table-functions/s3). Si votre cluster comporte plusieurs répliques, vous pouvez utiliser la [fonction s3Cluster](/fr/reference/functions/table-functions/s3Cluster) (compatible avec GCS) à la place pour paralléliser les insertions.
## Syntaxe
```sql theme={null} gcs(url [, NOSIGN | hmac_key, hmac_secret] [,format] [,structure] [,compression_method]) gcs(named_collection[, option=value [,..]]) ``` **GCS** La fonction de table GCS s’intègre à Google Cloud Storage à l’aide de l’API XML GCS et de clés HMAC. Consultez la [documentation sur l’interopérabilité de Google](https://cloud.google.com/storage/docs/interoperability) pour plus de détails sur l’endpoint et le HMAC.
## Arguments
| Argument | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | Chemin du bucket vers le fichier. Prend en charge les caractères génériques suivants en mode `readonly` : `*`, `**`, `?`, `{abc,def}` et `{N..M}`, où `N` et `M` sont des nombres, et `'abc'` et `'def'` des chaînes. | | `NOSIGN` | Si ce keyword est fourni à la place des credentials, aucune request ne sera signée. | | `hmac_key` and `hmac_secret` | Clés indiquant les credentials à utiliser avec l'endpoint spécifié. Facultatif. | | `format` | Le [format](/fr/reference/formats/index) du fichier. | | `structure` | Structure de la table. Format : `'column1_name column1_type, column2_name column2_type, ...'`. | | `compression_method` | Ce parameter est facultatif. Valeurs prises en charge : `none`, `gzip` ou `gz`, `brotli` ou `br`, `xz` ou `LZMA`, `zstd` ou `zst`. Par défaut, la méthode de compression est détectée automatiquement à partir de l'extension du fichier. | **GCS** Le chemin GCS se présente sous ce format, car l'endpoint de l'API XML de Google est différent de celui de l'API JSON : ```text theme={null} https://storage.googleapis.com/// ``` et non ~~[https://storage.cloud.google.com](https://storage.cloud.google.com)~~. Les arguments peuvent également être transmis à l'aide de [named collections](/fr/concepts/features/configuration/server-config/named-collections). Dans ce cas, `url`, `format`, `structure` et `compression_method` fonctionnent de la même manière, et quelques paramètres supplémentaires sont pris en charge : | Parameter | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access_key_id` | `hmac_key`, facultatif. | | `secret_access_key` | `hmac_secret`, facultatif. | | `filename` | Ajouté à l'URL s'il est spécifié. | | `use_environment_credentials` | Activé par défaut, permet de transmettre des paramètres supplémentaires à l'aide des variables d'environnement `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`, `AWS_CONTAINER_CREDENTIALS_FULL_URI`, `AWS_CONTAINER_AUTHORIZATION_TOKEN`, `AWS_EC2_METADATA_DISABLED`. | | `no_sign_request` | Désactivé par défaut. | | `expiration_window_seconds` | La valeur par défaut est 120. |
## Valeur renvoyée
Une table dotée de la structure spécifiée pour lire ou écrire des données dans le fichier indiqué.
## Exemples
Sélection des deux premières lignes de la table depuis le fichier GCS `https://storage.googleapis.com/my-test-bucket-768/data.csv` : ```sql theme={null} SELECT * FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32') LIMIT 2; ``` ```text theme={null} ┌─column1─┬─column2─┬─column3─┐ │ 1 │ 2 │ 3 │ │ 3 │ 2 │ 1 │ └─────────┴─────────┴─────────┘ ``` Le même, mais à partir d’un fichier utilisant la méthode de compression `gzip` : ```sql theme={null} SELECT * FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32', 'gzip') LIMIT 2; ``` ```text theme={null} ┌─column1─┬─column2─┬─column3─┐ │ 1 │ 2 │ 3 │ │ 3 │ 2 │ 1 │ └─────────┴─────────┴─────────┘ ```
## Utilisation
Supposons que nous disposions de plusieurs fichiers avec les URI suivantes sur GCS : * '[https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_1.csv\'](https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_1.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_2.csv\'](https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_2.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_3.csv\'](https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_3.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_4.csv\'](https://storage.googleapis.com/my-test-bucket-768/some\_prefix/some\_file\_4.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_1.csv\'](https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_1.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_2.csv\'](https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_2.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_3.csv\'](https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_3.csv\'); * '[https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_4.csv\'](https://storage.googleapis.com/my-test-bucket-768/another\_prefix/some\_file\_4.csv\'); Comptez le nombre de lignes dans les fichiers dont le nom se termine par un chiffre de 1 à 3 : ```sql theme={null} SELECT count(*) FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32') ``` ```text theme={null} ┌─count()─┐ │ 18 │ └─────────┘ ``` Comptez le nombre total de lignes dans tous les fichiers de ces deux répertoires : ```sql theme={null} SELECT count(*) FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/{some,another}_prefix/*', 'CSV', 'column1 UInt32, column2 UInt32, column3 UInt32') ``` ```text theme={null} ┌─count()─┐ │ 24 │ └─────────┘ ``` Si votre liste de fichiers contient des plages de nombres avec des zéros non significatifs, utilisez la construction avec des accolades pour chaque chiffre séparément ou utilisez `?`. Comptez le nombre total de lignes dans les fichiers nommés `file-000.csv`, `file-001.csv`, ... , `file-999.csv`: ```sql theme={null} SELECT count(*) FROM gcs('https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/big_prefix/file-{000..999}.csv', 'CSV', 'name String, value UInt32'); ``` ```text theme={null} ┌─count()─┐ │ 12 │ └─────────┘ ``` Insérez les données dans le fichier `test-data.csv.gz` : ```sql theme={null} INSERT INTO FUNCTION gcs('https://storage.googleapis.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip') VALUES ('test-data', 1), ('test-data-2', 2); ``` Insérez des données dans le fichier `test-data.csv.gz` à partir d’une table existante : ```sql theme={null} INSERT INTO FUNCTION gcs('https://storage.googleapis.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip') SELECT name, value FROM existing_table; ``` Le glob \*\* peut être utilisé pour parcourir récursivement les répertoires. Dans l’exemple ci-dessous, il récupérera récursivement tous les fichiers du répertoire `my-test-bucket-768` : ```sql theme={null} SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**', 'CSV', 'name String, value UInt32', 'gzip'); ``` Ce qui suit récupère les données de tous les fichiers `test-data.csv.gz` situés dans n’importe quel sous-dossier du répertoire `my-test-bucket`, de manière récursive : ```sql theme={null} SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip'); ``` Pour un usage en production, il est recommandé d'utiliser les [collections nommées](/fr/concepts/features/configuration/server-config/named-collections). Voici un exemple : ```sql theme={null} CREATE NAMED COLLECTION creds AS access_key_id = '***', secret_access_key = '***'; SELECT count(*) FROM gcs(creds, url='https://s3-object-url.csv') ```
## Écriture partitionnée
Si vous spécifiez une expression `PARTITION BY` lors de l’insertion de données dans la table `GCS`, un fichier distinct est créé pour chaque valeur de partition. Répartir les données dans des fichiers distincts permet d’améliorer l’efficacité des opérations de lecture. **Exemples** 1. L’utilisation de l’identifiant de partition dans une clé crée des fichiers distincts : ```sql theme={null} INSERT INTO TABLE FUNCTION gcs('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a String, b UInt32, c UInt32') PARTITION BY a VALUES ('x', 2, 3), ('x', 4, 5), ('y', 11, 12), ('y', 13, 14), ('z', 21, 22), ('z', 23, 24); ``` Par conséquent, les données sont écrites dans trois fichiers : `file_x.csv`, `file_y.csv` et `file_z.csv`. 2. L’utilisation de l’identifiant de partition dans le nom d’un bucket permet de créer des fichiers dans différents buckets : ```sql theme={null} INSERT INTO TABLE FUNCTION gcs('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32') PARTITION BY a VALUES (1, 2, 3), (1, 4, 5), (10, 11, 12), (10, 13, 14), (20, 21, 22), (20, 23, 24); ``` Par conséquent, les données sont écrites dans trois fichiers répartis dans différents buckets : `my_bucket_1/file.csv`, `my_bucket_10/file.csv` et `my_bucket_20/file.csv`. * [fonction de table S3](/fr/reference/functions/table-functions/s3) * [moteur S3](/fr/reference/engines/table-engines/integrations/s3)