Skip to main content
Nesta seção, apresentamos a documentação de alguns dos recursos disponíveis para o dbt com ClickHouse.

Configurações do Profile.yml

Para se conectar ao ClickHouse pelo dbt, você precisará adicionar um perfil ao arquivo profiles.yml. Um perfil do ClickHouse segue a sintaxe abaixo:

Schema vs Banco de dados

O identificador de relation do model do dbt database.schema.table não é compatível com o ClickHouse porque o ClickHouse não dá suporte a schema. Por isso, usamos uma abordagem simplificada, schema.table, em que schema é o banco de dados do ClickHouse. Não é recomendável usar o banco de dados default.

Aviso sobre a instrução SET

Em muitos ambientes, usar a instrução SET para fazer com que uma configuração do ClickHouse persista em todas as consultas do DBT não é confiável e pode causar falhas inesperadas. Isso é particularmente verdadeiro ao usar conexões HTTP por meio de um balanceador de carga que distribui as consultas entre vários nós (como no ClickHouse Cloud), embora, em algumas circunstâncias, isso também possa acontecer com conexões nativas do ClickHouse. Assim, recomendamos definir as configurações necessárias do ClickHouse na propriedade “custom_settings” do perfil do DBT como prática recomendada, em vez de depender de uma instrução “SET” em um pre-hook, como tem sido sugerido ocasionalmente.

Configurando quote_columns

Para evitar um aviso, certifique-se de definir explicitamente um valor para quote_columns no seu dbt_project.yml. Consulte a documentação sobre quote_columns para mais informações.

Sobre o cluster do ClickHouse

Ao usar um cluster do ClickHouse, você precisa considerar dois pontos:
  • Definir a configuração cluster.
  • Garantir a consistência de leitura após escrita, especialmente se você estiver usando mais de um threads.

Configuração de cluster

A configuração cluster no perfil permite que o dbt-clickhouse seja executado em um cluster ClickHouse. Se cluster estiver definida no perfil, todos os modelos serão criados com a cláusula ON CLUSTER por padrão — exceto os que usam o motor Replicated. Isso inclui:
  • Criação de banco de dados
  • Materializações de view
  • Materializações de tabela e incrementais
  • Materializações distribuídas
Motores Replicated não incluirão a cláusula ON CLUSTER, pois foram projetados para gerenciar a replicação internamente. Para desativar a criação baseada em cluster para um modelo específico, adicione a config disable_on_cluster:
materializações do tipo table e incremental com engine não replicado não serão afetadas pela configuração cluster (o modelo será criado apenas no nó ao qual você está conectado). Compatibilidade Se um modelo tiver sido criado sem a configuração cluster, o dbt-clickhouse detectará essa situação e executará todo o DDL/DML sem a cláusula on cluster para esse modelo.

Consistência de leitura após escrita

O dbt depende de um modelo de consistência de leitura após inserção. Isso não é compatível com clusters do ClickHouse com mais de uma réplica se você não puder garantir que todas as operações sejam direcionadas à mesma réplica. Você pode até não encontrar problemas no uso diário do dbt, mas, dependendo do seu cluster, há algumas estratégias para garantir isso:
  • Se você estiver usando um cluster do ClickHouse Cloud, basta definir select_sequential_consistency: 1 na propriedade custom_settings do seu perfil. Você pode encontrar mais informações sobre essa configuração aqui.
  • Se você estiver usando um cluster self-hosted, certifique-se de que todas as solicitações do dbt sejam enviadas para a mesma réplica do ClickHouse. Se houver um balanceador de carga na frente dele, tente usar algum mecanismo de replica aware routing/sticky sessions para sempre alcançar a mesma réplica. Adicionar a configuração select_sequential_consistency = 1 em clusters fora do ClickHouse Cloud não é recomendado.

Macros adicionais do ClickHouse

Macros utilitárias de materialização de modelos

As macros a seguir estão incluídas para facilitar a criação de tabelas e views específicas do ClickHouse:
  • engine_clause — Usa a propriedade de configuração engine do modelo para definir um engine de tabela do ClickHouse. O dbt-clickhouse usa o engine MergeTree por padrão.
  • partition_cols — Usa a propriedade de configuração partition_by do modelo para definir uma chave de partição do ClickHouse. Nenhuma chave de partição é definida por padrão.
  • order_cols — Usa a configuração order_by do modelo para definir uma chave de ordenação/ORDER BY do ClickHouse. Se não for especificada, o ClickHouse usará uma tuple() vazia e a tabela não será ordenada
  • primary_key_clause — Usa a propriedade de configuração primary_key do modelo para definir uma chave primária do ClickHouse. Por padrão, a chave primária é definida, e o ClickHouse usará a cláusula ORDER BY como chave primária.
  • on_cluster_clause — Usa a propriedade cluster do perfil para adicionar uma cláusula ON CLUSTER a determinadas operações do dbt: materializações distribuídas, criação de views e criação de banco de dados.
  • ttl_config — Usa a propriedade de configuração ttl do modelo para definir uma expressão de TTL de tabela do ClickHouse. Nenhum TTL é definido por padrão.

