gcs

Fornece uma interface semelhante a uma tabela para SELECT e INSERT de dados do Google Cloud Storage. Requer o papel do IAM Storage Object User.

Fornece uma interface semelhante a uma tabela para SELECT e INSERT de dados do Google Cloud Storage. Requer o papel do IAM Storage Object User.

Este é um alias da função de tabela s3.

Se você tiver várias réplicas no cluster, poderá usar a função s3Cluster (que funciona com GCS) para paralelizar inserções.

​

Sintaxe

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

GCS

A função de tabela GCS se integra ao Google Cloud Storage usando a API XML do GCS e chaves HMAC. Consulte a documentação de interoperabilidade do Google para mais detalhes sobre o endpoint e o HMAC.

​

Argumentos

Argumento	Descrição
url	Caminho do bucket para o arquivo. Suporta os seguintes curingas no modo somente leitura: *, **, ?, {abc,def} e {N..M}, em que N, M — números, 'abc', 'def' — strings.
NOSIGN	Se esta palavra-chave for fornecida no lugar das credenciais, nenhuma requisição será assinada.
hmac_key and hmac_secret	Chaves que especificam as credenciais a serem usadas com o endpoint informado. Opcional.
format	O formato do arquivo.
structure	Estrutura da tabela. Formato 'column1_name column1_type, column2_name column2_type, ...'.
compression_method	O parâmetro é opcional. Valores aceitos: none, gzip ou gz, brotli ou br, xz ou LZMA, zstd ou zst. Por padrão, o método de compressão é detectado automaticamente pela extensão do arquivo.

GCS

O caminho do GCS tem este formato, pois o endpoint da Google XML API é diferente do da JSON API:

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

e não https://storage.cloud.google.com.

Os argumentos também podem ser passados usando coleções nomeadas. Nesse caso, url, format, structure, compression_method funcionam da mesma forma, e alguns parâmetros extras são aceitos:

Parâmetro	Descrição
access_key_id	hmac_key, opcional.
secret_access_key	hmac_secret, opcional.
filename	Acrescentado à URL, se especificado.
use_environment_credentials	Habilitado por padrão, permite passar parâmetros extras usando as variáveis de ambiente AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_CONTAINER_AUTHORIZATION_TOKEN, AWS_EC2_METADATA_DISABLED.
no_sign_request	Desabilitado por padrão.
expiration_window_seconds	O valor padrão é 120.

​

Valor retornado

Uma tabela com a estrutura especificada para ler ou gravar dados no arquivo especificado.

​

Exemplos

Selecionando as duas primeiras linhas da tabela a partir do arquivo do 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 │
└─────────┴─────────┴─────────┘

Semelhante, mas de um arquivo com método de compressão 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

Suponha que temos vários arquivos com as seguintes URIs no 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'

Conte o número de linhas nos arquivos que terminam com os números de 1 a 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 │
└─────────┘

Conte o total de linhas em todos os arquivos nestes dois diretórios:

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

Se a lista de arquivos contiver intervalos numéricos com zeros à esquerda, use a construção com chaves para cada dígito separadamente ou use ?.

Conte o número total de linhas em arquivos chamados 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 │
└─────────┘

Insira dados no arquivo 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);

Insira dados no arquivo test-data.csv.gz a partir de uma tabela 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;

O glob ** pode ser usado para percorrer diretórios de forma recursiva. Considere o exemplo abaixo: ele buscará todos os arquivos do diretório my-test-bucket-768 recursivamente:

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

O trecho abaixo obtém dados de todos os arquivos test-data.csv.gz de qualquer pasta dentro do diretório 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 casos de uso em produção, recomenda-se usar coleções nomeadas. Veja o exemplo:

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

​

Gravação particionada

Se você especificar a expressão PARTITION BY ao inserir dados na tabela GCS, será criado um arquivo separado para cada valor de partição. Dividir os dados em arquivos separados ajuda a aumentar a eficiência das operações de leitura.

Exemplos

1. Usar o ID da partição em uma chave cria arquivos separados:

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, os dados são gravados em três arquivos: file_x.csv, file_y.csv e file_z.csv.

2. Usar o ID da partição no nome do bucket cria arquivos em 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, os dados são gravados em três arquivos, em buckets diferentes: my_bucket_1/file.csv, my_bucket_10/file.csv e my_bucket_20/file.csv.

​

Relacionados

• função de tabela S3
• motor S3