Skip to main content
Esta seção apresenta todas as materializações disponíveis no dbt-clickhouse, incluindo recursos experimentais.

Configurações gerais de materialização

A tabela a seguir mostra as configurações compartilhadas por algumas das materializações disponíveis. Para informações mais detalhadas sobre configurações gerais de modelos do dbt, consulte a documentação do dbt:

Motores de tabela compatíveis

Observação: para visões materializadas, todos os motores da família *MergeTree são compatíveis.

Motores de tabela com suporte experimental

Se você encontrar problemas para se conectar ao ClickHouse no dbt com um dos motores acima, abra uma issue aqui.

Uma observação sobre as configurações do modelo

O ClickHouse tem vários tipos/níveis de “configurações”. Na configuração do modelo acima, dois desses tipos são configuráveis. settings se refere à cláusula SETTINGS usada em instruções DDL do tipo CREATE TABLE/VIEW, portanto, em geral, são configurações específicas do motor de tabela do ClickHouse em questão. O novo query_settings é usado para adicionar uma cláusula SETTINGS às consultas INSERT e DELETE usadas na materialização do modelo ( incluindo materializações incrementais). Há centenas de configurações no ClickHouse, e nem sempre é claro qual é uma configuração de “tabela” e qual é uma configuração de “usuário” (embora estas últimas geralmente estejam disponíveis na tabela system.settings.) Em geral, recomenda-se usar os valores padrão, e qualquer uso dessas propriedades deve ser cuidadosamente pesquisado e testado.

Configuração de coluna

OBSERVAÇÃO: As opções de configuração de coluna abaixo exigem que os contratos de modelo estejam habilitados.

Exemplo de configuração de esquema

Adicionando tipos complexos

O dbt determina automaticamente o tipo de dado de cada coluna ao analisar o SQL usado para criar o modelo. No entanto, em alguns casos, esse processo pode não identificar corretamente o tipo de dado, o que gera conflitos com os tipos especificados na propriedade de contrato data_type. Para resolver isso, recomendamos usar a função CAST() no SQL do modelo para definir explicitamente o tipo desejado. Por exemplo:

Materialização: view

Um modelo do dbt pode ser criado como uma view no ClickHouse e configurado com a seguinte sintaxe: Arquivo do projeto (dbt_project.yml):
Ou bloco de configuração (models/<model_name>.sql):

Materialização: tabela

Um modelo do dbt pode ser criado como uma tabela no ClickHouse e configurado com a seguinte sintaxe: Arquivo do projeto (dbt_project.yml):
Ou no bloco de configuração (models/<model_name>.sql):

Data skipping indexes

Você pode adicionar data skipping indexes às materializações table usando a configuração indexes:

Projeções

Você pode adicionar projeções às materializações table e distributed_table por meio da configuração projections. Cada entrada de projeção exige uma chave query ou index (não ambas). Observação: Em tabelas distribuídas, a projeção é aplicada às tabelas _local, não à tabela proxy distribuída. Observação: Especificar query e index na mesma entrada de projeção gera um erro em tempo de compilação.

Projeções de consulta

Use query para definir uma consulta completa de projeção:

Projeções de índice

Use index como uma abreviação sintática para projeções de índice leves que usam a coluna virtual _part_offset. Passe o nome de uma única coluna ou uma lista de colunas para ordenar:
dbt-clickhouse gera automaticamente DDL adequada à versão:

Materialização: incremental

O modelo de tabela será reconstruído a cada execução do dbt. Isso pode ser inviável e extremamente custoso para conjuntos de resultados maiores ou transformações complexas. Para enfrentar esse desafio e reduzir o tempo de compilação, um modelo do dbt pode ser criado como uma tabela incremental do ClickHouse e configurado com a seguinte sintaxe: Definição do modelo em dbt_project.yml:
Ou o bloco de configuração em models/<model_name>.sql:

Configurações

As configurações específicas deste tipo de materialização estão listadas abaixo:

Estratégias de modelos incrementais

dbt-clickhouse oferece suporte a três estratégias de modelos incrementais.

