Skip to main content

​
O adaptador dbt-clickhouse

dbt (data build tool) permite que engenheiros de analytics transformem dados em seus warehouses simplesmente escrevendo instruções select. O dbt cuida de materializar essas instruções select em objetos no banco de dados, na forma de tabelas e views, realizando o T de Extrair, Carregar e Transformar (ELT). Você pode criar um modelo definido por uma instrução SELECT. No dbt, esses modelos podem ser referenciados entre si e organizados em camadas, permitindo a construção de conceitos de nível mais alto. O SQL boilerplate necessário para conectar os modelos é gerado automaticamente. Além disso, o dbt identifica as dependências entre os modelos e garante que eles sejam criados na ordem adequada usando um grafo acíclico direcionado (DAG). O dbt é compatível com o ClickHouse por meio de um adaptador com suporte a ClickHouse.

​
Recursos suportados

Lista de recursos suportados:
  • Materialização de tabela
  • Materialização de view
  • Materialização incremental
  • Materialização incremental do tipo Microbatch
  • Materializações de visão materializada (usa a forma TO de MATERIALIZED VIEW, experimental)
  • Seeds
  • Sources
  • Geração de documentação
  • Testes
  • Snapshots
  • A maioria das macros do dbt-utils (agora incluídas no dbt-core)
  • Materialização efêmera
  • Materialização de tabela distribuída (experimental)
  • Materialização incremental distribuída (experimental)
  • Materialização de dicionário (experimental)
  • Contratos
  • Configurações de coluna específicas do ClickHouse (Codec, TTL…)
  • Configurações de tabela específicas do ClickHouse (índices, projeções…)
Todos os recursos até o dbt-core 1.10 têm suporte, incluindo a flag --sample, e todos os avisos de descontinuação já foram corrigidos para versões futuras. Integrações de catálogo (por exemplo, Iceberg), introduzidas no dbt 1.10, ainda não têm suporte nativo no adaptador, mas há soluções alternativas disponíveis. Consulte a seção Suporte a catálogo para mais detalhes. Este adaptador ainda não está disponível para uso no dbt Cloud, mas esperamos disponibilizá-lo em breve. Entre em contato com o suporte para obter mais informações.

​
conceitos do dbt e materializações compatíveis

O dbt introduz o conceito de modelo. Ele é definido como uma instrução SQL, potencialmente combinando muitas tabelas. Um modelo pode ser “materializado” de várias maneiras. Uma materialização representa uma estratégia de build para a consulta select do modelo. O código por trás de uma materialização é um SQL boilerplate que envolve sua consulta SELECT em uma instrução para criar uma nova relação ou atualizar uma relação existente. O dbt fornece 5 tipos de materialização. Todos eles são compatíveis com dbt-clickhouse:
  • view (padrão): O modelo é construído como uma view no banco de dados. No ClickHouse, isso é criado como uma view.
  • table: O modelo é construído como uma tabela no banco de dados. No ClickHouse, isso é criado como uma table.
  • ephemeral: O modelo não é construído diretamente no banco de dados, mas é incorporado aos modelos dependentes como CTEs (expressões de tabela comuns).
  • incremental: O modelo é inicialmente materializado como uma tabela e, em execuções subsequentes, o dbt insere novas linhas e atualiza as linhas alteradas na tabela.
  • materialized view: O modelo é construído como uma visão materializada no banco de dados. No ClickHouse, isso é criado como uma materialized view.
Sintaxe e cláusulas adicionais definem como esses modelos devem ser atualizados se os dados subjacentes mudarem. Em geral, o dbt recomenda começar com a materialização view até que o desempenho se torne uma preocupação. A materialização table oferece melhora de desempenho em query time ao capturar os resultados da consulta do modelo como uma tabela, em troca de maior uso de armazenamento. A abordagem incremental vai além disso e permite que atualizações subsequentes nos dados subjacentes sejam capturadas na tabela de destino. Os itens a seguir são recursos experimentais no dbt-clickhouse:

​
Configuração do dbt e do adaptador do ClickHouse

​
Instale o dbt-core e o dbt-clickhouse

O dbt oferece várias opções para instalar a interface de linha de comando (CLI), detalhadas aqui. Recomendamos usar o pip para instalar tanto o dbt quanto o dbt-clickhouse.

​
Forneça ao dbt os detalhes da conexão da nossa instância do ClickHouse.

Configure o perfil clickhouse-service no arquivo ~/.dbt/profiles.yml e informe as propriedades schema, host, port, user e password. A lista completa de opções de configuração da conexão está disponível na página Recursos e configurações:

