Características y configuraciones

Descripción de las características y las configuraciones generales disponibles

En esta sección, ofrecemos documentación sobre algunas de las funcionalidades disponibles de dbt con ClickHouse.

​

Configuración de profiles.yml

Para conectarte a ClickHouse desde dbt, tendrás que añadir un perfil a tu archivo profiles.yml. Un perfil de ClickHouse sigue la siguiente sintaxis:

your_profile_name:
  target: dev
  outputs:
    dev:
      type: clickhouse

      # Optional
      schema: [default] # ClickHouse database for dbt models
      driver: [http] # http or native.  If not set this will be autodetermined based on port setting
      host: [localhost]
      port: [8123]  # If not set, defaults to 8123, 8443, 9000, 9440 depending on the secure and driver settings
      user: [default] # User for all database operations
      password: [<empty string>] # Password for the user
      cluster: [<empty string>] # If set, certain DDL/table operations will be executed with the `ON CLUSTER` clause using this cluster. Distributed materializations require this setting to work. See the following ClickHouse Cluster section for more details.
      verify: [True] # Validate TLS certificate if using TLS/SSL
      secure: [False] # Use TLS (native protocol) or HTTPS (http protocol)
      client_cert: [null] # Path to a TLS client certificate in .pem format
      client_cert_key: [null] # Path to the private key for the TLS client certificate
      server_host_name: [null] # Override the TLS SNI and hostname verification target. Useful when connecting via a DNS alias (e.g. an internal CNAME or AWS PrivateLink endpoint) where the TLS certificate is issued for a different hostname than the one used in `host`.
      retries: [1] # Number of times to retry a "retriable" database exception (such as a 503 'Service Unavailable' error)
      compression: [<empty string>] # Use gzip compression if truthy (http), or compression type for a native connection
      connect_timeout: [10] # Timeout in seconds to establish a connection to ClickHouse
      send_receive_timeout: [300] # Timeout in seconds to receive data from the ClickHouse server
      cluster_mode: [False] # Use specific settings designed to improve operation on Replicated databases (recommended for ClickHouse Cloud)
      use_lw_deletes: [False] # Use the strategy `delete+insert` as the default incremental strategy.
      check_exchange: [True] # Validate that clickhouse support the atomic EXCHANGE TABLES command.  (Not needed for most ClickHouse versions)
      local_suffix: [_local] # Table suffix of local tables on shards for distributed materializations.
      local_db_prefix: [<empty string>] # 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. Note: disabling connection reuse adds a new TCP/TLS handshake per model, which increases total `dbt run` wall time (typically ~200-500 ms per model). Combine with `threads > 1` for the best balance between distribution and throughput.
      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 para obtener más información.

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:

{{ 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í.
• 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 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 del rol de IAM creado para el acceso seguro a S3. Consulta esta documentación para obtener más información.
external_id	El ID externo que se pasará junto con role_arn al asumir el rol de IAM. Requiere que role_arn esté configurado. Disponible desde dbt-clickhouse 1.10.2.
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.

​

Ejemplo

Define la configuración compartida en dbt_project.yml (el nombre del diccionario debe terminar en s3):

vars:
  taxi_s3:
    bucket: 'datasets-documentation.s3.eu-west-3.amazonaws.com/nyc-taxi'
    fmt: 'TabSeparatedWithNames'

Luego, llama a la macro en un modelo. También puedes pasar cualquiera de los argumentos anteriores directamente en la llamada; estos tendrán prioridad sobre los valores del diccionario:

select * from {{ clickhouse_s3source('taxi_s3', path='/trips_4.gz') }}

Consulta el archivo de prueba de S3 para ver más ejemplos.

​

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.

​

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 y la función de tabla Iceberg.

• Además, ClickHouse proporciona el motor de base de datos DataLakeCatalog, 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:

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

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:

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.