Macro auxiliar s3Source

A macro s3source simplifica o processo de selecionar dados no ClickHouse diretamente do S3 usando a função de tabela S3 do ClickHouse. Ela funciona preenchendo os parâmetros da função de tabela S3 a partir de um dicionário de configuração nomeado (o nome do dicionário deve terminar em s3). A macro primeiro procura o dicionário nas vars do perfil e, depois, na configuração do modelo. O dicionário pode conter qualquer uma das seguintes chaves usadas para preencher os parâmetros da função de tabela S3: Consulte o arquivo de teste do S3 para ver exemplos de como usar esta macro.

Suporte a macros entre bancos de dados

Atualmente, o dbt-clickhouse oferece suporte à maioria das macros entre bancos de dados incluídas no dbt Core, com as seguintes exceções:
  • A função SQL split_part é implementada no ClickHouse usando a função splitByChar. Essa função exige o uso de uma string constante como delimitador de divisão, portanto o parâmetro delimeter usado nessa macro será interpretado como uma string, e não como um nome de coluna
  • Da mesma forma, a função SQL replace no ClickHouse exige strings constantes para os parâmetros old_chars e new_chars, portanto esses parâmetros serão interpretados como strings, e não como nomes de colunas, ao invocar essa macro.

Suporte a catálogos

Status da integração de catálogo do dbt

O dbt Core v1.10 introduziu suporte à integração de catálogo, permitindo que adaptadores materializem modelos em catálogos externos que gerenciam formatos de tabela abertos, como o Apache Iceberg. Esse recurso ainda não foi implementado nativamente no dbt-clickhouse. Você pode acompanhar o progresso da implementação desse recurso na issue #489 do GitHub.

Suporte a catálogos no ClickHouse

O ClickHouse adicionou recentemente suporte nativo a tabelas Apache Iceberg e catálogos de dados. A maioria dos recursos ainda é experimental, mas você já pode usá-los com uma versão recente do ClickHouse.
  • Você pode usar o ClickHouse para consultar tabelas Iceberg armazenadas em armazenamento de objetos (S3, Azure Blob Storage, Google Cloud Storage) usando o motor de tabela Iceberg e a função de tabela iceberg.
  • Além disso, o ClickHouse oferece o motor de banco de dados DataLakeCatalog, que permite a conexão com catálogos de dados externos, incluindo AWS Glue Catalog, Databricks Unity Catalog, Hive Metastore e REST Catalogs. Isso permite consultar dados em formatos de tabela abertos (Iceberg, Delta Lake) diretamente de catálogos externos, sem duplicação de dados.

Alternativas para trabalhar com Iceberg e catálogos

Você pode ler dados de tabelas Iceberg ou catálogos no seu projeto dbt se já os tiver definido no seu cluster ClickHouse com as ferramentas mencionadas acima. Você pode usar a funcionalidade source do dbt para referenciar essas tabelas nos seus projetos dbt. Por exemplo, se quiser acessar suas tabelas em um REST Catalog, você pode:
  1. Criar um banco de dados apontando para um catálogo externo:
  1. Defina o banco de dados do catálogo e suas tabelas como sources no dbt: lembre-se de que as tabelas já devem estar disponíveis no ClickHouse
  1. Use as tabelas de catálogo em seus modelos dbt:

Observações sobre as soluções alternativas

Os pontos positivos dessas soluções alternativas são:
  • Você terá acesso imediato a diferentes tipos de tabelas externas e catálogos externos sem precisar esperar pela integração nativa de catálogos do dbt.
  • Você terá um caminho de migração tranquilo quando o suporte nativo a catálogos estiver disponível.
Mas, no momento, há algumas limitações:
  • Configuração manual: tabelas Iceberg e bancos de dados de catálogo precisam ser criados manualmente no ClickHouse antes de poderem ser referenciados no dbt.
  • Sem DDL no nível de catálogo: o dbt não consegue gerenciar operações no nível de catálogo, como criar ou excluir tabelas Iceberg em catálogos externos. Portanto, no momento, você não poderá criá-las pelo conector do dbt. A criação de tabelas com os motores Iceberg() poderá ser adicionada no futuro.
  • Operações de escrita: no momento, a escrita em tabelas Iceberg/Data Catalog é limitada. Consulte a documentação do ClickHouse para entender quais opções estão disponíveis.
Última modificação em 24 de julho de 2026