azureBlobStorage

Fornece uma interface semelhante a uma tabela para selecionar/inserir arquivos no Azure Blob Storage. Esta função de tabela é semelhante à função s3.

Sintaxe

As credenciais estão embutidas na string de conexão, portanto account_name/account_key não são necessários separadamente:

azureBlobStorage(connection_string, container_name, blobpath [, format, compression, partition_strategy, structure])

Requer account_name e account_key como argumentos separados:

azureBlobStorage(storage_account_url, container_name, blobpath, account_name, account_key [, format, compression, partition_strategy, structure])

Veja Coleções nomeadas abaixo para a lista completa de chaves aceitas:

azureBlobStorage(named_collection[, option=value [,..]])

Argumentos

Argument	Descrição
`connection_string`	Uma string de conexão que inclui credenciais embutidas (nome da conta + chave da conta ou SAS token). Ao usar esse formato, `account_name` e `account_key` não devem ser passados separadamente. Consulte Configurar uma string de conexão.
`storage_account_url`	A URL do endpoint da conta de armazenamento, por exemplo, `https://myaccount.blob.core.windows.net/`. Ao usar esse formato, você deve também passar `account_name` e `account_key`.
`container_name`	Nome do contêiner.
`blobpath`	Caminho do arquivo. Oferece suporte aos seguintes wildcard no modo somente leitura: ``, `*`, `?`, `{abc,def}` e `{N..M}`, em que `N`, `M` — números, `'abc'`, `'def'` — strings.
`account_name`	Nome da conta de armazenamento. Obrigatório ao usar `storage_account_url` sem SAS; não deve ser passado ao usar `connection_string`.
`account_key`	Chave da conta de armazenamento. Obrigatória ao usar `storage_account_url` sem SAS; não deve ser passada ao usar `connection_string`.
`format`	O formato do arquivo.
`compression`	Valores compatíveis: `none`, `gzip/gz`, `brotli/br`, `xz/LZMA`, `zstd/zst`. Por padrão, a compressão será detectada automaticamente pela extensão do arquivo (o mesmo que definir como `auto`).
`structure`	Estrutura da tabela. Formato: `'column1_name column1_type, column2_name column2_type, ...'`.
`partition_strategy`	Opcional. Valores compatíveis: `WILDCARD` ou `HIVE`. `WILDCARD` exige um `{_partition_id}` no caminho, que é substituído pela chave de partição. `HIVE` não permite caracteres curinga, pressupõe que o caminho é a raiz da tabela e gera diretórios particionados no estilo Hive com IDs Snowflake como nomes de arquivo e o formato do arquivo como extensão. Sem uma estratégia explícita, um caminho com `{_partition_id}` usa `WILDCARD`. Um caminho com outro glob não usa estratégia de particionamento e ignora `PARTITION BY`. Um caminho sem glob usa `HIVE` quando `file_like_engine_default_partition_strategy` é `HIVE`; caso contrário, não usa estratégia de particionamento.
`partition_columns_in_data_file`	Opcional. Usado apenas com a estratégia de particionamento `HIVE`. Informa ao ClickHouse se deve esperar que as colunas de partição sejam gravadas no arquivo de dados. O padrão é `false`.
`extra_credentials`	Use `client_id` e `tenant_id` para autenticação. Se `extra_credentials` forem fornecidas, elas terão prioridade sobre `account_name` e `account_key`.

Coleções nomeadas

Os argumentos também podem ser passados usando coleções nomeadas. Nesse caso, as seguintes chaves são aceitas:

Chave	Obrigatório	Descrição
`container`	Sim	Nome do contêiner. Corresponde ao argumento posicional `container_name`.
`blob_path`	Sim	Caminho do arquivo (com wildcards opcionais). Corresponde ao argumento posicional `blobpath`.
`connection_string`	Não*	String de conexão com credenciais embutidas. *É necessário fornecer `connection_string` ou `storage_account_url`.
`storage_account_url`	Não*	URL do endpoint da conta de armazenamento. *É necessário fornecer `connection_string` ou `storage_account_url`.
`account_name`	Não	Obrigatório ao usar `storage_account_url`
`account_key`	Não	Obrigatório ao usar `storage_account_url`
`format`	Não	Formato do arquivo.
`compression`	Não	Tipo de compressão.
`structure`	Não	Estrutura da tabela.
`client_id`	Não	ID do cliente para autenticação.
`tenant_id`	Não	ID do tenant para autenticação.

Exemplo:

CREATE NAMED COLLECTION azure_my_data AS
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'mycontainer',
    blob_path = 'data/*.parquet',
    account_name = 'myaccount',
    account_key = 'mykey...==',
    format = 'Parquet';

SELECT *
FROM azureBlobStorage(azure_my_data)
LIMIT 5;

Você também pode sobrescrever os valores da coleção nomeada no momento da consulta:

SELECT *
FROM azureBlobStorage(azure_my_data, blob_path = 'other_data/*.csv', format = 'CSVWithNames')
LIMIT 5;

Valor retornado

Uma tabela com a estrutura especificada para leitura ou gravação de dados no arquivo especificado.

Exemplos

Leitura usando o formato `storage_account_url`

SELECT *
FROM azureBlobStorage(
    'https://myaccount.blob.core.windows.net/',
    'mycontainer',
    'data/*.parquet',
    'myaccount',
    'mykey...==',
    'Parquet'
)
LIMIT 5;

Leitura no formato `connection_string`

SELECT *
FROM azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'data/*.csv',
    'CSVWithNames'
)
LIMIT 5;

Gravação usando partições

