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:
_local, não à tabela proxy distribuída.
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
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=1ou você deve definiruse_lw_deletes=trueno 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)
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)
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.)