A Estratégia Padrão (Legada)

Historicamente, o ClickHouse oferecia apenas suporte limitado a atualizações e exclusões, na forma de “mutações” assíncronas. Para emular o comportamento esperado do dbt, o dbt-clickhouse, por padrão, cria uma nova tabela temporária contendo todos os registros “antigos” não afetados (não excluídos, não alterados), além de quaisquer registros novos ou atualizados, e então troca essa tabela temporária pela relação incremental existente do modelo. Esta é a única estratégia que preserva a relação original caso algo dê errado antes da conclusão da operação; no entanto, como envolve uma cópia completa da tabela original, sua execução pode ser bastante cara e lenta.

A estratégia Delete+Insert

A estratégia delete+insert usa exclusões leves para remover as linhas afetadas e inserir as novas. Como não copia a tabela inteira, apresenta um desempenho significativamente melhor que a estratégia “legado”. Definir use_lw_deletes: true no perfil torna delete+insert a estratégia incremental padrão. Há ressalvas importantes ao usar essa estratégia:
  • Ela opera diretamente na tabela afetada, sem criar tabelas intermediárias ou temporárias. Portanto, se ocorrer um problema durante a operação, os dados no modelo incremental provavelmente ficarão em um estado inválido.
  • Ela exige a configuração allow_nondeterministic_mutations do ClickHouse. O adaptador a habilita automaticamente em suas próprias sessões, quando possível. Quando não é possível habilitá-la (por exemplo, se ela for somente leitura para seu usuário do dbt), o comportamento depende de como a estratégia foi escolhida: os modelos que usam a estratégia padrão recorrem silenciosamente à estratégia legado; os modelos que definem explicitamente delete+insert ou microbatch falham em tempo de execução; e use_lw_deletes: true no perfil falha no momento da conexão.
  • Em casos muito raros, o uso de incremental_predicates não determinísticos pode resultar em uma condição de corrida nos itens atualizados/excluídos. Para garantir resultados consistentes, os predicados incrementais devem incluir apenas subconsultas sobre dados que não serão modificados durante a materialização incremental.

A estratégia microbatch (requer dbt-core >= 1.9)

A estratégia incremental microbatch é um recurso do dbt-core desde a versão 1.9, projetado para lidar com transformações de grandes volumes de dados de séries temporais com eficiência. No dbt-clickhouse, ela se baseia na estratégia incremental delete_insert já existente, dividindo o processamento incremental em lotes predefinidos de séries temporais com base nas configurações do modelo event_time e batch_size. Além de lidar com grandes transformações, o microbatch oferece a capacidade de: Para mais detalhes sobre o uso de microbatch, consulte a documentação oficial.
Configurações de Microbatch disponíveis

A estratégia Append

Essa estratégia substitui a configuração inserts_only nas versões anteriores do dbt-clickhouse. Essa abordagem simplesmente adiciona novas linhas à relação existente. Como resultado, linhas duplicadas não são eliminadas, e não há tabela temporária nem intermediária. É a abordagem mais rápida se duplicatas forem permitidas nos dados ou excluídas pela consulta incremental na cláusula WHERE/filtro.

A estratégia insert_overwrite (Experimental)

[IMPORTANT] Atualmente, a estratégia insert_overwrite não é totalmente funcional com materializações distribuídas.
Executa as seguintes etapas:
  1. Cria uma tabela de staging (temporária) com a mesma estrutura da relação do modelo incremental: CREATE TABLE <staging> AS <target>.
  2. Insere apenas novos registros (produzidos por SELECT) na tabela de staging.
  3. Substitui apenas as novas partições (presentes na tabela de staging) na tabela de destino.
Essa abordagem tem as seguintes vantagens:
  • É mais rápida do que a estratégia padrão porque não copia a tabela inteira.
  • É mais segura do que outras estratégias porque não modifica a tabela original até que a operação INSERT seja concluída com sucesso: em caso de falha intermediária, a tabela original não é modificada.
  • Implementa a prática recomendada de engenharia de dados de “imutabilidade de partições”, o que simplifica o processamento de dados incremental e paralelo, rollbacks etc.