Um caminho que contém {_partition_id} implica o uso da estratégia de particionamento WILDCARD. Um caminho com outro glob não usa estratégia de particionamento e ignora PARTITION BY. Um caminho sem glob usa HIVE quando file_like_engine_default_partition_strategy é HIVE; caso contrário, não usa estratégia de particionamento.

INSERT INTO TABLE FUNCTION azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_{_partition_id}.csv',
    'CSV',
    'auto',
    'wildcard',
    'column1 UInt32, column2 UInt32, column3 UInt32'
) PARTITION BY column3
VALUES (1, 2, 3), (3, 2, 1), (78, 43, 3);

Em seguida, leia uma partição específica:

SELECT *
FROM azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_1.csv',
    'CSV',
    'auto',
    'column1 UInt32, column2 UInt32, column3 UInt32'
);

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

Colunas virtuais

_path — Caminho do arquivo. Tipo: LowCardinality(String).
_file — Nome do arquivo. Tipo: LowCardinality(String).
_size — Tamanho do arquivo em bytes. Tipo: Nullable(UInt64). Se o tamanho do arquivo for desconhecido, o valor será NULL.
_time — Horário da última modificação do arquivo. Tipo: Nullable(DateTime). Se o horário for desconhecido, o valor será NULL.

Gravação particionada

Estratégia de particionamento

Compatível apenas com consultas INSERT.

WILDCARD: substitui o wildcard {_partition_id} no caminho do arquivo pela chave de partição real. É selecionado por padrão quando o caminho contém {_partition_id}.

Quando nenhum partition_strategy é definido, um caminho com outro glob não usa nenhuma estratégia de particionamento e ignora PARTITION BY. Um caminho sem glob usa HIVE quando file_like_engine_default_partition_strategy é HIVE; caso contrário, não usa nenhuma estratégia de particionamento.

HIVE implementa o particionamento no estilo Hive para leituras & gravações. Gera arquivos usando o seguinte formato: <prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>.

Exemplo da estratégia de particionamento HIVE

INSERT INTO TABLE FUNCTION azureBlobStorage(
    azure_conf2,
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'cont',
    blob_path = 'azure_table_root',
    format = 'CSVWithNames',
    compression = 'auto',
    structure = 'year UInt16, country String, id Int32',
    partition_strategy = 'hive'
) PARTITION BY (year, country)
VALUES (2020, 'Russia', 1), (2021, 'Brazil', 2);

SELECT _path, * FROM azureBlobStorage(
    azure_conf2,
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'cont',
    blob_path = 'azure_table_root/**.csvwithnames'
)

   ┌─_path───────────────────────────────────────────────────────────────────────────┬─id─┬─year─┬─country─┐
1. │ cont/azure_table_root/year=2021/country=Brazil/7351307847391293440.csvwithnames │  2 │ 2021 │ Brazil  │
2. │ cont/azure_table_root/year=2020/country=Russia/7351307847378710528.csvwithnames │  1 │ 2020 │ Russia  │
   └─────────────────────────────────────────────────────────────────────────────────┴────┴──────┴─────────┘

configuração use_hive_partitioning

Esta é uma instrução para o ClickHouse interpretar arquivos particionados no estilo Hive no momento da leitura. Isso não afeta a gravação. Para manter simetria entre leituras e gravações, use o argumento partition_strategy.

Quando a configuração use_hive_partitioning é definida como 1, o ClickHouse detecta o particionamento no estilo Hive no caminho (/name=value/) e permite usar colunas de partição como colunas virtuais na consulta. Essas colunas virtuais terão os mesmos nomes do caminho particionado.

Exemplo

Use a coluna virtual criada com particionamento no estilo Hive

SELECT * FROM azureBlobStorage(config, storage_account_url='...', container='...', blob_path='http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

Usando Shared Access Signatures (SAS)

Uma Shared Access Signature (SAS) é um URI que concede acesso restrito a um contêiner ou arquivo no Azure Storage. Use-a para fornecer acesso por tempo limitado aos recursos da conta de armazenamento sem compartilhar a chave da conta de armazenamento. Mais detalhes aqui.

A função azureBlobStorage oferece suporte a Shared Access Signatures (SAS).

Um Blob SAS token contém todas as informações necessárias para autenticar a solicitação, incluindo o blob de destino, as permissões e o período de validade. Para montar uma URL de blob, acrescente o SAS token ao endpoint do serviço Blob. Por exemplo, se o endpoint for https://clickhousedocstest.blob.core.windows.net/, a solicitação será:

SELECT count()
FROM azureBlobStorage('BlobEndpoint=https://clickhousedocstest.blob.core.windows.net/;SharedAccessSignature=sp=r&st=2025-01-29T14:58:11Z&se=2025-01-29T22:58:11Z&spr=https&sv=2022-11-02&sr=c&sig=Ac2U0xl4tm%2Fp7m55IilWl1yHwk%2FJG0Uk6rMVuOiD0eE%3D', 'exampledatasets', 'example.csv')

┌

Como alternativa, os usuários podem usar a URL SAS gerada do Blob:

SELECT count()
FROM azureBlobStorage('https://clickhousedocstest.blob.core.windows.net/?sp=r&st=2025-01-29T14:58:11Z&se=2025-01-29T22:58:11Z&spr=https&sv=2022-11-02&sr=c&sig=Ac2U0xl4tm%2Fp7m55IilWl1yHwk%2FJG0Uk6rMVuOiD0eE%3D', 'exampledatasets', 'example.csv')

┌

Mecanismo de tabela AzureBlobStorage