> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/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)

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Beta</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>Recurso beta</span>
        </a>;
};

export const ClickHouseSupportedBadge = () => {
  return <div className="ClickHouseSupportedBadge">
            <div className="ClickHouseSupportedIcon">
                <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                    <path d="M1.30762 1.39073C1.30762 1.3103 1.37465 1.22986 1.46849 1.22986H2.64824C2.72868 1.22986 2.80912 1.29689 2.80912 1.39073V14.4886C2.80912 14.5691 2.74209 14.6495 2.64824 14.6495H1.46849C1.38805 14.6495 1.30762 14.5825 1.30762 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M4.2832 1.39073C4.2832 1.3103 4.35023 1.22986 4.44408 1.22986H5.62383C5.70427 1.22986 5.7847 1.29689 5.7847 1.39073V14.4886C5.7847 14.5691 5.71767 14.6495 5.62383 14.6495H4.44408C4.36364 14.6495 4.2832 14.5825 4.2832 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M7.25977 1.39073C7.25977 1.3103 7.3268 1.22986 7.42064 1.22986H8.60039C8.68083 1.22986 8.76127 1.29689 8.76127 1.39073V14.4886C8.76127 14.5691 8.69423 14.6495 8.60039 14.6495H7.42064C7.3402 14.6495 7.25977 14.5825 7.25977 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M10.2354 1.39073C10.2354 1.3103 10.3024 1.22986 10.3962 1.22986H11.576C11.6564 1.22986 11.7369 1.29689 11.7369 1.39073V14.4886C11.7369 14.5691 11.6698 14.6495 11.576 14.6495H10.3962C10.3158 14.6495 10.2354 14.5825 10.2354 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M13.2256 6.6057C13.2256 6.52526 13.2926 6.44482 13.3865 6.44482H14.5662C14.6466 6.44482 14.7271 6.51186 14.7271 6.6057V9.27354C14.7271 9.35398 14.6601 9.43442 14.5662 9.43442H13.3865C13.306 9.43442 13.2256 9.36739 13.2256 9.27354V6.6057Z" fill="currentColor" />
                </svg>
            </div>
            Suportado pelo ClickHouse
        </div>;
};

<ClickHouseSupportedBadge />

<BetaBadge link="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.
</Warning>

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

<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.
</Note>

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

<h4 id="request-access">
  Experimente o ClickHouse na plataforma dbt
</h4>

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.

<h2 id="terminology">
  Terminologia e disponibilidade
</h2>

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

<h2 id="beta-status">
  Status Beta
</h2>

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.

<h3 id="out-of-scope">
  Fora do escopo do Beta
</h3>

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.

<h2 id="parity">
  Paridade entre v1 e v2
</h2>

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

<Badge color="green">compatível</Badge> já funciona · <Badge color="yellow">parcial</Badge> funciona com limitações · <Badge color="red">ainda não</Badge> implementação pendente.

### Materializations

| Feature | O que faz | dbt v2 | Notas |
| - | - | - | - |
| `view` | View padrão do dbt. | <Badge color="green">Compatível</Badge> | |
| `table` | Reconstrução completa com opções de motor e DDL. | <Badge color="green">Compatível</Badge> | |
| `incremental` | Adiciona ou mescla novas linhas. | <Badge color="green">Compatível</Badge> | |
| `materialized_view` | MV do ClickHouse que transforma os dados no momento da inserção. | <Badge color="green">Compatível</Badge> | |
| `dictionary` | Dicionário do ClickHouse para lookups por chave e junções. | <Badge color="green">Compatível</Badge> | |
| `snapshot` | Dimensões de mudança lenta do tipo 2. | <Badge color="green">Compatível</Badge> | |
| `seed` | Carrega CSVs como tabelas. | <Badge color="green">Compatível</Badge> | 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. | <Badge color="green">Compatível</Badge> | |
| `distributed_table`, `distributed_incremental` | Tabelas divididas em shards por trás de um motor Distributed. | <Badge color="red">Ainda não</Badge> | |

### Configuração de models

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

### Testes e documentação

| Recurso | O que faz | dbt v2 | Observações |
| - | - | - | - |
| Testes de dados | Testes genéricos e singulares. | <Badge color="green">Compatível</Badge> | |
| Testes unitários | Valida a lógica do model com entradas de fixtures. | <Badge color="green">Compatível</Badge> | |
| Persistência da documentação | Descrições gravadas como comentários do ClickHouse. | <Badge color="yellow">Parcial</Badge> | Descrições que contêm `;` falham. |
| Geração de catálogo e documentação | Metadados de colunas para o site de documentação. | <Badge color="green">Compatível</Badge> | |
| Linhagem em nível de coluna | Rastreia colunas ao longo do DAG. | <Badge color="yellow">Parcial</Badge> | 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. | <Badge color="green">Compatível</Badge> | |
| Consistência entre múltiplas réplicas | `select_sequential_consistency` e configurações relacionadas de leitura após escrita. | <Badge color="green">Compatível</Badge> | |
| `ON CLUSTER` e motores replicados | Propagação de DDL em clusters autogerenciados. | <Badge color="red">Ainda não</Badge> | 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. | <Badge color="green">Compatível</Badge> | |
| Configurações personalizadas de conexão | `custom_settings` no nível do profile. | <Badge color="green">Compatível</Badge> | |
| Versão do servidor ClickHouse | Versão mínima do servidor. | <Badge color="green">Compatível</Badge> | 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. | <Badge color="green">Compatível</Badge> | |
| Macros entre bancos de dados | Helpers como os do `dbt-utils`. | <Badge color="green">Compatível</Badge> | |
| Grants | Instruções `GRANT` definidas na configuração do model. | <Badge color="red">Ainda não</Badge> | |
| `dbt clone` | `CLONE AS` zero-copy entre ambientes. | <Badge color="red">Ainda não</Badge> | |
| Query ID nos resultados da execução | `query_id` em `adapter_response` para correlação com `system.query_log`. | <Badge color="red">Ainda não</Badge> | |
| `query-comment` | Configuração do comentário da consulta. | <Badge color="red">Ainda não</Badge> | `query-comment: null` ainda não é respeitado. |
| Integração com catalog (Iceberg) | Materializar em external catalogs. | <Badge color="red">Ainda não</Badge> | 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. | <Badge color="green">Compatível</Badge> | ADBC (Arrow sobre HTTP) na v2; HTTP e native na v1. |
| Nome de usuário e senha, TLS | Autenticação padrão. | <Badge color="green">Compatível</Badge> | |
| Certificados de cliente mTLS | `client_cert`, `client_cert_key`, `verify`. | <Badge color="red">Ainda não</Badge> | 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`. | <Badge color="red">Ainda não</Badge> | Aceitas, mas ignoradas; `server_host_name` está indisponível. |