> ## 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.
> Você pode transformar e modelar seus dados no ClickHouse usando dbt
# Integração entre dbt e ClickHouse
export const ClickHouseSupportedBadge = () => {
return
Suportado pelo ClickHouse
;
};
## O adaptador dbt-clickhouse
**dbt** (data build tool) permite que engenheiros de analytics transformem dados em seus warehouses simplesmente escrevendo instruções select. O dbt cuida de materializar essas instruções select em objetos no banco de dados, na forma de tabelas e views, realizando o T de [Extrair, Carregar e Transformar (ELT)](https://en.wikipedia.org/wiki/Extract,_load,_transform). Você pode criar um modelo definido por uma instrução SELECT.
No dbt, esses modelos podem ser referenciados entre si e organizados em camadas, permitindo a construção de conceitos de nível mais alto. O SQL boilerplate necessário para conectar os modelos é gerado automaticamente. Além disso, o dbt identifica as dependências entre os modelos e garante que eles sejam criados na ordem adequada usando um grafo acíclico direcionado (DAG).
O dbt é compatível com o ClickHouse por meio de um [adaptador com suporte a ClickHouse](https://github.com/ClickHouse/dbt-clickhouse).
## Páginas relacionadas
| Página | Descrição |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [Funcionalidades e configurações](/docs/pt-BR/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations) | Descrição das funcionalidades e configurações gerais disponíveis |
| [Materializações](/docs/pt-BR/integrations/connectors/data-ingestion/etl-tools/dbt/materializations) | Materializações disponíveis e suas configurações |
| [Visões materializadas](/docs/pt-BR/integrations/connectors/data-ingestion/etl-tools/dbt/materialization-materialized-view) | Documentação específica da materialização materialized\_view |
| [Guias](/docs/pt-BR/integrations/connectors/data-ingestion/etl-tools/dbt/guides) | Guias para usar o dbt com ClickHouse |
## Recursos suportados
Lista de recursos suportados:
* [x] Materialização de tabela
* [x] Materialização de view
* [x] Materialização incremental
* [x] Materialização incremental do tipo Microbatch
* [x] Materializações de visão materializada (usa a forma `TO` de MATERIALIZED VIEW, experimental)
* [x] Seeds
* [x] Sources
* [x] Geração de documentação
* [x] Testes
* [x] Snapshots
* [x] A maioria das macros do dbt-utils (agora incluídas no dbt-core)
* [x] Materialização efêmera
* [x] Materialização de tabela distribuída (experimental)
* [x] Materialização incremental distribuída (experimental)
* [x] Contratos
* [x] Configurações de coluna específicas do ClickHouse (Codec, TTL...)
* [x] Configurações de tabela específicas do ClickHouse (índices, projeções...)
Todos os recursos até o dbt-core 1.10 têm suporte, incluindo a flag `--sample`, e todos os avisos de descontinuação já foram corrigidos para versões futuras. **Integrações de catálogo** (por exemplo, Iceberg), introduzidas no dbt 1.10, ainda não têm suporte nativo no adaptador, mas há soluções alternativas disponíveis. Consulte a [seção Suporte a catálogo](/docs/pt-BR/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations#catalog-support) para mais detalhes.
Este adaptador ainda não está disponível para uso no [dbt Cloud](https://docs.getdbt.com/docs/dbt-cloud/cloud-overview), mas esperamos disponibilizá-lo em breve. Entre em contato com o suporte para obter mais informações.
## conceitos do dbt e materializações compatíveis
O dbt introduz o conceito de modelo. Ele é definido como uma instrução SQL, potencialmente combinando muitas tabelas. Um modelo pode ser "materializado" de várias maneiras. Uma materialização representa uma estratégia de build para a consulta `select` do modelo. O código por trás de uma materialização é um SQL boilerplate que envolve sua consulta SELECT em uma instrução para criar uma nova relação ou atualizar uma relação existente.
O dbt fornece 5 tipos de materialização. Todos eles são compatíveis com `dbt-clickhouse`:
* **view** (padrão): O modelo é construído como uma view no banco de dados. No ClickHouse, isso é criado como uma [view](/docs/pt-BR/reference/statements/create/view).
* **table**: O modelo é construído como uma tabela no banco de dados. No ClickHouse, isso é criado como uma [table](/docs/pt-BR/reference/statements/create/table).
* **ephemeral**: O modelo não é construído diretamente no banco de dados, mas é incorporado aos modelos dependentes como CTEs (expressões de tabela comuns).
* **incremental**: O modelo é inicialmente materializado como uma tabela e, em execuções subsequentes, o dbt insere novas linhas e atualiza as linhas alteradas na tabela.
* **materialized view**: O modelo é construído como uma visão materializada no banco de dados. No ClickHouse, isso é criado como uma [materialized view](/docs/pt-BR/reference/statements/create/view#materialized-view).
Sintaxe e cláusulas adicionais definem como esses modelos devem ser atualizados se os dados subjacentes mudarem. Em geral, o dbt recomenda começar com a materialização view até que o desempenho se torne uma preocupação. A materialização table oferece melhora de desempenho em query time ao capturar os resultados da consulta do modelo como uma tabela, em troca de maior uso de armazenamento. A abordagem incremental vai além disso e permite que atualizações subsequentes nos dados subjacentes sejam capturadas na tabela de destino.
O [adaptador atual](https://github.com/silentsokolov/dbt-clickhouse) para ClickHouse também oferece suporte às materializações **Dicionário**, **distributed table** e **distributed incremental**. O adaptador também oferece suporte a [snapshots](https://docs.getdbt.com/docs/building-a-dbt-project/snapshots#check-strategy) e [seeds](https://docs.getdbt.com/docs/building-a-dbt-project/seeds) do dbt.
Os itens a seguir são [recursos experimentais](/docs/pt-BR/reference/settings/beta-and-experimental-features) no `dbt-clickhouse`:
| Tipo | Compatível? | Detalhes |
| -------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Materialização de visão materializada | Sim. A criação com destino explícito está em Beta | Cria uma [materialized view](/docs/pt-BR/reference/statements/create/view#materialized-view). |
| Materialização de tabela distribuída | Sim, Experimental | Cria uma [tabela distribuída](/docs/pt-BR/reference/engines/table-engines/special/distributed). |
| Materialização incremental distribuída | Sim, Experimental | Modelo incremental baseado na mesma ideia da tabela distribuída. Observe que nem todas as estratégias são compatíveis; visite [a seção da documentação](/docs/pt-BR/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#materialization-distributed-incremental) para mais informações. |
| Materialização de Dicionário | Sim, Experimental | Cria um [dicionário](/docs/pt-BR/reference/engines/table-engines/special/dictionary). |
## Configuração do dbt e do adaptador do ClickHouse
### Instale o dbt-core e o dbt-clickhouse
O dbt oferece várias opções para instalar a interface de linha de comando (CLI), detalhadas [aqui](https://docs.getdbt.com/dbt-cli/install/overview). Recomendamos usar o `pip` para instalar tanto o dbt quanto o dbt-clickhouse.
```sh theme={null}
pip install dbt-core dbt-clickhouse
```
### Forneça ao dbt os detalhes da conexão da nossa instância do ClickHouse.
Configure o perfil `clickhouse-service` no arquivo `~/.dbt/profiles.yml` e informe as propriedades `schema`, `host`, `port`, `user` e `password`. A lista completa de opções de configuração da conexão está disponível na página [Recursos e configurações](/docs/pt-BR/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations):
```yaml theme={null}
clickhouse-service:
target: dev
outputs:
dev:
type: clickhouse
schema: [ default ] # Banco de dados ClickHouse para modelos dbt
# Opcional
host: [ localhost ]
port: [ 8123 ] # Padrão: 8123, 8443, 9000, 9440 dependendo das configurações de secure e driver
user: [ default ] # Usuário para todas as operações no banco de dados
password: [ ] # Senha do usuário
secure: True # Usar TLS (protocolo nativo) ou HTTPS (protocolo HTTP)
```
### Criar um projeto dbt
Agora você pode usar este perfil em um dos seus projetos existentes ou criar um novo usando:
```sh theme={null}
dbt init project_name
```
Dentro do diretório `project_name`, atualize o arquivo `dbt_project.yml` para especificar um nome de perfil para se conectar ao servidor ClickHouse.
```yaml theme={null}
profile: 'clickhouse-service'
```
### Testar a conexão
Execute `dbt debug` na CLI para confirmar se o dbt consegue se conectar ao ClickHouse. Verifique se a resposta inclui `Connection test: [OK connection ok]`, indicando que a conexão foi bem-sucedida.
Acesse a [página de guias](/docs/pt-BR/integrations/connectors/data-ingestion/etl-tools/dbt/guides) para saber mais sobre como usar o dbt com o ClickHouse.
### Testando e implantando seus modelos (CI/CD)
Há muitas maneiras de testar e implantar seu projeto dbt. O dbt traz algumas sugestões de [fluxos de trabalho com boas práticas](https://docs.getdbt.com/best-practices/best-practice-workflows#pro-tips-for-workflows) e [jobs de CI](https://docs.getdbt.com/docs/deploy/ci-jobs). Vamos abordar várias estratégias, mas tenha em mente que elas podem precisar de ajustes significativos para se adequar ao seu caso de uso específico.
#### CI/CD com testes de dados simples e testes unitários
Uma forma simples de dar início ao seu pipeline de CI é executar um cluster do ClickHouse no seu job e, em seguida, executar seus modelos nele. Você pode inserir dados de exemplo nesse cluster antes de executar seus modelos. Também pode usar um [seed](https://docs.getdbt.com/reference/commands/seed) para preencher o ambiente de staging com um subconjunto dos seus dados de produção.
Depois que os dados forem inseridos, você poderá executar seus [testes de dados](https://docs.getdbt.com/docs/build/data-tests) e seus [testes unitários](https://docs.getdbt.com/docs/build/unit-tests).
Sua etapa de CD pode ser tão simples quanto executar `dbt build` no seu cluster de produção do ClickHouse.
#### Estágio de CI/CD mais completo: use dados recentes e teste apenas os modelos afetados
Uma estratégia comum é usar jobs de [Slim CI](https://docs.getdbt.com/best-practices/best-practice-workflows#run-only-modified-models-to-test-changes-slim-ci), em que apenas os modelos modificados (e suas dependências upstream e downstream) são implantados novamente. Essa abordagem usa artefatos das suas execuções em produção (ou seja, o [manifest do dbt](https://docs.getdbt.com/reference/artifacts/manifest-json)) para reduzir o tempo de execução do seu projeto e garantir que não haja divergência de schema entre ambientes.
Para manter seus ambientes de desenvolvimento em sincronia e evitar executar seus modelos em implantações desatualizadas, você pode usar [clone](https://docs.getdbt.com/reference/commands/clone) ou até mesmo [defer](https://docs.getdbt.com/reference/node-selection/defer).
Recomendamos usar um cluster ou serviço ClickHouse dedicado para o ambiente de teste (ou seja, um ambiente de staging) para evitar impactar a operação do seu ambiente de produção. Para garantir que o ambiente de teste seja representativo, é importante usar um subconjunto dos seus dados de produção, além de executar o dbt de forma a evitar divergência de schema entre ambientes.
* Se você não precisa de dados recentes para testar, pode restaurar um backup dos seus dados de produção no ambiente de staging.
* Se você precisa de dados recentes para testar, pode usar uma combinação da [table function `remoteSecure()`](/docs/pt-BR/reference/functions/table-functions/remote) com views materializadas atualizáveis para inserir dados na frequência desejada. Outra opção é usar armazenamento de objetos como intermediário e gravar dados periodicamente a partir do seu serviço de produção, depois importá-los para o ambiente de staging usando table functions de armazenamento de objetos ou ClickPipes (para ingestão contínua).
Usar um ambiente dedicado para testes de CI também permite realizar testes manuais sem impactar seu ambiente de produção. Por exemplo, você pode querer apontar uma ferramenta de BI para esse ambiente para testes.
Para a implantação (ou seja, a etapa de CD), recomendamos usar os artefatos das suas implantações em produção para atualizar apenas os modelos que mudaram. Isso exige configurar armazenamento de objetos (por exemplo, S3) como armazenamento intermediário para seus artefatos do dbt. Depois que isso estiver configurado, você pode executar um comando como `dbt build --select state:modified+ --state path/to/last/deploy/state.json` para reconstruir seletivamente o menor conjunto de modelos necessário com base no que mudou desde a última execução em produção.
## Solução de problemas comuns
### Conexões
Se você tiver problemas para se conectar ao ClickHouse pelo dbt, verifique se os seguintes critérios foram atendidos:
* O motor deve ser um dos [motores compatíveis](/docs/pt-BR/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#supported-table-engines).
* Você deve ter permissões adequadas para acessar o banco de dados.
* Se você não estiver usando o motor de tabela padrão do banco de dados, deverá especificar um motor de tabela na configuração do seu modelo.
### Entendendo operações de longa duração
Algumas operações podem levar mais tempo do que o esperado devido a consultas específicas do ClickHouse. Para ter mais visibilidade sobre quais consultas estão demorando mais, aumente o [nível de log](https://docs.getdbt.com/reference/global-configs/logs#log-level) para `debug` — isso exibirá o tempo gasto por cada consulta. Por exemplo, isso pode ser feito acrescentando `--log-level debug` aos comandos do dbt.
## Limitações
O adaptador atual do ClickHouse para dbt tem várias limitações das quais você deve estar ciente:
* O plugin usa uma sintaxe que exige o ClickHouse versão 25.3 ou mais recente. Não testamos versões mais antigas do ClickHouse. No momento, também não testamos tabelas Replicated.
* Diferentes execuções do `dbt-adapter` podem entrar em conflito se forem executadas ao mesmo tempo, pois internamente podem usar os mesmos nomes de tabela para as mesmas operações. Para mais informações, consulte a issue [#420](https://github.com/ClickHouse/dbt-clickhouse/issues/420).
* Atualmente, o adaptador materializa modelos como tabelas usando um [INSERT INTO SELECT](/docs/pt-BR/reference/statements/insert-into#inserting-the-results-of-select). Na prática, isso significa duplicação de dados se a execução ocorrer novamente. Datasets muito grandes (PB) podem resultar em tempos de execução extremamente longos, tornando alguns modelos inviáveis. Para melhorar o desempenho, use visões materializadas do ClickHouse implementando a view como `materialized: materialization_view`. Além disso, procure minimizar o número de linhas retornadas por qualquer consulta usando `GROUP BY` sempre que possível. Prefira modelos que resumam os dados em vez daqueles que apenas os transformam mantendo a mesma contagem de linhas da origem.
* Para usar tabelas Distributed para representar um modelo, você deve criar manualmente as tabelas replicadas subjacentes em cada nó. A tabela Distributed, por sua vez, pode ser criada sobre elas. O adaptador não gerencia a criação do cluster.
* Quando o dbt cria uma relação (tabela/view) em um banco de dados, ele normalmente a cria como: `{{ database }}.{{ schema }}.{{ table/view id }}`. O ClickHouse não tem o conceito de schemas. Portanto, o adaptador usa `{{schema}}.{{ table/view id }}`, em que `schema` é o banco de dados do ClickHouse.
* Modelos/CTEs efêmeros não funcionam se forem colocados antes do `INSERT INTO` em uma instrução de insert do ClickHouse; veja [https://github.com/ClickHouse/ClickHouse/issues/30323](https://github.com/ClickHouse/ClickHouse/issues/30323). Isso não deve afetar a maioria dos modelos, mas é preciso ter cuidado com onde um modelo efêmero é colocado nas definições de modelo e em outras instruções SQL. {/* TODO review this limitation, looks like the issue was already closed and the fix was introduced in 24.10 */}
## Fivetran
O conector `dbt-clickhouse` também está disponível para uso em [transformações do Fivetran](https://fivetran.com/docs/transformations/dbt), permitindo integração e transformação de forma fluida diretamente na plataforma Fivetran com `dbt`.