> ## 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.

> Status do adaptador ClickHouse no dbt OSS, no dbt v2 e na plataforma dbt

# dbt OSS, v2 e Platform (Beta)

Suportado pelo ClickHouse

[Beta](https://github.com/ClickHouse/dbt-clickhouse/issues/660)

O dbt está sendo reconstruído sobre um novo motor, e o ClickHouse faz parte disso desde o início. O ClickHouse já funciona com o novo motor do dbt escrito em Rust, tanto no dbt OSS quanto no dbt v2 e, pela primeira vez, é possível se conectar ao ClickHouse a partir da plataforma dbt. Seu projeto não muda: os mesmos models, testes e profiles que rodam hoje no dbt Core 1.x rodam no novo motor; apenas o binário é diferente.

O ClickHouse é o primeiro adaptador da comunidade no dbt OSS, no dbt v2 e na plataforma dbt. Os adaptadores próprios do dbt estão sendo lançados junto conosco; somos os primeiros de fora da dbt Labs. O adaptador Python para dbt Core 1.x, `dbt-clickhouse`, não será descontinuado: nós o mantemos atualizado com os lançamentos do dbt 1.x e mantemos ambos os adaptadores em paralelo.

> [!WARNING]
>
> **Não está pronto para produção.** O adaptador ClickHouse para dbt OSS e dbt v2, bem como a conexão com a plataforma dbt, ainda não estão disponíveis de forma geral (GA). Utilize-os apenas em projetos de desenvolvimento ou staging.

> [!NOTE]
>
> **A documentação do dbt Core 1.x também se aplica ao dbt OSS e ao dbt v2.** O adaptador se comporta da mesma forma em ambos os motores: os profiles, configurações de model, materializations e macros descritos nas demais páginas do dbt funcionam sem alterações no dbt OSS, no dbt v2 e na plataforma dbt. As exceções estão documentadas na tabela [paridade entre v1 e v2](#parity) abaixo.

> [!NOTE]
>
> **dbt OSS** é a compilação de código aberto (Apache 2.0) do motor v2. Consulte [terminologia e disponibilidade](#terminology) para entender como ele se relaciona com o dbt v2 e a plataforma dbt.

O status em tempo real é acompanhado em [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660) (paridade da v2 com a v1, com uma sub-issue por área) e [ClickHouse/dbt-clickhouse#555](https://github.com/ClickHouse/dbt-clickhouse/issues/555) (dbt v2).

#### Experimente o ClickHouse na plataforma dbt

Se você tiver interesse em testar o beta privado, inscreva-se pelo [formulário de beta privado da dbt Labs](https://docs.google.com/forms/d/e/1FAIpQLScjHwRchnKarq_RpNM7hATjphNFxqBEePmAwRtSpMWG1snGHA/viewform). O formulário pertence à dbt Labs, portanto as informações enviadas vão para a dbt Labs, e não para a ClickHouse. Depois de habilitado o acesso, siga [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) na documentação do dbt para configurar a conexão.

## Terminologia e disponibilidade

O dbt está disponível em diversas formas, e o mesmo adapter pode ser executado em mais de uma delas. Esta tabela explica cada nome e o nível atual de suporte do ClickHouse.

| Termo | O que é | Status do ClickHouse e como obter |
| - | - | - |
| **dbt Core 1.x** | O motor do dbt baseado em Python, open source (Apache 2.0). Nosso adapter é o `dbt-clickhouse`, mantido na [organização ClickHouse no GitHub](https://github.com/ClickHouse/dbt-clickhouse) e instalado junto com o `dbt-core`. | **GA, mantido.** Continua recebendo lançamentos em paralelo com o dbt v2. |
| **dbt OSS** | Reescrita completa do motor do dbt em Rust, open source (Apache 2.0). Essa nova versão inclui todas as features da v1, além de diversas melhorias de desempenho. | **Beta.** Consulte o [guia de atualização para o dbt v2](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v2) e a [página de configuração do ClickHouse para a v2](https://docs.getdbt.com/docs/local/connect-data-platform/clickhouse-setup?version=2) na documentação do dbt. O adapter do ClickHouse já vem incluído no binary do dbt; não há package separado para instalar. |
| **dbt v2** | dbt OSS mais features adicionais da dbt Labs: compreensão de SQL, análise estática, LSP, uma extensão para o VS Code e reconhecimento de colunas. Closed source, licenciado sob o [dbt Product Licensing Agreement](https://www.getdbt.com/dbt-fusion-engine-license-agreement). | **Beta.** O adapter funciona com o binary da v2, mas as novas features de SQL ainda não estão disponíveis para o ClickHouse. |
| **dbt platform** | dbt hospedado, antigo dbt Cloud: Studio IDE, jobs agendados, ambientes, Catalog, Semantic Layer. A plataforma executa apenas o dbt v2, portanto usar o ClickHouse na plataforma significa usar o adapter da v2. | **Private Beta.** Veja [como solicitar acesso](#request-access). Configuração: [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) na documentação do dbt. |

## Status Beta

Avaliamos o adapter dbt v2 em relação ao test suite de integração do dbt Core 1.x do `dbt-clickhouse`. Beta significa que os workflows principais do dbt e o conjunto de recursos do ClickHouse Cloud funcionam dentro dos limites documentados; a paridade total com a v1 e o suporte a cluster autogerenciado virão depois.

**Hoje,** o adapter passa em mais de 81% do suite completo da v1 e em 92% dos testes que se aplicam ao ClickHouse Cloud. Todas as materializations estão em paridade (`view`, `table`, `incremental`, `materialized_view`, `dictionary`, `snapshot`, `seed`, `ephemeral`), com o conjunto completo de configs de table, contratos de model, testes de dados e unit tests, persistência de documentação, `clickhouse_s3source()` e as settings de connection do dbt Core 1.x. As falhas restantes estão relacionadas ao trabalho de cluster autogerenciado listado abaixo e a algumas diferenças do lado do motor. Consulte [paridade entre v1 e v2](#parity) para o panorama recurso por recurso.

**Próximos passos**: DDL com `ON CLUSTER` e as materializações distribuídas para clusters autogerenciados, grants, `dbt clone`, `dbt source freshness` a partir de metadata de table, correções para os bugs restantes e aprovação no test suite completo da v1 para garantir paridade total. O progresso de tudo isso é acompanhado em [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660), com um sub-issue por área.

GA está no roadmap e chegará em breve. Atualizaremos a documentação assim que estiver pronto.

### Fora do escopo do Beta

Além das lacunas de paridade com a v1 listadas abaixo, alguns recursos exclusivos da v2 estão fora do escopo atual, mas chegarão em breve:

* **Semantic Layer / MetricFlow.** O suporte ao ClickHouse ainda não foi adicionado. Acompanhado em [dbt-labs/metricflow#2124](https://github.com/dbt-labs/metricflow/pull/2124).
* **Inteligência de ClickHouse SQL no dbt v2** (validação com reconhecimento de dialect, análise estática, LSP, reconhecimento de colunas na extensão do VS Code). Atualmente, o adapter é executado com o binary do dbt v2, mas ainda não inclui esses recursos. Até lá, a análise estática é forçada para `off` em projetos ClickHouse e o motor não grava linhagem em nível de coluna. Acompanhado em [#736](https://github.com/ClickHouse/dbt-clickhouse/issues/736).
* **Métodos de autenticação adicionais** além de username e password na plataforma dbt.

## Paridade entre v1 e v2

As tabelas abaixo comparam os recursos disponíveis no `dbt-clickhouse` (v1) com seu status no adapter do dbt v2. Todos os recursos listados são compatíveis na v1, salvo indicação em contrário nas notas; a coluna de status refere-se ao dbt v2 e aplica-se igualmente ao dbt OSS. A evolução de cada item pendente é acompanhada em [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660).

compatível já funciona · parcial funciona com limitações · ainda não implementação pendente.

### Materializations

| Feature | O que faz | dbt v2 | Notas |
| - | - | - | - |
| `view` | View padrão do dbt. | Compatível | |
| `table` | Reconstrução completa com opções de motor e DDL. | Compatível | |
| `incremental` | Adiciona ou mescla novas linhas. | Compatível | |
| `materialized_view` | MV do ClickHouse que transforma os dados no momento da inserção. | Compatível | |
| `dictionary` | Dicionário do ClickHouse para lookups por chave e junções. | Compatível | |
| `snapshot` | Dimensões de mudança lenta do tipo 2. | Compatível | |
| `seed` | Carrega CSVs como tabelas. | Compatível | Tipos de coluna numéricos são inferidos como `Int64`/`Float64` em vez de `Int32`/`Float32`; use `column_types` para defini-los explicitamente. |
| `ephemeral` | CTE inline, sem criação de objeto. | Compatível | |
| `distributed_table`, `distributed_incremental` | Tabelas divididas em shards por trás de um motor Distributed. | Ainda não | |

### Configuração de models

| Feature | O que faz | dbt v2 | Notas |
| - | - | - | - |
| Engine, `ORDER BY`, `PARTITION BY`, `PRIMARY KEY` | Controles essenciais de DDL do MergeTree. | Compatível | |
| TTL | Expiração de linhas e colunas. | Compatível | |
| Settings de tabela e de consulta | `SETTINGS` por model no DDL e no insert. | Compatível | |
| Projeções, índices, `sql_header` | Estruturas secundárias e SQL de prefixo. | Compatível | |
| Contratos e constraints de model | Tipos de coluna e constraints aplicados no momento da compilação. | Compatível | |
| Evolução de schema em models incrementais | `on_schema_change` adiciona ou sincroniza colunas. | Compatível | |
| `codec` e `ttl` de coluna | Compressão e expiração por coluna. | Compatível | |

### Testes e documentação

| Recurso | O que faz | dbt v2 | Observações |
| - | - | - | - |
| Testes de dados | Testes genéricos e singulares. | Compatível | |
| Testes unitários | Valida a lógica do model com entradas de fixtures. | Compatível | |
| Persistência da documentação | Descrições gravadas como comentários do ClickHouse. | Parcial | Descrições que contêm `;` falham. |
| Geração de catálogo e documentação | Metadados de colunas para o site de documentação. | Compatível | |
| Linhagem em nível de coluna | Rastreia colunas ao longo do DAG. | Parcial | Novidade na v2 por meio do compilador SQL, indisponível na v1. A linhagem na plataforma dbt só é renderizada com a delimitação de identificadores desabilitada em `dbt_project.yml`; a linhagem no lado do motor exige o dialect ClickHouse SQL. |

### Cluster e Cloud

| Recurso | O que faz | dbt v2 | Notas |
| - | - | - | - |
| ClickHouse Cloud | Configuração Beta recomendada. | Compatível | |
| Consistência entre múltiplas réplicas | `select_sequential_consistency` e configurações relacionadas de leitura após escrita. | Compatível | |
| `ON CLUSTER` e motores replicados | Propagação de DDL em clusters autogerenciados. | Ainda não | Clusters com múltiplos nós no ClickHouse Cloud são compatíveis. Outras configurações que exigem `ON CLUSTER` para propagação de DDL ainda não são compatíveis. Em implantações autogerenciadas, faça testes apenas em clusters de nó único. |
| `EXCHANGE TABLES` | Troca atômica na reconstrução. | Compatível | |
| Configurações personalizadas de conexão | `custom_settings` no nível do profile. | Compatível | |
| Versão do servidor ClickHouse | Versão mínima do servidor. | Compatível | 25.3+ em ambos os motores. A leitura de colunas `UUID` na v2 exige 26.7+ (servidores mais antigos não conseguem converter `UUID` para Arrow). |

### Macros e operações

| Recurso | O que faz | dbt v2 | Observações |
| - | - | - | - |
| Macro da S3 table function | `clickhouse_s3source()` lê diretamente do S3 em um model. | Compatível | |
| Macros entre bancos de dados | Helpers como os do `dbt-utils`. | Compatível | |
| Grants | Instruções `GRANT` definidas na configuração do model. | Ainda não | |
| `dbt clone` | `CLONE AS` zero-copy entre ambientes. | Ainda não | |
| Query ID nos resultados da execução | `query_id` em `adapter_response` para correlação com `system.query_log`. | Ainda não | |
| `query-comment` | Configuração do comentário da consulta. | Ainda não | `query-comment: null` ainda não é respeitado. |
| Integração com catalog (Iceberg) | Materializar em external catalogs. | Ainda não | Também não havia na v1; alternativas documentadas. |

### Conectividade e autenticação

| Recurso | O que faz | dbt v2 | Notas |
| - | - | - | - |
| Protocolo | Como o dbt se comunica com o ClickHouse. | Compatível | ADBC (Arrow sobre HTTP) na v2; HTTP e native na v1. |
| Nome de usuário e senha, TLS | Autenticação padrão. | Compatível | |
| Certificados de cliente mTLS | `client_cert`, `client_cert_key`, `verify`. | Ainda não | Depende de trabalho no driver; as chaves são aceitas, mas ignoradas. |
| Opções do HTTP client | `connect_timeout`, `send_receive_timeout`, `sync_request_timeout`, `compress_block_size`, `server_host_name`. | Ainda não | Aceitas, mas ignoradas; `server_host_name` está indisponível. |