gcs - ClickHouse Documentation

Proporciona una interfaz de tipo tabla para SELECT e INSERT de datos desde Google Cloud Storage. Requiere el IAM role Storage Object User. Este es un alias de la función de tabla s3. Si tiene varias réplicas en el cluster, puede usar en su lugar la función s3Cluster (que funciona con GCS) para paralelizar los inserts.

Sintaxis

gcs(url [, NOSIGN | hmac_key, hmac_secret] [,format] [,structure] [,compression_method] [,partition_strategy])
gcs(named_collection[, option=value [,..]])

GCSLa función de tabla de GCS se integra con Google Cloud Storage mediante la API XML de GCS y las claves HMAC. Consulta la documentación de interoperabilidad de Google para obtener más información sobre el endpoint y las claves HMAC.

Argumentos

Argumento	Descripción
`url`	Ruta del bucket al archivo. Admite los siguientes wildcards en modo de solo lectura: ``, `*`, `?`, `{abc,def}` y `{N..M}`, donde `N` y `M` son números, y `'abc'` y `'def'` son cadenas.
`NOSIGN`	Si esta palabra clave se proporciona en lugar de las credenciales, ninguna de las solicitudes se firmará.
`hmac_key` y `hmac_secret`	Claves que especifican las credenciales que se usarán con el endpoint indicado. Opcional.
`format`	El formato del archivo.
`structure`	Estructura de la tabla. Formato: `'column1_name column1_type, column2_name column2_type, ...'`.
`compression_method`	El parámetro es opcional. Valores admitidos: `none`, `gzip` o `gz`, `brotli` o `br`, `xz` o `LZMA`, `zstd` o `zst`. De forma predeterminada, el método de compresión se detecta automáticamente por la extensión del archivo.
`partition_strategy`	Opcional. Valores admitidos: `wildcard` o `hive`. `wildcard` requiere `{_partition_id}` en la ruta. Es el valor predeterminado solo cuando `compatibility` es anterior a `26.6`; en caso contrario, incluido cuando se aplican los valores predeterminados actuales, el valor predeterminado es `hive`.

GCSLa ruta de GCS tiene este formato, ya que el endpoint de la API XML de Google es distinto del de la API JSON:

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

y no ~~https://storage.cloud.google.com~~.

Los argumentos también pueden pasarse mediante colecciones con nombre. En este caso, url, format, structure, compression_method y partition_strategy funcionan de la misma manera, y se admiten algunos parámetros adicionales:

Parámetro	Descripción
`access_key_id`	`hmac_key`, opcional.
`secret_access_key`	`hmac_secret`, opcional.
`filename`	Se añade a la url si se especifica.
`use_environment_credentials`	Habilitado de forma predeterminada, permite pasar parámetros adicionales mediante las variables de entorno `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`, `AWS_CONTAINER_CREDENTIALS_FULL_URI`, `AWS_CONTAINER_AUTHORIZATION_TOKEN`, `AWS_EC2_METADATA_DISABLED`.
`no_sign_request`	Deshabilitado de forma predeterminada.
`expiration_window_seconds`	El valor predeterminado es 120.

Valor devuelto

Una tabla con la estructura especificada para leer o escribir datos en el archivo indicado.

Ejemplos

Selección de las dos primeras filas del archivo de GCS https://storage.googleapis.com/clickhouse_public_datasets/my-test-bucket-768/data.csv.gz. El método de compresión se detecta automáticamente a partir de la extensión de archivo .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 misma consulta que arriba, pero con el método de compresión gzip especificado de forma explícita en lugar de depender de la autodetección:

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 │
└─────────┴─────────┴─────────┘

Uso

Supongamos que tenemos varios archivos con las siguientes URI en GCS:

Cuenta el número de filas de los archivos que terminan en números del 1 al 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 │
└─────────┘

Cuenta el número total de filas de todos los archivos de estos dos directorios:

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 la lista de archivos contiene rangos numéricos con ceros a la izquierda, usa la sintaxis con llaves para cada dígito por separado o ?.

Cuenta el número total de filas en archivos llamados 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 │
└─────────┘

Inserta datos en el archivo 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);

Insertar datos en el archivo test-data.csv.gz desde una tabla existente:

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;

El patrón glob ** se puede usar para recorrer directorios de forma recursiva. Considere el siguiente ejemplo: recuperará todos los archivos del directorio my-test-bucket-768 de forma recursiva:

SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**', 'CSV', 'name String, value UInt32', 'gzip');

Lo siguiente obtiene datos de todos los archivos test-data.csv.gz ubicados en cualquier carpeta dentro del directorio my-test-bucket, de forma recursiva:

SELECT * FROM gcs('https://storage.googleapis.com/my-test-bucket-768/**/test-data.csv.gz', 'CSV', 'name String, value UInt32', 'gzip');

Para entornos de producción, se recomienda usar colecciones con nombre. A continuación se muestra un ejemplo:

CREATE NAMED COLLECTION creds AS
        access_key_id = '***',
        secret_access_key = '***';
SELECT count(*)
FROM gcs(creds, url='https://s3-object-url.csv')

Escritura particionada

Si se especifica la expresión PARTITION BY al insertar datos en la tabla GCS, se crea un archivo independiente para cada valor de partición. Dividir los datos en archivos independientes ayuda a mejorar la eficiencia de las operaciones de lectura. Cuando compatibility se establece en 26.6 o una versión posterior, o cuando se aplican los valores predeterminados actuales, hive es la estrategia de partición predeterminada. Como las rutas que contienen {_partition_id} requieren wildcard, los siguientes ejemplos establecen partition_strategy='wildcard' explícitamente. Ejemplos

Usar el ID de la partición en la clave crea archivos independientes:

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

Como resultado, los datos se escriben en tres archivos: file_x.csv, file_y.csv y file_z.csv.

El uso del ID de la partición en el nombre de un bucket crea archivos en buckets diferentes:

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

Como resultado, los datos se escriben en tres archivos ubicados en distintos buckets: my_bucket_1/file.csv, my_bucket_10/file.csv y my_bucket_20/file.csv.

​Sintaxis

​Argumentos

​Valor devuelto

​Ejemplos

​Uso

​Escritura particionada

​Relacionados

Sintaxis

Argumentos

Valor devuelto

Ejemplos

Uso

Escritura particionada

Relacionados