Configurações gerais de materialização
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
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
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
dbt_project.yml):
models/<model_name>.sql):
Materialização: tabela
dbt_project.yml):
models/<model_name>.sql):
Data skipping indexes
table usando a configuração indexes:
Projeçõ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
query para definir uma consulta completa de projeção:
Projeções de índice
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:
Materialização: incremental
dbt_project.yml:
models/<model_name>.sql:
Configurações
Estratégias de modelos incrementais
dbt-clickhouse oferece suporte a três estratégias de modelos incrementais.
A Estratégia Padrão (Legada)
A estratégia Delete+Insert
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_mutationsdo 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 explicitamentedelete+insertoumicrobatchfalham em tempo de execução; euse_lw_deletes: trueno perfil falha no momento da conexão. - Em casos muito raros, o uso de
incremental_predicatesnã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)
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:
- Reprocessar lotes com falha.
- Detectar automaticamente a execução paralela de lotes.
- Eliminar a necessidade de lógica condicional complexa em cargas retroativas.
Configurações de Microbatch disponíveis
A estratégia Append
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:
- Cria uma tabela de staging (temporária) com a mesma estrutura da relação do modelo incremental:
CREATE TABLE <staging> AS <target>. - Insere apenas novos registros (produzidos por
SELECT) na tabela de staging. - Substitui apenas as novas partições (presentes na tabela de staging) na tabela de destino.
- É 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.
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
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)
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
Exemplo com uma fonte HTTP
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:
Materialização: distributed_table (experimental)
- Cria uma view temporária com uma consulta SQL para obter a estrutura correta
- Cria tabelas locais vazias com base na view
- Cria uma tabela distribuída com base nas tabelas locais.
- Os dados são inseridos na tabela distribuída para que sejam distribuídos entre os shards sem duplicação.
- As consultas do dbt-clickhouse agora incluem automaticamente a configuração
insert_distributed_sync = 1para 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
materialização: distributed_incremental (experimental)
- A estratégia Append simplesmente insere dados na tabela distribuída.
- A estratégia Delete+Insert cria uma tabela temporária distribuída para trabalhar com todos os dados em cada shard.
- A estratégia padrão (legada) cria tabelas temporárias e intermediárias distribuídas pelo mesmo motivo.
Exemplo de modelo incremental distribuído
Migrações geradas
Snapshot
snapshots/<model_name>.sql:
Contratos e 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.)