] # Database prefix of local tables on shards for distributed materializations. If empty, it uses the same database as the distributed table.
allow_automatic_deduplication: [False] # Enable ClickHouse automatic deduplication for Replicated tables
tcp_keepalive: [False] # Native client only, specify TCP keepalive configuration. Specify custom keepalive settings as [idle_time_sec, interval_sec, probes].
reuse_connections: [True] # Re-use the same connection across models. Set to `False` to close the connection at the end of each model — useful on multi-replica ClickHouse Cloud services where the load balancer routes by TCP connection.
custom_settings: [{}] # A dictionary/mapping of custom ClickHouse settings for the connection - default is empty.
database_engine: '' # Database engine to use when creating new ClickHouse schemas (databases). If not set (the default), new databases will use the default ClickHouse database engine (usually Atomic).
threads: [1] # Number of threads to use when running queries. Before setting it to a number higher than 1, make sure to read the [read-after-write consistency](#read-after-write-consistency) section.
# Native (clickhouse-driver) connection settings
sync_request_timeout: [5] # Timeout for server ping
compress_block_size: [1048576] # Compression block size if compression is enabled
```
### Esquema vs base de datos
El identificador de relación del modelo de dbt `database.schema.table` no es compatible con ClickHouse porque ClickHouse no
admite `schema`.
Por eso, usamos un enfoque simplificado: `schema.table`, donde `schema` es la database de ClickHouse. No se recomienda usar la database `default`.
### Advertencia sobre la sentencia SET
En muchos entornos, usar la sentencia SET para hacer persistente una configuración de ClickHouse en todas las consultas de DBT no es fiable
y puede provocar fallos inesperados. Esto es especialmente cierto cuando se usan conexiones HTTP a través de un balanceador de carga que
distribuye las consultas entre varios nodos (como ClickHouse Cloud), aunque en algunas circunstancias esto también puede
ocurrir con conexiones nativas de ClickHouse. En consecuencia, recomendamos configurar cualquier ajuste de ClickHouse necesario en la
propiedad "custom\_settings" del perfil de DBT como práctica recomendada, en lugar de depender de una sentencia "SET" en un pre-hook, como
se ha sugerido en ocasiones.
### Configuración de `quote_columns`
Para evitar una advertencia, asegúrate de establecer explícitamente un valor para `quote_columns` en tu archivo `dbt_project.yml`. Consulta la [documentación sobre quote\_columns](https://docs.getdbt.com/reference/resource-configs/quote_columns) para obtener más información.
```yaml theme={null}
seeds:
+quote_columns: false #o `true` si tienes encabezados de columna CSV con espacios
```
### Acerca del clúster de ClickHouse
Al usar un clúster de ClickHouse, debes tener en cuenta dos aspectos:
* Configurar el parámetro `cluster`.
* Garantizar la consistencia de lectura después de la escritura, especialmente si `threads` es mayor que 1.
#### Configuración de clúster
La configuración `cluster` del perfil permite que dbt-clickhouse se ejecute en un clúster de ClickHouse. Si `cluster` está definida en el perfil, **todos los modelos se crearán con la cláusula `ON CLUSTER`** de forma predeterminada, excepto los que usan un motor **Replicated**. Esto incluye:
* Creación de bases de datos
* Materializaciones de vistas
* Materializaciones de tablas e incrementales
* Materializaciones Distributed
Los motores Replicated **no** incluirán la cláusula `ON CLUSTER`, ya que están diseñados para gestionar la replicación internamente.
Para **desactivar** la creación basada en clúster para un modelo específico, agrega la configuración `disable_on_cluster`:
```sql theme={null}
{{ config(
engine='MergeTree',
materialized='table',
disable_on_cluster='true'
)
}}
```
las materializaciones de tabla e incrementales con motor no replicado no se verán afectadas por la configuración de `cluster` (el modelo
se creará únicamente en el nodo conectado).
**Compatibilidad**
Si un modelo se ha creado sin una configuración de `cluster`, dbt-clickhouse detectará esta situación y ejecutará todo el DDL/DML
sin la cláusula `on cluster` para ese modelo.
#### Consistencia de lectura después de la escritura
dbt se basa en un modelo de consistencia de lectura después de la inserción. Esto no es compatible con clústeres de ClickHouse que tienen más de una réplica si no puedes garantizar que todas las operaciones se dirijan a la misma réplica. Puede que no tengas problemas en el uso diario de dbt, pero hay algunas estrategias, según tu clúster, para contar con esa garantía:
* Si usas un clúster de ClickHouse Cloud, solo necesitas establecer `select_sequential_consistency: 1` en la propiedad `custom_settings` de tu perfil. Puedes encontrar más información sobre esta configuración [aquí](/docs/es/reference/settings/session-settings#select_sequential_consistency).
* Si usas un clúster autohospedado, asegúrate de que todas las solicitudes de dbt se envíen a la misma réplica de ClickHouse. Si tienes un balanceador de carga delante, intenta usar algún mecanismo de `replica aware routing`/`sticky sessions` para poder llegar siempre a la misma réplica. [No se recomienda](/docs/es/reference/settings/session-settings#select_sequential_consistency) añadir la configuración `select_sequential_consistency = 1` en clústeres fuera de ClickHouse Cloud.
## Macros adicionales de ClickHouse
### Macros utilitarias de materialización de modelos
Se incluyen las siguientes macros para facilitar la creación de tablas y vistas específicas de ClickHouse:
* `engine_clause` -- Usa la propiedad de configuración `engine` del modelo para asignar un motor de tabla de ClickHouse. dbt-clickhouse
usa el engine `MergeTree` de forma predeterminada.
* `partition_cols` -- Usa la propiedad de configuración `partition_by` del modelo para asignar una clave de partición de ClickHouse. De forma predeterminada, no
se asigna ninguna clave de partición.
* `order_cols` -- Usa la configuración `order_by` del modelo para asignar una clave de ORDER BY/ordenación de ClickHouse. Si no se especifica,
ClickHouse usará una Tuple() vacía y la tabla no tendrá ordenación.
* `primary_key_clause` -- Usa la propiedad de configuración `primary_key` del modelo para asignar una clave primaria de ClickHouse. De
forma predeterminada, se establece una clave primaria y ClickHouse usará la cláusula ORDER BY como clave primaria.
* `on_cluster_clause` -- Usa la propiedad `cluster` del perfil para añadir una cláusula `ON CLUSTER` a determinadas operaciones de dbt:
materializaciones distribuidas, creación de vistas y creación de bases de datos.
* `ttl_config` -- Usa la propiedad de configuración `ttl` del modelo para asignar una expresión de TTL de tabla de ClickHouse. De forma predeterminada, no se
asigna ningún TTL.
### macro auxiliar `s3Source`
La macro `s3source` simplifica el proceso de seleccionar datos de ClickHouse directamente desde S3 mediante la función de tabla S3 de ClickHouse.
Funciona
rellenando los parámetros de la función de tabla S3 a partir de un diccionario de configuración con nombre (el nombre del diccionario debe terminar
en `s3`). La macro
primero busca el diccionario en las `vars` del perfil y luego en la configuración del modelo. El diccionario puede contener
cualquiera de las siguientes
claves utilizadas para rellenar los parámetros de la función de tabla S3:
| Argument Name | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bucket | La URL base del bucket, como `https://datasets-documentation.s3.eu-west-3.amazonaws.com/nyc-taxi`. Se asume `https://` si no se proporciona ningún protocolo. |
| path | La ruta de S3 que se usará para la consulta de la tabla, como `/trips_4.gz`. Se admiten comodines de S3. |
| fmt | El formato de entrada de ClickHouse esperado (como `TSV` o `CSVWithNames`) de los objetos S3 referenciados. |
| structure | La estructura de columnas de los datos del bucket, como una lista de pares nombre/tipo de dato, por ejemplo `['id UInt32', 'date DateTime', 'value String']`. Si no se proporciona, ClickHouse inferirá la estructura. |
| aws\_access\_key\_id | El ID de la clave de acceso de S3. |
| aws\_secret\_access\_key | La clave secreta de S3. |
| role\_arn | El ARN de un rol de IAM de ClickHouseAccess que se usará para acceder de forma segura a los objetos S3. Consulta esta [documentación](/docs/es/products/cloud/guides/data-sources/accessing-s3-data-securely) para obtener más información. |
| compression | El método de compresión utilizado con los objetos S3. Si no se proporciona, ClickHouse intentará determinar la compresión en función del nombre del archivo. |
Consulta
el [archivo de prueba de S3](https://github.com/ClickHouse/dbt-clickhouse/blob/main/tests/integration/adapter/clickhouse/test_clickhouse_s3.py)
para ver ejemplos de cómo usar esta macro.
### Compatibilidad con macros entre bases de datos
dbt-clickhouse ya admite la mayoría de las macros entre bases de datos incluidas en `dbt Core`, con las siguientes excepciones:
* La función SQL `split_part` está implementada en ClickHouse mediante la función splitByChar. Esta función requiere
usar una cadena constante como delimitador de "split", por lo que el parámetro `delimeter` usado para esta macro se
interpretará como una cadena, no como un nombre de columna
* Del mismo modo, la función SQL `replace` en ClickHouse requiere cadenas constantes para los parámetros `old_chars` y `new_chars`,
por lo que esos parámetros se interpretarán como cadenas en lugar de como nombres de columna al invocar esta macro.
## Soporte para catálogos
### Estado de la integración de catálogos en dbt
dbt Core v1.10 introdujo compatibilidad con la integración de catálogos, lo que permite a los adaptadores materializar modelos en catálogos externos que gestionan formatos de tabla abiertos como Apache Iceberg. **Esta funcionalidad aún no está implementada de forma nativa en dbt-clickhouse.** Puedes seguir el progreso de la implementación de esta funcionalidad en el [issue n.º 489 de GitHub](https://github.com/ClickHouse/dbt-clickhouse/issues/489).
### Soporte de catálogos en ClickHouse
ClickHouse ha añadido recientemente compatibilidad nativa con tablas Apache Iceberg y catálogos de datos. La mayoría de estas funciones siguen siendo `experimental`, pero ya puede usarlas si utiliza una versión reciente de ClickHouse.
* Puede usar ClickHouse para **consultar tablas Iceberg almacenadas en almacenamiento de objetos** (S3, Azure Blob Storage, Google Cloud Storage) mediante el [motor de tabla Iceberg](/docs/es/reference/engines/table-engines/integrations/iceberg) y la [función de tabla Iceberg](/docs/es/reference/functions/table-functions/iceberg).
* Además, ClickHouse proporciona el [motor de base de datos DataLakeCatalog](/docs/es/reference/engines/database-engines/datalake), que permite la **conexión a catálogos de datos externos** como AWS Glue Catalog, Databricks Unity Catalog, Hive Metastore y catálogos REST. Esto le permite consultar datos en formatos de tabla abiertos (Iceberg, Delta Lake) directamente desde catálogos externos sin duplicar los datos.
### Soluciones alternativas para trabajar con Iceberg y catálogos
Puedes leer datos de tablas Iceberg o de catálogos desde tu proyecto de dbt si ya los has definido en tu clúster de ClickHouse con las herramientas mencionadas anteriormente. Puedes usar la funcionalidad `source` de dbt para hacer referencia a estas tablas en tus proyectos de dbt. Por ejemplo, si quieres acceder a tus tablas en un REST Catalog, puedes:
1. **Crear una base de datos que apunte a un catálogo externo:**
```sql theme={null}
-- Ejemplo con REST Catalog
SET allow_experimental_database_iceberg = 1;
CREATE DATABASE iceberg_catalog
ENGINE = DataLakeCatalog('http://rest:8181/v1', 'admin', 'password')
SETTINGS
catalog_type = 'rest',
storage_endpoint = 'http://minio:9000/lakehouse',
warehouse = 'demo'
```
2. **Defina la base de datos del catálogo y sus tablas como fuentes en dbt:** recuerde que las tablas ya deben estar disponibles en ClickHouse
```yaml theme={null}
version: 2
sources:
- name: external_catalog
database: iceberg_catalog
tables:
- name: orders
- name: customers
```
3. **Usa las tablas del catálogo en tus modelos de dbt:**
```sql theme={null}
SELECT
o.order_id,
c.customer_name,
o.order_date
FROM {{ source('external_catalog', 'orders') }} o
INNER JOIN {{ source('external_catalog', 'customers') }} c
ON o.customer_id = c.customer_id
```
### Notas sobre las soluciones alternativas
Lo positivo de estas soluciones alternativas es:
* Tendrá acceso inmediato a distintos tipos de tablas externas y catálogos externos sin tener que esperar a la integración nativa de catálogos en dbt.
* Tendrá una vía de migración fluida cuando la compatibilidad nativa con catálogos esté disponible.
Pero actualmente hay algunas limitaciones:
* **Configuración manual:** Las tablas Iceberg y las bases de datos de catálogo deben crearse manualmente en ClickHouse antes de poder referenciarse en dbt.
* **Sin DDL a nivel de catálogo:** dbt no puede gestionar operaciones a nivel de catálogo, como crear o eliminar tablas Iceberg en catálogos externos. Por lo tanto, ahora mismo no podrá crearlas desde el conector de dbt. La creación de tablas con los motores Iceberg() podría añadirse en el futuro.
* **Operaciones de escritura:** Actualmente, la escritura en tablas Iceberg/Data Catalog es limitada. Consulte la documentación de ClickHouse para conocer qué opciones están disponibles.