Motor de tabela AzureBlobStorage

Este motor oferece integração com o ecossistema do Azure Blob Storage.

Este motor oferece integração com o ecossistema do Azure Blob Storage.

​

CREATE TABLE

CREATE TABLE azure_blob_storage_table (name String, value UInt32)
    ENGINE = AzureBlobStorage(connection_string|storage_account_url, container_name, blobpath, [account_name, account_key, format, compression, partition_strategy, partition_columns_in_data_file, extra_credentials(client_id=, tenant_id=)])
    [PARTITION BY expr]
    [SETTINGS ...]

​

Parâmetros do mecanismo

• endpoint — URL do endpoint do AzureBlobStorage com contêiner e prefixo. Opcionalmente, pode conter account_name se o método de autenticação usado exigir isso. (http://azurite1:{port}/[account_name]{container_name}/{data_prefix}) ou esses parâmetros podem ser fornecidos separadamente usando storage_account_url, account_name e container. Para especificar o prefixo, endpoint deve ser usado.
• endpoint_contains_account_name - Este sinalizador é usado para especificar se endpoint contém account_name, já que isso só é necessário para determinados métodos de autenticação. (Padrão: true)
• connection_string|storage_account_url — connection_string inclui nome da conta e chave (Criar string de conexão) ou você também pode fornecer aqui a URL da conta de armazenamento e o nome da conta e a chave da conta como parâmetros separados (consulte os parâmetros account_name e account_key)
• container_name - Nome do contêiner
• blobpath - caminho do arquivo. Suporta os seguintes curingas no modo readonly: *, **, ?, {abc,def} e {N..M}, em que N, M — números, 'abc', 'def' — strings.
• account_name - se storage_account_url for usado, o nome da conta pode ser especificado aqui
• account_key - se storage_account_url for usado, a chave da conta pode ser especificada aqui
• 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. (equivale a definir como auto).
• partition_strategy – Opções: WILDCARD ou HIVE. WILDCARD exige um {_partition_id} no caminho, que é substituído pela chave de partição. HIVE não permite curingas, pressupõe que o caminho seja a raiz da tabela e gera diretórios particionados no estilo Hive com Snowflake IDs como nomes de arquivo e o formato do arquivo como extensão. O padrão é WILDCARD
• partition_columns_in_data_file - 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.

Exemplo

Os usuários podem usar o emulador Azurite para desenvolvimento local do Azure Storage. Mais detalhes aqui. Se estiver usando uma instância local do Azurite, talvez seja necessário substituir http://localhost:10000 por http://azurite1:10000 nos comandos abaixo, em que assumimos que o Azurite está disponível no host azurite1.

CREATE TABLE test_table (key UInt64, data String)
    ENGINE = AzureBlobStorage('DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite1:10000/devstoreaccount1/;', 'testcontainer', 'test_table', 'CSV');

INSERT INTO test_table VALUES (1, 'a'), (2, 'b'), (3, 'c');

SELECT * FROM test_table;

┌─key──┬─data──┐
│  1   │   a   │
│  2   │   b   │
│  3   │   c   │
└──────┴───────┘

​

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 for desconhecido, o valor é NULL.
• _time — Data e hora da última modificação do arquivo. Tipo: Nullable(DateTime). Se a data e hora forem desconhecidas, o valor é NULL.

​

Autenticação

Atualmente, há 3 formas de autenticação:

• Managed Identity - Pode ser usada ao fornecer um endpoint, connection_string ou storage_account_url.
• SAS Token - Pode ser usado ao fornecer um endpoint, connection_string ou storage_account_url. Ele é identificado pela presença de ? na URL. Consulte azureBlobStorage para ver exemplos.
• Workload Identity - Pode ser usada ao fornecer um endpoint ou storage_account_url. Se o parâmetro use_workload_identity estiver definido na configuração, a Workload Identity será usada para autenticação.

​

Cache de dados

O mecanismo de tabela Azure oferece suporte ao cache de dados em disco local. Consulte as opções de configuração e o uso do cache do sistema de arquivos nesta seção. O cache é feito com base no caminho e no ETag do objeto de armazenamento, portanto o ClickHouse não lerá uma versão desatualizada do cache.

Para habilitar o cache, use a configuração filesystem_cache_name = '<name>' e enable_filesystem_cache = 1.

SELECT *
FROM azureBlobStorage('DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite1:10000/devstoreaccount1/;', 'testcontainer', 'test_table', 'CSV')
SETTINGS filesystem_cache_name = 'cache_for_azure', enable_filesystem_cache = 1;

1. adicione a seção a seguir ao arquivo de configuração do ClickHouse:

<clickhouse>
    <filesystem_caches>
        <cache_for_azure>
            <path>path to cache directory</path>
            <max_size>10Gi</max_size>
        </cache_for_azure>
    </filesystem_caches>
</clickhouse>

2. reutilize a configuração de cache (e, portanto, o armazenamento em cache) da seção storage_configuration do ClickHouse, descrita aqui

​

PARTITION BY

PARTITION BY — Opcional. Na maioria dos casos, você não precisa de uma chave de partição e, quando ela é necessária, em geral não precisa ser mais granular do que mensal. O particionamento não acelera consultas (ao contrário da expressão ORDER BY). Você nunca deve usar um particionamento granular demais. Não particione seus dados por identificadores ou nomes de clientes (em vez disso, use o identificador ou o nome do cliente como a primeira coluna na expressão ORDER BY).

Para particionar por mês, use a expressão toYYYYMM(date_column), em que date_column é uma coluna com uma data do tipo Date. Os nomes das partições aqui têm o formato "YYYYMM".

​

Estratégia de particionamento

WILDCARD (padrão): substitui o caractere curinga {_partition_id} no caminho do arquivo pela chave de partição real. A leitura não é suportada.

HIVE implementa o particionamento no estilo Hive para leituras & gravações. A leitura é implementada com um padrão glob recursivo. A gravação gera arquivos no seguinte formato: <prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>.

Observação: ao usar a estratégia de particionamento HIVE, a configuração use_hive_partitioning não tem efeito.

Exemplo de estratégia de particionamento HIVE:

arthur :) create table azure_table (year UInt16, country String, counter UInt8) ENGINE=AzureBlobStorage(account_name='devstoreaccount1', account_key='Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==', storage_account_url = 'http://localhost:30000/devstoreaccount1', container='cont', blob_path='hive_partitioned', format='Parquet', compression='auto', partition_strategy='hive') PARTITION BY (year, country);

arthur :) insert into azure_table values (2020, 'Russia', 1), (2021, 'Brazil', 2);

arthur :) select _path, * from azure_table;

   ┌─_path──────────────────────────────────────────────────────────────────────┬─year─┬─country─┬─counter─┐
1. │ cont/hive_partitioned/year=2020/country=Russia/7351305360873664512.parquet │ 2020 │ Russia  │       1 │
2. │ cont/hive_partitioned/year=2021/country=Brazil/7351305360894636032.parquet │ 2021 │ Brazil  │       2 │
   └────────────────────────────────────────────────────────────────────────────┴──────┴─────────┴─────────┘

​

Veja também

Função de tabela do Azure Blob Storage