Integração do Azure Blob Storage com o ClickHouse Cloud

Conecte seu armazenamento de objetos ao ClickHouse Cloud sem complicações.

O ABS ClickPipe oferece uma maneira totalmente gerenciada e resiliente de realizar a ingestão de dados do Azure Blob Storage no ClickHouse Cloud. Ele oferece suporte tanto à ingestão única quanto à ingestão contínua, com semântica de exactly-once.

Os ClickPipes do ABS podem ser implantados e gerenciados manualmente usando a UI do ClickPipes, bem como de forma programática usando OpenAPI e Terraform.

​

Formatos suportados

• JSON
• CSV
• TSV
• Parquet
• Avro

​

Funcionalidades

​

Ingestão única

O ClickPipe do ABS carregará, em uma única operação em lote, todos os arquivos do contêiner especificado que correspondam a um padrão para a tabela de destino do ClickHouse. Quando a tarefa de ingestão for concluída, o ClickPipe será interrompido automaticamente. Esse modo de ingestão única oferece semântica de exactly-once, garantindo que cada arquivo seja processado de forma confiável e sem duplicações.

​

Ingestão contínua

Quando a ingestão contínua está ativada, o ClickPipes ingere continuamente dados do caminho especificado. Para determinar a ordem de ingestão, o ClickPipe ABS depende da ordem lexicográfica implícita dos arquivos.

​

Ordem lexicográfica

O ABS ClickPipe assume que os arquivos são adicionados a um contêiner em ordem lexicográfica e se baseia nessa ordem implícita para fazer a ingestão dos arquivos sequencialmente. Isso significa que qualquer arquivo novo deve ser lexicograficamente maior que o último arquivo ingerido. Por exemplo, arquivos chamados file1, file2 e file3 serão ingeridos sequencialmente, mas, se um novo file 0 for adicionado ao contêiner, ele será ignorado, porque o nome do arquivo não é lexicograficamente maior que o último arquivo ingerido.

Nesse modo, o ABS ClickPipe faz a carga inicial de todos os arquivos no caminho especificado e, em seguida, verifica se há novos arquivos em um intervalo configurável (por padrão, 30 segundos). Para iniciar a ingestão contínua após um arquivo específico, configure Start after. O ClickPipes ignorará arquivos lexicograficamente menores ou iguais ao valor configurado e continuará ingerindo arquivos mais recentes a partir desse ponto.

​

Correspondência de padrões de arquivo

O Object Storage ClickPipes segue o padrão POSIX para correspondência de padrões de arquivo. Todos os padrões são sensíveis a maiúsculas e minúsculas e correspondem ao caminho completo após o nome do contêiner. Para melhor desempenho, use o padrão mais específico possível (por exemplo, data-2024-*.csv em vez de *.csv).

​

Padrões compatíveis

Padrão	Descrição	Exemplo	Corresponde a
?	Corresponde a exatamente um caractere (excluindo /)	data-?.csv	data-1.csv, data-a.csv, data-x.csv
*	Corresponde a zero ou mais caracteres (excluindo /)	data-*.csv	data-1.csv, data-001.csv, data-report.csv, data-.csv
** Recursivo	Corresponde a zero ou mais caracteres (incluindo /). Permite percorrer diretórios recursivamente.	logs/**/error.log	logs/error.log, logs/2024/error.log, logs/2024/01/error.log

Exemplos:

• https://storageaccount.blob.core.windows.net/container/folder/*.csv
• https://storageaccount.blob.core.windows.net/container/logs/**/data.json
• https://storageaccount.blob.core.windows.net/container/file-?.parquet
• https://storageaccount.blob.core.windows.net/container/data-2024-*.csv.gz

​

Padrões sem suporte

Padrão	Descrição	Exemplo	Alternativas
{abc,def}	Expansão com chaves - alternativas	{logs,data}/file.csv	Crie ClickPipes separados para cada caminho.
{N..M}	Expansão de intervalo numérico	file-{1..100}.csv	Use file-*.csv ou file-?.csv.

Exemplos:

• https://storageaccount.blob.core.windows.net/container/{documents-01,documents-02}.json
• https://storageaccount.blob.core.windows.net/container/file-{1..100}.csv
• https://storageaccount.blob.core.windows.net/container/{logs,metrics}/data.parquet

​

Semântica de exactly-once

Vários tipos de falha podem ocorrer durante a ingestão de grandes conjuntos de dados, o que pode resultar em inserções parciais ou dados duplicados. O Object Storage ClickPipes é resiliente a falhas de inserção e oferece semântica de exactly-once. Isso é feito com o uso de tabelas temporárias de “staging”. Os dados são primeiro inseridos nas tabelas de staging. Se algo der errado com essa inserção, a tabela de staging pode ser truncada e a inserção pode ser repetida a partir de um estado limpo. Somente quando uma inserção é concluída com sucesso, as partições na tabela de staging são movidas para a tabela de destino. Para saber mais sobre essa estratégia, confira esta postagem no blog.

​

Colunas virtuais

Para rastrear quais arquivos foram ingeridos, inclua a coluna virtual _file na lista de mapeamento de colunas. A coluna virtual _file contém o nome do arquivo do objeto de origem e pode ser usada para consultar quais arquivos já foram processados.

​

Controle de acesso

​

Permissões

O ClickPipe ABS oferece suporte apenas a contêineres privados. Contêineres públicos não são compatíveis.

Os contêineres devem permitir as ações s3:GetObject e s3:ListBucket na política do bucket.

​

Autenticação

No momento, a autenticação com o Microsoft Entra ID (incluindo Managed Identities) não é compatível.

A autenticação do Azure Blob Storage usa uma string de conexão, que oferece suporte tanto a chaves de acesso quanto a assinaturas de acesso compartilhado (SAS).

