gcs

Proporciona una interfaz de tipo tabla para SELECT e INSERT de datos desde Google Cloud Storage. Requiere el IAM role Storage Object User.

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])
gcs(named_collection[, option=value [,..]])

GCS

La 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.

GCS

La 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 y compression_method 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 de la tabla desde el archivo de GCS https://storage.googleapis.com/my-test-bucket-768/data.csv:

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

Algo similar, pero desde un archivo con compresión gzip:

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:

• ‘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'

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.

Ejemplos

1. 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 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.

2. 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 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.

​

Relacionados

• Función de tabla S3
• Motor S3