Configurações do Profile.yml
profiles.yml. Um perfil do ClickHouse segue a sintaxe abaixo:
Schema vs Banco de dados
database.schema.table não é compatível com o ClickHouse porque o ClickHouse não
dá suporte a schema.
Por isso, usamos uma abordagem simplificada, schema.table, em que schema é o banco de dados do ClickHouse. Não é
recomendável usar o banco de dados default.
Aviso sobre a instrução SET
Configurando quote_columns
quote_columns no seu dbt_project.yml. Consulte a documentação sobre quote_columns para mais informações.
Sobre o cluster do ClickHouse
- Definir a configuração
cluster. - Garantir a consistência de leitura após escrita, especialmente se você estiver usando mais de um
threads.
Configuração de cluster
cluster no perfil permite que o dbt-clickhouse seja executado em um cluster ClickHouse. Se cluster estiver definida no perfil, todos os modelos serão criados com a cláusula ON CLUSTER por padrão — exceto os que usam o motor Replicated. Isso inclui:
- Criação de banco de dados
- Materializações de view
- Materializações de tabela e incrementais
- Materializações distribuídas
ON CLUSTER, pois foram projetados para gerenciar a replicação internamente.
Para desativar a criação baseada em cluster para um modelo específico, adicione a config disable_on_cluster:
cluster (o modelo
será criado apenas no nó ao qual você está conectado).
Compatibilidade
Se um modelo tiver sido criado sem a configuração cluster, o dbt-clickhouse detectará essa situação e executará todo o DDL/DML
sem a cláusula on cluster para esse modelo.
Consistência de leitura após escrita
- Se você estiver usando um cluster do ClickHouse Cloud, basta definir
select_sequential_consistency: 1na propriedadecustom_settingsdo seu perfil. Você pode encontrar mais informações sobre essa configuração aqui. - Se você estiver usando um cluster self-hosted, certifique-se de que todas as solicitações do dbt sejam enviadas para a mesma réplica do ClickHouse. Se houver um balanceador de carga na frente dele, tente usar algum mecanismo de
replica aware routing/sticky sessionspara sempre alcançar a mesma réplica. Adicionar a configuraçãoselect_sequential_consistency = 1em clusters fora do ClickHouse Cloud não é recomendado.
Macros adicionais do ClickHouse
Macros utilitárias de materialização de modelos
engine_clause— Usa a propriedade de configuraçãoenginedo modelo para definir um engine de tabela do ClickHouse. O dbt-clickhouse usa o engineMergeTreepor padrão.partition_cols— Usa a propriedade de configuraçãopartition_bydo modelo para definir uma chave de partição do ClickHouse. Nenhuma chave de partição é definida por padrão.order_cols— Usa a configuraçãoorder_bydo modelo para definir uma chave de ordenação/ORDER BY do ClickHouse. Se não for especificada, o ClickHouse usará umatuple()vazia e a tabela não será ordenadaprimary_key_clause— Usa a propriedade de configuraçãoprimary_keydo modelo para definir uma chave primária do ClickHouse. Por padrão, a chave primária é definida, e o ClickHouse usará a cláusula ORDER BY como chave primária.on_cluster_clause— Usa a propriedadeclusterdo perfil para adicionar uma cláusulaON CLUSTERa determinadas operações do dbt: materializações distribuídas, criação de views e criação de banco de dados.ttl_config— Usa a propriedade de configuraçãottldo modelo para definir uma expressão de TTL de tabela do ClickHouse. Nenhum TTL é definido por padrão.
Macro auxiliar s3Source
s3source simplifica o processo de selecionar dados no ClickHouse diretamente do S3 usando a função de tabela S3 do ClickHouse.
Ela funciona
preenchendo os parâmetros da função de tabela S3 a partir de um dicionário de configuração nomeado (o nome do dicionário deve terminar
em s3). A macro
primeiro procura o dicionário nas vars do perfil e, depois, na configuração do modelo. O dicionário pode conter
qualquer uma das seguintes
chaves usadas para preencher os parâmetros da função de tabela S3:
Consulte
o arquivo de teste do S3
para ver exemplos de como usar esta macro.
Suporte a macros entre bancos de dados
dbt Core, com as seguintes exceções:
- A função SQL
split_parté implementada no ClickHouse usando a função splitByChar. Essa função exige o uso de uma string constante como delimitador de divisão, portanto o parâmetrodelimeterusado nessa macro será interpretado como uma string, e não como um nome de coluna - Da mesma forma, a função SQL
replaceno ClickHouse exige strings constantes para os parâmetrosold_charsenew_chars, portanto esses parâmetros serão interpretados como strings, e não como nomes de colunas, ao invocar essa macro.
Suporte a catálogos
Status da integração de catálogo do dbt
Suporte a catálogos no ClickHouse
experimental, mas você já pode usá-los com uma versão recente do ClickHouse.
- Você pode usar o ClickHouse para consultar tabelas Iceberg armazenadas em armazenamento de objetos (S3, Azure Blob Storage, Google Cloud Storage) usando o motor de tabela Iceberg e a função de tabela iceberg.
- Além disso, o ClickHouse oferece o motor de banco de dados DataLakeCatalog, que permite a conexão com catálogos de dados externos, incluindo AWS Glue Catalog, Databricks Unity Catalog, Hive Metastore e REST Catalogs. Isso permite consultar dados em formatos de tabela abertos (Iceberg, Delta Lake) diretamente de catálogos externos, sem duplicação de dados.
Alternativas para trabalhar com Iceberg e catálogos
source do dbt para referenciar essas tabelas nos seus projetos dbt. Por exemplo, se quiser acessar suas tabelas em um REST Catalog, você pode:
- Criar um banco de dados apontando para um catálogo externo:
- Defina o banco de dados do catálogo e suas tabelas como sources no dbt: lembre-se de que as tabelas já devem estar disponíveis no ClickHouse
- Use as tabelas de catálogo em seus modelos dbt:
Observações sobre as soluções alternativas
- Você terá acesso imediato a diferentes tipos de tabelas externas e catálogos externos sem precisar esperar pela integração nativa de catálogos do dbt.
- Você terá um caminho de migração tranquilo quando o suporte nativo a catálogos estiver disponível.
- Configuração manual: tabelas Iceberg e bancos de dados de catálogo precisam ser criados manualmente no ClickHouse antes de poderem ser referenciados no dbt.
- Sem DDL no nível de catálogo: o dbt não consegue gerenciar operações no nível de catálogo, como criar ou excluir tabelas Iceberg em catálogos externos. Portanto, no momento, você não poderá criá-las pelo conector do dbt. A criação de tabelas com os motores Iceberg() poderá ser adicionada no futuro.
- Operações de escrita: no momento, a escrita em tabelas Iceberg/Data Catalog é limitada. Consulte a documentação do ClickHouse para entender quais opções estão disponíveis.