gcs

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.

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.

Il s’agit d’un alias de la fonction de table s3.

Si votre cluster comporte plusieurs répliques, vous pouvez utiliser la fonction s3Cluster (compatible avec GCS) à la place pour paralléliser les insertions.

​

Syntaxe

gcs(url [, NOSIGN | hmac_key, hmac_secret] [,format] [,structure] [,compression_method] [,partition_strategy])
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 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 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.
partition_strategy	Facultatif. Valeurs prises en charge : wildcard ou hive. wildcard nécessite {_partition_id} dans le chemin. C’est la valeur par défaut lorsque le chemin contient {_partition_id} (la seule stratégie compatible avec un tel chemin), ou lorsque compatibility est antérieure à 26.6 ; sinon, y compris lorsque les valeurs par défaut actuelles s’appliquent, la valeur par défaut est hive.

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 :

  https://storage.googleapis.com/<bucket>/<folder>/<filename(s)>

et non https://storage.cloud.google.com.

Les arguments peuvent également être transmis à l’aide de collections nommées. Dans ce cas, url, format, structure, compression_method et partition_strategy 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 depuis le fichier GCS https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz. La méthode de compression est détectée automatiquement à partir de l’extension de fichier .gz :

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;

┌─column1─┬─column2─┬─column3─┐
│       1 │       2 │       3 │
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

La même requête que ci-dessus, mais avec la méthode de compression gzip explicitement spécifiée au lieu de s’appuyer sur la détection automatique :

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;

┌─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_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_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_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_4.csv'

Comptez le nombre de lignes dans les fichiers dont le nom se termine par un chiffre de 1 à 3 :

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')

┌─count()─┐
│      18 │
└─────────┘

Comptez le nombre total de lignes dans tous les fichiers de ces deux répertoires :

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')

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

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');

┌─count()─┐
│      12 │
└─────────┘

Insérez les données dans le fichier test-data.csv.gz :

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 :

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 :

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 :

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. Voici un exemple :

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.

Un chemin contenant {_partition_id} implique la stratégie de partitionnement wildcard, donc la définition explicite de partition_strategy='wildcard' dans les exemples ci-dessous est facultative. Pour les chemins sans l’espace réservé, la valeur par défaut est hive lorsque compatibility est défini sur 26.6 ou une version ultérieure (y compris les valeurs par défaut actuelles) ; consultez le paramètre file_like_engine_default_partition_strategy.

Exemples

1. L’utilisation de l’identifiant de partition dans une clé crée des fichiers distincts :

INSERT INTO TABLE FUNCTION
    gcs('http://bucket.amazonaws.com/my_bucket/file_{_partition_id}.csv', 'CSV', 'a String, b UInt32, c UInt32', partition_strategy='wildcard')
    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 :

INSERT INTO TABLE FUNCTION
    gcs('http://bucket.amazonaws.com/my_bucket_{_partition_id}/file.csv', 'CSV', 'a UInt32, b UInt32, c UInt32', partition_strategy='wildcard')
    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.

​

Voir aussi

• fonction de table S3
• moteur S3