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:
Observação: Em tabelas distribuídas, a projeção é aplicada às tabelas _local, não à tabela proxy distribuída.

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

O ClickHouse adicionou “exclusões leves” como um recurso experimental na versão 22.8. As exclusões leves são significativamente mais rápidas do que as operações ALTER TABLE … DELETE, porque não exigem a regravação das partes de dados do ClickHouse. A estratégia incremental delete+insert utiliza exclusões leves para implementar materializações incrementais com desempenho significativamente superior ao da estratégia “legada”. No entanto, há ressalvas importantes ao usar essa estratégia:
  • As exclusões leves devem estar habilitadas no seu servidor ClickHouse usando a configuração allow_experimental_lightweight_delete=1 ou você deve definir use_lw_deletes=true no seu perfil (o que habilitará essa configuração para suas sessões do dbt)
  • As exclusões leves agora estão prontas para produção, mas ainda pode haver problemas de desempenho e outros problemas em versões do ClickHouse anteriores à versão 23.3.
  • Essa estratégia opera diretamente na tabela/relação afetada (sem criar tabelas intermediárias ou temporárias), portanto, se ocorrer algum problema durante a operação, é provável que os dados no modelo incremental fiquem em um estado inválido
  • Ao usar exclusões leves, o dbt-clickhouse habilita a configuração allow_nondeterministic_mutations. Em alguns casos muito raros, o uso de incremental_predicates não determinísticos pode resultar em uma condição de corrida para os itens atualizados/excluídos (e mensagens de log relacionadas nos logs do ClickHouse). 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)

Consulte os testes em https://github.com/ClickHouse/dbt-clickhouse/blob/main/tests/integration/adapter/dictionary/test&#95;dictionary.py para ver exemplos de como implementar materializações para dicionários no ClickHouse

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 24 de julho de 2026