​
Criar um projeto dbt

Agora você pode usar este perfil em um dos seus projetos existentes ou criar um novo usando:
Dentro do diretório project_name, atualize o arquivo dbt_project.yml para especificar um nome de perfil para se conectar ao servidor ClickHouse.

​
Testar a conexão

Execute dbt debug na CLI para confirmar se o dbt consegue se conectar ao ClickHouse. Verifique se a resposta inclui Connection test: [OK connection ok], indicando que a conexão foi bem-sucedida. Acesse a página de guias para saber mais sobre como usar o dbt com o ClickHouse.

​
Testando e implantando seus modelos (CI/CD)

Há muitas maneiras de testar e implantar seu projeto dbt. O dbt traz algumas sugestões de fluxos de trabalho com boas práticas e jobs de CI. Vamos abordar várias estratégias, mas tenha em mente que elas podem precisar de ajustes significativos para se adequar ao seu caso de uso específico.

​
CI/CD com testes de dados simples e testes unitários

Uma forma simples de dar início ao seu pipeline de CI é executar um cluster do ClickHouse no seu job e, em seguida, executar seus modelos nele. Você pode inserir dados de exemplo nesse cluster antes de executar seus modelos. Também pode usar um seed para preencher o ambiente de staging com um subconjunto dos seus dados de produção. Depois que os dados forem inseridos, você poderá executar seus testes de dados e seus testes unitários. Sua etapa de CD pode ser tão simples quanto executar dbt build no seu cluster de produção do ClickHouse.

​
Estágio de CI/CD mais completo: use dados recentes e teste apenas os modelos afetados

Uma estratégia comum é usar jobs de Slim CI, em que apenas os modelos modificados (e suas dependências upstream e downstream) são implantados novamente. Essa abordagem usa artefatos das suas execuções em produção (ou seja, o manifest do dbt) para reduzir o tempo de execução do seu projeto e garantir que não haja divergência de schema entre ambientes. Para manter seus ambientes de desenvolvimento em sincronia e evitar executar seus modelos em implantações desatualizadas, você pode usar clone ou até mesmo defer. No ClickHouse, dbt clone copia tabelas MergeTree usando uma instrução CLONE zero-copy — consulte Clonagem de modelos com dbt clone abaixo para obter detalhes. Recomendamos usar um cluster ou serviço ClickHouse dedicado para o ambiente de teste (ou seja, um ambiente de staging) para evitar impactar a operação do seu ambiente de produção. Para garantir que o ambiente de teste seja representativo, é importante usar um subconjunto dos seus dados de produção, além de executar o dbt de forma a evitar divergência de schema entre ambientes.
  • Se você não precisa de dados recentes para testar, pode restaurar um backup dos seus dados de produção no ambiente de staging.
  • Se você precisa de dados recentes para testar, pode usar uma combinação da table function remoteSecure() com views materializadas atualizáveis para inserir dados na frequência desejada. Outra opção é usar armazenamento de objetos como intermediário e gravar dados periodicamente a partir do seu serviço de produção, depois importá-los para o ambiente de staging usando table functions de armazenamento de objetos ou ClickPipes (para ingestão contínua).
Usar um ambiente dedicado para testes de CI também permite realizar testes manuais sem impactar seu ambiente de produção. Por exemplo, você pode querer apontar uma ferramenta de BI para esse ambiente para testes. Para a implantação (ou seja, a etapa de CD), recomendamos usar os artefatos das suas implantações em produção para atualizar apenas os modelos que mudaram. Isso exige configurar armazenamento de objetos (por exemplo, S3) como armazenamento intermediário para seus artefatos do dbt. Depois que isso estiver configurado, você pode executar um comando como dbt build --select state:modified+ --state path/to/last/deploy/state.json para reconstruir seletivamente o menor conjunto de modelos necessário com base no que mudou desde a última execução em produção.

​
Clonagem de modelos com dbt clone

A partir do dbt-clickhouse 1.10.1, o comando dbt clone usa a instrução zero-copy CREATE OR REPLACE TABLE ... CLONE AS ... do ClickHouse para clonar modelos materializados como tabelas que usam um motor da família MergeTree. Isso cria uma cópia da tabela sem duplicar as partes de dados subjacentes, o que torna essa uma forma rápida e econômica de sincronizar ambientes — por exemplo, ao configurar um ambiente de desenvolvimento ou Slim CI a partir do estado de produção. Os modelos que não podem ser clonados dessa forma usam o comportamento padrão do dbt, que cria uma visão apontando para a relação de origem:
  • Tabelas que usam motores diferentes de MergeTree
  • Materializações Distributed
