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

> Estado del adaptador de ClickHouse en dbt OSS, dbt v2 y la plataforma dbt

# dbt OSS, v2 y Platform (Beta)

Compatible con ClickHouse

[Beta](https://github.com/ClickHouse/dbt-clickhouse/issues/660)

dbt se está reconstruyendo sobre un nuevo motor, y ClickHouse forma parte de ello desde el principio. ClickHouse ya funciona con el nuevo motor de dbt escrito en Rust, tanto en dbt OSS como en dbt v2, y por primera vez es posible conectarse a ClickHouse desde la plataforma dbt. Tu proyecto no cambia: los mismos modelos, tests y profiles que hoy se ejecutan en dbt Core 1.x se ejecutan en el nuevo motor; lo único distinto es el binary.

ClickHouse es el primer adaptador de la comunidad en dbt OSS, dbt v2 y la plataforma dbt. Los adaptadores propios de dbt se lanzan junto con el nuestro; nosotros somos los primeros ajenos a dbt Labs. El adaptador de Python para dbt Core 1.x, `dbt-clickhouse`, no desaparece: lo mantenemos al día con los releases de dbt 1.x y damos mantenimiento a ambos adaptadores en paralelo.

> [!WARNING]
>
> **No está listo para producción.** El adaptador de ClickHouse para dbt OSS y dbt v2, así como la conexión con la plataforma dbt, todavía no están generally available (GA). Úsalos únicamente en proyectos de desarrollo o de staging.

> [!NOTE]
>
> **La documentación de dbt Core 1.x también se aplica a dbt OSS y dbt v2.** El adaptador se comporta igual en ambos motores: los profiles, las configuraciones de modelo, las materializaciones y los macros descritos en las demás páginas de dbt funcionan sin cambios en dbt OSS, dbt v2 y la plataforma dbt. Las excepciones están documentadas en la tabla de [paridad entre v1 y v2](#parity) que aparece más abajo.

> [!NOTE]
>
> **dbt OSS** es la build open-source (Apache 2.0) del motor v2. Consulta [terminología y availability](#terminology) para ver cómo se relaciona con dbt v2 y la plataforma dbt.

El estado actualizado se registra en [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660) (paridad de v2 con v1, un sub-issue por área) y en [ClickHouse/dbt-clickhouse#555](https://github.com/ClickHouse/dbt-clickhouse/issues/555) (dbt v2).

#### Prueba ClickHouse en la plataforma dbt

Si te interesa probar la beta privada, regístrate mediante el [formulario de beta privada de dbt Labs](https://docs.google.com/forms/d/e/1FAIpQLScjHwRchnKarq_RpNM7hATjphNFxqBEePmAwRtSpMWG1snGHA/viewform). El formulario pertenece a dbt Labs, por lo que la información que envíes llegará a dbt Labs y no a ClickHouse. Una vez habilitado el acceso, sigue las instrucciones de [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) en la documentación de dbt para configurar la conexión.

## Terminología y disponibilidad

dbt está disponible en varias formas, y un mismo adaptador puede ejecutarse en más de una de ellas. Esta tabla explica cada nombre y el nivel actual de soporte de ClickHouse.

| Término | Qué es | Estado en ClickHouse y cómo obtenerlo |
| - | - | - |
| **dbt Core 1.x** | El motor de dbt basado en Python, open source (Apache 2.0). Nuestro adaptador es `dbt-clickhouse`, mantenido en la [organización de ClickHouse en GitHub](https://github.com/ClickHouse/dbt-clickhouse) e instalado junto con `dbt-core`. | **GA, con mantenimiento activo.** Sigue recibiendo releases en paralelo con dbt v2. |
| **dbt OSS** | Reescritura completa del motor de dbt en Rust, open source (Apache 2.0). Esta nueva versión incluye todas las features de la v1 más varias mejoras del rendimiento. | **Beta.** Consulta la [guía de upgrade a dbt v2](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v2) y la [página de configuración de ClickHouse para la v2](https://docs.getdbt.com/docs/local/connect-data-platform/clickhouse-setup?version=2) en la documentación de dbt. El adaptador de ClickHouse se distribuye dentro del binary de dbt; no hay que instalar ningún package aparte. |
| **dbt v2** | dbt OSS más features adicionales de dbt Labs: comprensión de SQL, análisis estático, LSP, una extensión de VS Code y reconocimiento de columnas. Código cerrado, licenciado bajo el [dbt Product Licensing Agreement](https://www.getdbt.com/dbt-fusion-engine-license-agreement). | **Beta.** El adaptador funciona con el binary de la v2, pero las nuevas features de SQL todavía no están disponibles para ClickHouse. |
| **plataforma dbt** | dbt alojado, antes dbt Cloud: IDE Studio, jobs programados, entornos, Catalog, Semantic Layer. La plataforma solo ejecuta dbt v2, así que usar ClickHouse en la plataforma implica el adaptador de la v2. | **Private Beta.** Consulta [cómo solicitar acceso](#request-access). Configuración: [Conectar ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) en la documentación de dbt. |

## Estado Beta

Evaluamos el adaptador dbt v2 con la suite de pruebas de integración de dbt Core 1.x de `dbt-clickhouse`. Beta significa que los flujos de trabajo principales de dbt y el conjunto de funcionalidades de ClickHouse Cloud funcionan dentro de los límites documentados; la paridad completa con v1 y el soporte de clusters autogestionados llegarán más adelante.

**A día de hoy,** el adaptador supera más del 81% de la suite v1 completa y el 92% de las pruebas aplicables a ClickHouse Cloud. Todas las materializaciones están a la par (`view`, `table`, `incremental`, `materialized_view`, `dictionary`, `snapshot`, `seed`, `ephemeral`), junto con el conjunto completo de configuraciones de tabla, contratos de modelos, pruebas de datos y unitarias, persistencia de la documentación, `clickhouse_s3source()` y los ajustes de conexión de dbt Core 1.x. Los fallos restantes tienen que ver con el trabajo sobre clusters autogestionados que se detalla más abajo y con unas pocas diferencias del lado del motor. Consulta [paridad entre v1 y v2](#parity) para ver el panorama funcionalidad por funcionalidad.

**Próximos pasos**: DDL con `ON CLUSTER` y las materializaciones distribuidas para clusters autogestionados, grants, `dbt clone`, `dbt source freshness` a partir de los metadatos de las tablas, correcciones de los bugs restantes y superación de la suite de pruebas v1 completa para garantizar la paridad total. El progreso de todo ello se sigue en [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660), con un sub-issue por área.

GA está en el roadmap y llegará pronto. Actualizaremos la documentación en cuanto esté listo.

### Fuera del alcance de la Beta

Además de las diferencias de paridad con la v1 que se enumeran a continuación, algunas funcionalidades exclusivas de la v2 quedan fuera del alcance actual, pero llegarán pronto:

* **Semantic Layer / MetricFlow.** Todavía no se ha añadido compatibilidad con ClickHouse. Se hace seguimiento en [dbt-labs/metricflow#2124](https://github.com/dbt-labs/metricflow/pull/2124).
* **Inteligencia de ClickHouse SQL en dbt v2** (validación según el dialecto, análisis estático, LSP, reconocimiento de columnas en la extensión de VS Code). Actualmente, el adaptador funciona con el binary de dbt v2, pero aún no incluye estas funcionalidades. Hasta entonces, el análisis estático se fuerza a `off` en los proyectos de ClickHouse y el motor no escribe linaje a nivel de columna. Se hace seguimiento en [#736](https://github.com/ClickHouse/dbt-clickhouse/issues/736).
* **Métodos de autenticación adicionales** más allá de nombre de usuario y contraseña en la plataforma de dbt.

## Paridad entre v1 y v2

Las tablas siguientes comparan las funcionalidades disponibles en `dbt-clickhouse` (v1) con su estado en el adaptador de dbt v2. Todas las funcionalidades enumeradas son compatibles en v1 salvo que las notas indiquen lo contrario; la columna de estado corresponde a dbt v2 y se aplica igualmente a dbt OSS. La evolución de cada elemento pendiente se registra en [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660).

compatible funciona actualmente · parcial funciona con limitaciones · Aún no implementación pendiente.

### Materializaciones

| Funcionalidad | Qué hace | dbt v2 | Notas |
| - | - | - | - |
| `view` | Vista estándar de dbt. | Compatible | |
| `table` | Reconstrucción completa con opciones de motor y DDL. | Compatible | |
| `incremental` | Añade (append) o fusiona (merge) filas nuevas. | Compatible | |
| `materialized_view` | Vista materializada de ClickHouse que transforma los datos en el momento de la inserción. | Compatible | |
| `dictionary` | Diccionario de ClickHouse para búsquedas por clave y joins. | Compatible | |
| `snapshot` | Dimensiones de cambio lento de tipo 2. | Compatible | |
| `seed` | Carga archivos CSV como tablas. | Compatible | Los tipos de columna numéricos se infieren como `Int64`/`Float64` en lugar de `Int32`/`Float32`; utiliza `column_types` para definirlos explícitamente. |
| `ephemeral` | CTE en línea; no se crea ningún objeto. | Compatible | |
| `distributed_table`, `distributed_incremental` | Tablas segmentadas tras un motor Distributed. | Aún no | |

### Configuración del modelo

| Característica | Qué hace | dbt v2 | Notas |
| - | - | - | - |
| Motor, `ORDER BY`, `PARTITION BY`, `PRIMARY KEY` | Controles principales del DDL de MergeTree. | Compatible | |
| TTL | Expiración de filas y columnas. | Compatible | |
| Ajustes de tabla y de consulta | `SETTINGS` por modelo en el DDL y en el insert. | Compatible | |
| Proyecciones, índices, `sql_header` | Estructuras secundarias y SQL previo. | Compatible | |
| Contratos y restricciones del modelo | Tipos de columna y restricciones que se aplican en el momento del build. | Compatible | |
| Evolución del esquema en modelos incrementales | `on_schema_change` añade o sincroniza columnas. | Compatible | |
| `codec` y `ttl` de columna | Compresión y expiración por columna. | Compatible | |

### Pruebas y documentación

| Funcionalidad | Qué hace | dbt v2 | Notas |
| - | - | - | - |
| Pruebas de datos | Pruebas genéricas y singulares. | Compatible | |
| Unit tests | Lógica de los modelos frente a entradas de fixtures. | Compatible | |
| Persistencia de la documentación | Descripciones escritas como comentarios de ClickHouse. | Parcial | Las descripciones que contienen `;` fallan. |
| Generación del catálogo y de la documentación | Metadatos de columnas para el sitio de documentación. | Compatible | |
| Linaje a nivel de columna | Rastrea las columnas a través del DAG. | Parcial | Novedad en v2 mediante el compilador de SQL; no está disponible en v1. El linaje de la plataforma dbt solo se muestra si el entrecomillado de identificadores está desactivado en `dbt_project.yml`; el linaje del lado del motor requiere el dialecto ClickHouse SQL. |

### Cluster y Cloud

| Característica | Qué hace | dbt v2 | Notas |
| - | - | - | - |
| ClickHouse Cloud | Configuración Beta recomendada. | Compatible | |
| Consistencia entre varias réplicas | `select_sequential_consistency` y configuraciones relacionadas de lectura tras escritura. | Compatible | |
| `ON CLUSTER` y motores replicados | Propagación de DDL en clusters autogestionados. | Aún no | Los clusters de varios nodos en ClickHouse Cloud son compatibles. Otras configuraciones que requieren `ON CLUSTER` para propagar DDL todavía no son compatibles. En implementaciones autogestionadas, realice pruebas únicamente en clusters de un solo nodo. |
| `EXCHANGE TABLES` | Intercambio atómico durante la reconstrucción. | Compatible | |
| Configuraciones de conexión personalizadas | `custom_settings` a nivel de profile. | Compatible | |
| Versión del servidor ClickHouse | Versión mínima del servidor. | Compatible | 25.3+ en ambos motores. Para leer columnas `UUID` en v2 se requiere 26.7+ (los servidores anteriores no pueden convertir `UUID` a Arrow). |

### Macros y operaciones

| Funcionalidad | Qué hace | dbt v2 | Notas |
| - | - | - | - |
| Macro de table function de S3 | `clickhouse_s3source()` lee directamente de S3 en un modelo. | Compatible | |
| Macros entre bases de datos | Funciones auxiliares como las de `dbt-utils`. | Compatible | |
| Grants | Sentencias `GRANT` definidas en la configuración del modelo. | Aún no | |
| `dbt clone` | `CLONE AS` zero-copy entre entornos. | Aún no | |
| Query ID en los resultados de ejecución | `query_id` en `adapter_response` para correlacionar con `system.query_log`. | Aún no | |
| `query-comment` | Configuración del comentario de la consulta. | Aún no | Todavía no se respeta `query-comment: null`. |
| Integración con catálogos (Iceberg) | Materializar en catálogos externos. | Aún no | Tampoco está en v1; existen soluciones alternativas documentadas. |

### Conectividad y autenticación

| Funcionalidad | Qué hace | dbt v2 | Notas |
| - | - | - | - |
| Protocolo | Cómo se comunica dbt con ClickHouse. | Compatible | ADBC (Arrow sobre HTTP) en v2; HTTP y native en v1. |
| Nombre de usuario y contraseña, TLS | Autenticación estándar. | Compatible | |
| Certificados de cliente mTLS | `client_cert`, `client_cert_key`, `verify`. | Aún no | Pendiente en el driver; las keys se aceptan, pero se ignoran. |
| Opciones del client HTTP | `connect_timeout`, `send_receive_timeout`, `sync_request_timeout`, `compress_block_size`, `server_host_name`. | Aún no | Se aceptan, pero se ignoran; `server_host_name` no está disponible. |