A estratégia exige que partition_by seja definido na configuração do modelo. Ela ignora todos os demais parâmetros específicos de estratégia na configuração do modelo.

Materialização: materialized_view

A materialização materialized_view cria uma visão materializada no ClickHouse que atua como um gatilho de inserção, transformando e inserindo automaticamente novas linhas de uma tabela de origem em uma tabela de destino. Esta é uma das materializações mais poderosas disponíveis no dbt-clickhouse. Devido ao nível de detalhamento, esta materialização tem uma página dedicada. Acesse o guia de visões materializadas para consultar a documentação completa

Materialização: dicionário (experimental)

Um modelo dbt pode ser criado como um dicionário do ClickHouse. Em cada dbt run, o dicionário é substituído pela definição atual do modelo usando CREATE OR REPLACE DICTIONARY.

Configurações

Exemplo com uma fonte do ClickHouse

O SQL do modelo se torna a consulta da fonte do dicionário:

Exemplo com uma fonte HTTP

Ao usar source_type='http' (ou a opção table), o SQL do modelo não é usado como fonte, mas o dbt ainda exige um corpo — use select 1 como placeholder:
Consulte os testes de dicionário para mais exemplos, incluindo dicionários range e direct.

Materialização: distributed_table (experimental)

A tabela distribuída é criada nas seguintes etapas:
  1. Cria uma view temporária com uma consulta SQL para obter a estrutura correta
  2. Cria tabelas locais vazias com base na view
  3. Cria uma tabela distribuída com base nas tabelas locais.
  4. Os dados são inseridos na tabela distribuída para que sejam distribuídos entre os shards sem duplicação.
Observações:
  • As consultas do dbt-clickhouse agora incluem automaticamente a configuração insert_distributed_sync = 1 para garantir que operações subsequentes de materialização incremental sejam executadas corretamente. Isso pode fazer com que algumas inserções em tabelas distribuídas sejam executadas mais lentamente do que o esperado.

Exemplo de modelo de tabela distribuída

Migrações geradas

Configurações

As configurações específicas para este tipo de materialização estão listadas abaixo:

materialização: distributed_incremental (experimental)

Modelo incremental baseado no mesmo conceito de tabela distribuída; a principal dificuldade é processar corretamente todas as estratégias incrementais.
  1. A estratégia Append simplesmente insere dados na tabela distribuída.
  2. A estratégia Delete+Insert cria uma tabela temporária distribuída para trabalhar com todos os dados em cada shard.
  3. A estratégia padrão (legada) cria tabelas temporárias e intermediárias distribuídas pelo mesmo motivo.
Somente as tabelas de shard são substituídas, porque a tabela distribuída não armazena dados. A tabela distribuída é recarregada apenas quando o modo full_refresh está habilitado ou quando a estrutura da tabela pode ter sido alterada.

Exemplo de modelo incremental distribuído

Migrações geradas

Snapshot

Os snapshots do dbt permitem manter um registro das alterações em um modelo mutável ao longo do tempo. Isso, por sua vez, permite consultas pontuais em modelos, nas quais os analistas podem “voltar no tempo” para ver o estado anterior de um modelo. Essa funcionalidade é compatível com o ClickHouse Connector e é configurada usando a seguinte sintaxe: Bloco de configuração em snapshots/<model_name>.sql:
Para mais informações sobre configuração, consulte a página de referência configurações de snapshot.

Contratos e restrições

Apenas contratos com correspondência exata de tipo de coluna são compatíveis. Por exemplo, um contrato com uma coluna do tipo UInt32 falhará se o modelo retornar um UInt64 ou outro tipo inteiro. O ClickHouse também oferece suporte apenas a restrições CHECK na tabela/modelo como um todo. Chave primária, chave estrangeira, UNIQUE e restrições CHECK em nível de coluna não são compatíveis. (Consulte a documentação do ClickHouse sobre chaves primárias/chave ORDER BY.)
Última modificação em 26 de agosto de 2026