> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > Materializações disponíveis e suas configurações # Materializações export const ClickHouseSupportedBadge = () => { return
Suportado pelo ClickHouse
; }; 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](https://docs.getdbt.com/category/general-configs): | Option | Description | Default if any | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | engine | O motor de tabela (tipo de tabela) a ser usado ao criar tabelas | `MergeTree()` | | order\_by | Uma tupla de nomes de colunas ou expressões arbitrárias. Isso permite criar um pequeno índice esparso que ajuda a localizar dados mais rapidamente. | `tuple()` | | partition\_by | Uma partição é uma combinação lógica de registros em uma tabela com base em um critério especificado. A chave de partição pode ser qualquer expressão das colunas da tabela. | | | primary\_key | Assim como em `order_by`, uma expressão de chave primária do ClickHouse. Se não for especificada, o ClickHouse usará a expressão de ordenação como chave primária | | | settings | Um mapa/dicionário de configurações de "TABLE" para uso em instruções DDL, como `CREATE TABLE`, com este modelo | | | query\_settings | Um mapa/dicionário de configurações em nível de usuário do ClickHouse para uso com instruções `INSERT` ou `DELETE` em conjunto com este modelo | | | ttl | Uma expressão TTL a ser usada com a tabela. A expressão TTL é uma string que pode ser usada para especificar o TTL da tabela. | | | sql\_security | O usuário do ClickHouse a ser usado ao executar a consulta subjacente da view. [Valores aceitos](/docs/pt-BR/reference/statements/create/view#sql_security): `definer`, `invoker`. | | | definer | Se `sql_security` tiver sido definido como `definer`, você deverá especificar qualquer usuário existente ou `CURRENT_USER` na cláusula `definer`. | |
### Motores de tabela compatíveis
| Tipo | Detalhes | | ---------------------- | ------------------------------------------------------------------------------------------- | | MergeTree (padrão) | [documentação](/docs/pt-BR/reference/engines/table-engines/mergetree-family/mergetree). | | HDFS | [documentação](/docs/pt-BR/reference/engines/table-engines/integrations/hdfs) | | MaterializedPostgreSQL | [documentação](/docs/pt-BR/reference/engines/table-engines/integrations/materialized-postgresql) | | S3 | [documentação](/docs/pt-BR/reference/engines/table-engines/integrations/s3) | | EmbeddedRocksDB | [documentação](/docs/pt-BR/reference/engines/table-engines/integrations/embedded-rocksdb) | | Hive | [documentação](/docs/pt-BR/reference/engines/table-engines/integrations/hive) | **Observação**: para visões materializadas, todos os motores da família \*MergeTree são compatíveis.
#### Motores de tabela com suporte experimental
| Tipo | Detalhes | | ------------------ | --------------------------------------------------------------------------- | | Tabela distribuída | [documentação](/docs/pt-BR/reference/engines/table-engines/special/distributed). | | Dicionário | [documentação](/docs/pt-BR/reference/engines/table-engines/special/dictionary) | Se você encontrar problemas para se conectar ao ClickHouse no dbt com um dos motores acima, abra uma issue [aqui](https://github.com/ClickHouse/dbt-clickhouse/issues).
### 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](https://docs.getdbt.com/docs/collaborate/govern/model-contracts) estejam habilitados. | Opção | Descrição | Padrão, se houver | | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | codec | Uma string com os argumentos passados para `CODEC()` na DDL da coluna. Por exemplo: `codec: "Delta, ZSTD"` será compilado como `CODEC(Delta, ZSTD)`. | | | ttl | Uma string com uma [expressão de TTL (time-to-live)](/docs/pt-BR/concepts/features/operations/delete/ttl) que define uma regra de TTL na DDL da coluna. Por exemplo: `ttl: ts + INTERVAL 1 DAY` será compilado como `TTL ts + INTERVAL 1 DAY`. | |
#### Exemplo de configuração de esquema
```yaml theme={null} models: - name: table_column_configs description: 'Testing column-level configurations' config: contract: enforced: true columns: - name: ts data_type: timestamp codec: ZSTD - name: x data_type: UInt8 ttl: ts + INTERVAL 1 DAY ```
#### 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: ```sql theme={null} {{ config( materialized="materialized_view", engine="AggregatingMergeTree", order_by=["event_type"], ) }} select -- event_type pode ser inferido como String, mas podemos preferir LowCardinality(String): CAST(event_type, 'LowCardinality(String)') as event_type, -- countState() pode ser inferido como `AggregateFunction(count)`, mas podemos preferir alterar o tipo do argumento utilizado: CAST(countState(), 'AggregateFunction(count, UInt32)') as response_count, -- maxSimpleState() pode ser inferido como `SimpleAggregateFunction(max, String)`, mas podemos preferir também alterar o tipo do argumento utilizado: CAST(maxSimpleState(event_type), 'SimpleAggregateFunction(max, LowCardinality(String))') as max_event_type from {{ ref('user_events') }} group by event_type ```
## Materialização: view
Um modelo do dbt pode ser criado como uma [view no ClickHouse](/docs/pt-BR/reference/functions/table-functions/view) e configurado com a seguinte sintaxe: Arquivo do projeto (`dbt_project.yml`): ```yaml theme={null} models: : +materialized: view ``` Ou bloco de configuração (`models/.sql`): ```python theme={null} {{ config(materialized = "view") }} ```
## Materialização: tabela
Um modelo do dbt pode ser criado como uma [tabela no ClickHouse](/docs/pt-BR/reference/system-tables/tables) e configurado com a seguinte sintaxe: Arquivo do projeto (`dbt_project.yml`): ```yaml theme={null} models: : +materialized: table +order_by: [ , ... ] +engine: +partition_by: [ , ... ] ``` Ou no bloco de configuração (`models/.sql`): ```python theme={null} {{ config( materialized = "table", engine = "", order_by = [ "", ... ], partition_by = [ "", ... ], ... ] ) }} ```
### Data skipping indexes
Você pode adicionar [data skipping indexes](/docs/pt-BR/concepts/features/performance/skip-indexes/skipping-indexes) às materializações `table` usando a configuração `indexes`: ```sql theme={null} {{ config( materialized='table', indexes=[{ 'name': 'your_index_name', 'definition': 'your_column TYPE minmax GRANULARITY 2' }] ) }} ```
### Projeções
Você pode adicionar [projeções](/docs/pt-BR/concepts/features/projections/projections) às materializações `table` e `distributed_table` por meio da configuração `projections`: ```sql theme={null} {{ config( materialized='table', projections=[ { 'name': 'your_projection_name', 'query': 'SELECT department, avg(age) AS avg_age GROUP BY department' } ] ) }} ``` **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`: ```yaml theme={null} models: : +materialized: incremental +order_by: [ , ... ] +engine: +partition_by: [ , ... ] +unique_key: [ , ... ] +inserts_only: [ True|False ] ``` Ou o bloco de configuração em `models/.sql`: ```python theme={null} {{ config( materialized = "incremental", engine = "", order_by = [ "", ... ], partition_by = [ "", ... ], unique_key = [ "", ... ], inserts_only = [ True|False ], ... ] ) }} ```
### Configurações
As configurações específicas deste tipo de materialização estão listadas abaixo: | Option | Description | Required? | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `unique_key` | Uma tupla de nomes de colunas que identificam exclusivamente as linhas. Para mais detalhes sobre restrições de unicidade, veja [aqui](https://docs.getdbt.com/docs/build/incremental-models#defining-a-unique-key-optional). | Obrigatório. Se não for fornecido, linhas alteradas serão adicionadas duas vezes à tabela incremental. | | `inserts_only` | Foi descontinuado em favor da `strategy` incremental `append`, que funciona da mesma forma. Se definido como True para um modelo incremental, as atualizações incrementais serão inseridas diretamente na tabela de destino sem criar uma tabela intermediária. Se `inserts_only` for definido, `incremental_strategy` será ignorado. | Opcional (padrão: `False`) | | `incremental_strategy` | A estratégia a ser usada para a materialização incremental. `delete+insert`, `append`, `insert_overwrite` ou `microbatch` são compatíveis. Para mais detalhes sobre as estratégias, veja [aqui](#incremental-model-strategies) | Opcional (padrão: 'default') | | `incremental_predicates` | Condições adicionais a serem aplicadas à materialização incremental (aplicadas apenas à estratégia `delete+insert` | Opcional |
### 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: * [Reprocessar lotes com falha](https://docs.getdbt.com/docs/build/incremental-microbatch#retry). * Detectar automaticamente a [execução paralela de lotes](https://docs.getdbt.com/docs/build/parallel-batch-execution). * Eliminar a necessidade de lógica condicional complexa em [cargas retroativas](https://docs.getdbt.com/docs/build/incremental-microbatch#backfills). Para mais detalhes sobre o uso de microbatch, consulte a [documentação oficial](https://docs.getdbt.com/docs/build/incremental-microbatch).
##### Configurações de Microbatch disponíveis
| Opção | Descrição | Padrão, se houver | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | event\_time | A coluna que indica "em que momento a linha ocorreu". Obrigatória para seu modelo de microbatch e quaisquer modelos pai diretos que devam ser filtrados. | | | begin | O "início dos tempos" do modelo de microbatch. Este é o ponto de partida para quaisquer compilações iniciais ou atualizações completas. Por exemplo, um modelo de microbatch com granularidade diária executado em 2024-10-01 com begin = '2023-10-01 processará 366 batches (é um ano bissexto!) mais o batch de "hoje". | | | batch\_size | A granularidade dos seus batches. Os valores compatíveis são `hour`, `day`, `month` e `year` | | | lookback | Processa X batches antes do marcador mais recente para capturar registros que chegam com atraso. | 1 | | concurrent\_batches | Substitui a detecção automática do dbt para executar batches de forma concorrente (ao mesmo tempo). Leia mais sobre [como configurar batches concorrentes](https://docs.getdbt.com/docs/build/incremental-microbatch#configure-concurrent_batches). Definir como true executa os batches de forma concorrente (em paralelo). false executa os batches de forma sequencial (um após o outro). | |
#### 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 AS `. 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](/docs/pt-BR/reference/statements/create/view#materialized-view) 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](/docs/pt-BR/integrations/connectors/data-ingestion/etl-tools/dbt/materialization-materialized-view)** 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\_dictionary.py](https://github.com/ClickHouse/dbt-clickhouse/blob/main/tests/integration/adapter/dictionary/test\_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
```sql theme={null} {{ config( materialized='distributed_table', order_by='id, created_at', sharding_key='cityHash64(id)', engine='ReplacingMergeTree' ) }} select id, created_at, item from {{ source('db', 'table') }} ```
### Migrações geradas
```sql theme={null} CREATE TABLE db.table_local on cluster cluster ( `id` UInt64, `created_at` DateTime, `item` String ) ENGINE = ReplacingMergeTree ORDER BY (id, created_at); CREATE TABLE db.table on cluster cluster ( `id` UInt64, `created_at` DateTime, `item` String ) ENGINE = Distributed ('cluster', 'db', 'table_local', cityHash64(id)); ```
### Configurações
As configurações específicas para este tipo de materialização estão listadas abaixo: | Opção | Descrição | Padrão, se houver | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | sharding\_key | A chave de sharding determina o servidor de destino ao inserir em uma tabela com mecanismo Distributed. A chave de sharding pode ser aleatória ou ser a saída de uma função hash | `rand()`) |
## 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
```sql theme={null} {{ config( materialized='distributed_incremental', engine='MergeTree', incremental_strategy='append', unique_key='id,created_at' ) }} select id, created_at, item from {{ source('db', 'table') }} ```
### Migrações geradas
```sql theme={null} CREATE TABLE db.table_local on cluster cluster ( `id` UInt64, `created_at` DateTime, `item` String ) ENGINE = MergeTree; CREATE TABLE db.table on cluster cluster ( `id` UInt64, `created_at` DateTime, `item` String ) ENGINE = Distributed ('cluster', 'db', 'table_local', cityHash64(id)); ```
## 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/.sql`: ```python theme={null} {{ config( schema = "", unique_key = "", strategy = "", updated_at = "", ) }} ``` Para mais informações sobre configuração, consulte a página de referência [configurações de snapshot](https://docs.getdbt.com/docs/build/snapshots#snapshot-configs).
## 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`.)