> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Proporciona una interfaz de tipo tabla para `SELECT` e `INSERT` de datos desde Google Cloud Storage. Requiere el IAM role `Storage Object User`. # gcs Proporciona una interfaz de tipo tabla para `SELECT` e `INSERT` de datos desde [Google Cloud Storage](https://cloud.google.com/storage/). Requiere el [IAM role `Storage Object User`](https://cloud.google.com/storage/docs/access-control/iam-roles). Este es un alias de la [función de tabla s3](/es/reference/functions/table-functions/s3). Si tiene varias réplicas en el cluster, puede usar en su lugar la [función s3Cluster](/es/reference/functions/table-functions/s3Cluster) (que funciona con GCS) para paralelizar los inserts.
## Sintaxis
```sql theme={null} 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](https://cloud.google.com/storage/docs/interoperability) 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](/es/reference/formats) 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: ```text theme={null} https://storage.googleapis.com/// ``` y no ~~[https://storage.cloud.google.com](https://storage.cloud.google.com)~~. Los argumentos también pueden pasarse mediante [colecciones con nombre](/es/concepts/features/configuration/server-config/named-collections). 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`: ```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 │ └─────────┴─────────┴─────────┘ ``` Algo similar, pero desde un archivo con compresión `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 │ └─────────┴─────────┴─────────┘ ```
## 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\_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\'); Cuenta el número de filas de los archivos que terminan en números del 1 al 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 │ └─────────┘ ``` Cuenta el número total de filas de todos los archivos de estos dos directorios: ```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 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`: ```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 │ └─────────┘ ``` Inserta datos en el archivo `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); ``` Insertar datos en el archivo `test-data.csv.gz` desde una tabla existente: ```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; ``` 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: ```sql theme={null} 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: ```sql theme={null} 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](/es/concepts/features/configuration/server-config/named-collections). A continuación se muestra un ejemplo: ```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') ```
## 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: ```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); ``` 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: ```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); ``` 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`. * [Función de tabla S3](/es/reference/functions/table-functions/s3) * [Motor S3](/es/reference/engines/table-engines/integrations/s3)