​

Chave de acesso

Para se autenticar com uma chave de acesso da conta, forneça uma string de conexão no formato a seguir:

DefaultEndpointsProtocol=https;AccountName=storage-account-name;AccountKey=account-access-key;EndpointSuffix=core.windows.net

Você pode encontrar o nome da sua conta de armazenamento e a chave de acesso no Azure Portal, em Storage Account > Access keys.

​

Assinatura de Acesso Compartilhado (SAS)

Para autenticar com uma Assinatura de Acesso Compartilhado (SAS), forneça uma string de conexão que inclua o token SAS:

BlobEndpoint=https://storage-account-name.blob.core.windows.net/;SharedAccessSignature=sas-token

Gere um SAS token no Azure Portal em Storage Account > Shared access signature com as permissões adequadas (Read, List) para o contêiner e os blobs que você deseja ingerir.

​

Acesso de rede

Os ClickPipes do ABS usam dois caminhos de rede distintos para descoberta de metadados e ingestão de dados: o serviço ClickPipes e o serviço ClickHouse Cloud, respectivamente. Se você quiser configurar uma camada adicional de segurança de rede (por exemplo, por motivos de compliance), o acesso de rede deve ser configurado para ambos os caminhos.

O controle de acesso baseado em IP não funciona se o seu contêiner do Azure Blob Storage estiver na mesma região do Azure que o seu serviço ClickHouse Cloud. Quando ambos os serviços estão co-localizados, o tráfego é roteado pela rede interna do Azure, em vez da internet pública.

• Para controle de acesso baseado em IP, as regras de rede IP do firewall do seu Azure Storage devem permitir os IPs estáticos da região do serviço ClickPipes listados aqui, bem como os IPs estáticos do serviço ClickHouse Cloud. Para obter os IPs estáticos da sua região do ClickHouse Cloud, abra um terminal e execute:

  # Substitua <your-region> pela sua região do ClickHouse Cloud
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.azure[] | select(.region == "<your-region>") | .egress_ips[]'
  

​

Configurações avançadas

O ClickPipes fornece padrões sensatos que atendem aos requisitos da maioria dos casos de uso. Se o seu caso de uso exigir ajustes finos adicionais, você poderá ajustar as seguintes configurações:

Configuração	Valor padrão	Descrição
Max insert bytes	10GB	Número de bytes a serem processados em um único lote de inserção.
Max file count	100	Número máximo de arquivos a serem processados em um único lote de inserção.
Max threads	auto(3)	Número máximo de threads concorrentes para processamento de arquivos.
Max insert threads	1	Número máximo de threads de inserção concorrentes para processamento de arquivos.
Min insert block size bytes	1GB	Tamanho mínimo, em bytes, do bloco que pode ser inserido em uma tabela.
Max download threads	4	Número máximo de threads de download concorrentes.
Object storage polling interval	30s	Configura o período máximo de espera antes de inserir dados no cluster do ClickHouse.
Start after	None	Para ingestão contínua ordenada, ignora arquivos lexicograficamente menores ou iguais ao nome de arquivo ou caminho configurado.
Parallel distributed insert select	2	Configuração de insert select distribuído em paralelo.
Parallel view processing	false	Define se o envio para views anexadas deve ser habilitado de forma concorrente em vez de sequencial.
Use cluster function	true	Define se os arquivos devem ser processados em paralelo em vários nós.

​

Escalonamento

Object Storage ClickPipes são escalados com base no tamanho mínimo do serviço ClickHouse, determinado pelas configurações de autoscaling vertical. O tamanho do ClickPipe é definido quando o pipe é criado. Alterações posteriores nas configurações do serviço ClickHouse não afetam o tamanho do ClickPipe.

Para aumentar o throughput em jobs de ingestão de grande porte, recomendamos escalar o serviço ClickHouse antes de criar o ClickPipe.

​

Limitações conhecidas

​

Tamanho do arquivo

O ClickPipes só tentará fazer a ingestão de objetos com 10 GB ou menos. Se um arquivo tiver mais de 10 GB, um erro será registrado na tabela de erro dedicada do ClickPipes.

​

Latência

Para contêineres com mais de 100.000 arquivos, as operações LIST do Azure Blob Storage adicionam latência na detecção de novos arquivos, além do intervalo de polling padrão:

• < 100 mil arquivos: ~30 segundos (intervalo de polling padrão)
• 100 mil arquivos: ~40-45 segundos
• 250 mil arquivos: ~55-70 segundos
• 500 mil+ arquivos: pode ultrapassar 90 segundos

Para ingestão contínua, o ClickPipes precisa varrer o contêiner para identificar arquivos novos lexicograficamente maiores que o último arquivo ingerido. Recomendamos organizar os arquivos em contêineres menores ou usar estruturas hierárquicas de diretórios para reduzir o número de arquivos por operação de listagem.

​

Suporte a views

Visões materializadas na tabela de destino também são compatíveis. O ClickPipes criará tabelas de staging não apenas para a tabela de destino, mas também para qualquer visão materializada dependente.

Não criamos tabelas de staging para views não materializadas. Isso significa que, se você tiver uma tabela de destino com uma ou mais visões materializadas dependentes, essas visões materializadas devem evitar selecionar dados por meio de uma view da tabela de destino. Caso contrário, você poderá acabar com dados ausentes na visão materializada.

​

Dependências

Quaisquer alterações na tabela de destino, em suas visões materializadas (incluindo visões materializadas em cascata) ou nas tabelas de destino das visões materializadas enquanto o ClickPipe estiver em execução resultarão em erros que exigirão nova tentativa. Para fazer alterações de esquema nessas dependências, você deve pausar o ClickPipe, aplicar as alterações e depois retomá-lo.