azureBlobStorage

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

​

Função de tabela 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

String de conexão

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, structure])

URL da conta de armazenamento

Requer account_name e account_key como argumentos separados:

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

Coleção nomeada

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 caracteres curinga 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 ID Snowflake como nomes de arquivo e o formato do arquivo como extensão. O padrão é a configuração file_like_engine_default_partition_strategy (WILDCARD nas configurações de compatibility anteriores à 26.6, caso contrário HIVE).
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.

Os nomes das chaves da coleção nomeada diferem dos nomes dos argumentos posicionais da função: container (não container_name) e blob_path (não blobpath).

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

INSERT INTO TABLE FUNCTION azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_{_partition_id}.csv',
    'CSV',
    'auto',
    '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 curinga {_partition_id} no caminho do arquivo pela chave de particionamento real. É selecionado por padrão apenas nas configurações de compatibility anteriores a 26.6; caso contrário, o padrão é HIVE (consulte a configuração file_like_engine_default_partition_strategy).

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

┌─count()─┐
│      10 │
└─────────┘

1 row in set. Elapsed: 0.425 sec.

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

┌─count()─┐
│      10 │
└─────────┘

1 row in set. Elapsed: 0.153 sec.

​

Relacionados

• Mecanismo de tabela AzureBlobStorage