Para modelos de visão materializada, apenas a tabela de destino é clonada; a própria visão materializada é criada sobre a tabela clonada.

​
Solução de problemas comuns

​
Conexões

Se você tiver problemas para se conectar ao ClickHouse pelo dbt, verifique se os seguintes critérios foram atendidos:
  • O motor deve ser um dos motores compatíveis.
  • Você deve ter permissões adequadas para acessar o banco de dados.
  • Se você não estiver usando o motor de tabela padrão do banco de dados, deverá especificar um motor de tabela na configuração do seu modelo.

​
Entendendo operações de longa duração

Algumas operações podem levar mais tempo do que o esperado devido a consultas específicas do ClickHouse. Para ter mais visibilidade sobre quais consultas estão demorando mais, aumente o nível de log para debug — isso exibirá o tempo gasto por cada consulta. Por exemplo, isso pode ser feito acrescentando --log-level debug aos comandos do dbt.

​
Correlacionando execuções do dbt com consultas do ClickHouse

Para obter detalhes do lado do servidor, a partir do dbt-clickhouse 1.10.1, cada instrução executada pelo adaptador recebe seu próprio ID de consulta (um UUID4), que é encaminhado ao ClickHouse. O ID da instrução principal de um modelo é retornado na adapter_response do respectivo resultado do dbt e, portanto, está disponível em artefatos do dbt, como run_results.json. Você pode consultá-lo na tabela system.query_log para verificar a duração e o uso de recursos dessa instrução:
Observe que uma materialização geralmente executa várias instruções por modelo (DDL, inserts etc.), cada uma com seu próprio ID de consulta; o ID em run_results.json identifica apenas a instrução principal do modelo. Para encontrar todas as instruções associadas a uma execução, filtre system.query_log pelo comentário de consulta do dbt incorporado ao texto de cada consulta. O ID de consulta também permite que ferramentas de observabilidade que consomem artefatos do dbt (por exemplo, Elementary) vinculem automaticamente execuções de modelos do dbt às entradas em system.query_log.

​
Limitações

O adaptador atual do ClickHouse para dbt tem várias limitações das quais você deve estar ciente:
  • O plugin usa uma sintaxe que exige o ClickHouse versão 25.3 ou mais recente. Não testamos versões mais antigas do ClickHouse. No momento, também não testamos tabelas Replicated.
  • Diferentes execuções do dbt-adapter podem entrar em conflito se forem executadas ao mesmo tempo, pois internamente podem usar os mesmos nomes de tabela para as mesmas operações. Para mais informações, consulte a issue #420.
  • Atualmente, o adaptador materializa modelos como tabelas usando um INSERT INTO SELECT. Na prática, isso significa duplicação de dados se a execução ocorrer novamente. Datasets muito grandes (PB) podem resultar em tempos de execução extremamente longos, tornando alguns modelos inviáveis. Para melhorar o desempenho, use visões materializadas do ClickHouse implementando a view como materialized: materialization_view. Além disso, procure minimizar o número de linhas retornadas por qualquer consulta usando GROUP BY sempre que possível. Prefira modelos que resumam os dados em vez daqueles que apenas os transformam mantendo a mesma contagem de linhas da origem.
  • Para usar tabelas distribuídas para representar um modelo, você deve criar manualmente as tabelas replicadas subjacentes em cada nó. A tabela distribuída, por sua vez, pode ser criada sobre elas. O adaptador não gerencia a criação do cluster.
  • Quando o dbt cria uma relação (tabela/view) em um banco de dados, ele normalmente a cria como: {{ database }}.{{ schema }}.{{ table/view id }}. O ClickHouse não tem o conceito de schemas. Portanto, o adaptador usa {{schema}}.{{ table/view id }}, em que schema é o banco de dados do ClickHouse.
  • Modelos/CTEs efêmeros não funcionam se forem colocados antes do INSERT INTO em uma instrução de insert do ClickHouse; veja https://github.com/ClickHouse/ClickHouse/issues/30323. Isso não deve afetar a maioria dos modelos, mas é preciso ter cuidado com onde um modelo efêmero é colocado nas definições de modelo e em outras instruções SQL.

​
Fivetran

O conector dbt-clickhouse também está disponível para uso em transformações do Fivetran, permitindo integração e transformação de forma fluida diretamente na plataforma Fivetran com dbt.
Última modificação em 26 de agosto de 2026