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

> Puedes transformar y modelar tus datos en ClickHouse con dbt

# Integración entre dbt y ClickHouse

export const ClickHouseSupportedBadge = () => {
  return <div className="ClickHouseSupportedBadge">
            <div className="ClickHouseSupportedIcon">
                <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                    <path d="M1.30762 1.39073C1.30762 1.3103 1.37465 1.22986 1.46849 1.22986H2.64824C2.72868 1.22986 2.80912 1.29689 2.80912 1.39073V14.4886C2.80912 14.5691 2.74209 14.6495 2.64824 14.6495H1.46849C1.38805 14.6495 1.30762 14.5825 1.30762 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M4.2832 1.39073C4.2832 1.3103 4.35023 1.22986 4.44408 1.22986H5.62383C5.70427 1.22986 5.7847 1.29689 5.7847 1.39073V14.4886C5.7847 14.5691 5.71767 14.6495 5.62383 14.6495H4.44408C4.36364 14.6495 4.2832 14.5825 4.2832 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M7.25977 1.39073C7.25977 1.3103 7.3268 1.22986 7.42064 1.22986H8.60039C8.68083 1.22986 8.76127 1.29689 8.76127 1.39073V14.4886C8.76127 14.5691 8.69423 14.6495 8.60039 14.6495H7.42064C7.3402 14.6495 7.25977 14.5825 7.25977 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M10.2354 1.39073C10.2354 1.3103 10.3024 1.22986 10.3962 1.22986H11.576C11.6564 1.22986 11.7369 1.29689 11.7369 1.39073V14.4886C11.7369 14.5691 11.6698 14.6495 11.576 14.6495H10.3962C10.3158 14.6495 10.2354 14.5825 10.2354 14.4886V1.39073Z" fill="currentColor" />
                    <path d="M13.2256 6.6057C13.2256 6.52526 13.2926 6.44482 13.3865 6.44482H14.5662C14.6466 6.44482 14.7271 6.51186 14.7271 6.6057V9.27354C14.7271 9.35398 14.6601 9.43442 14.5662 9.43442H13.3865C13.306 9.43442 13.2256 9.36739 13.2256 9.27354V6.6057Z" fill="currentColor" />
                </svg>
            </div>
            Compatible con ClickHouse
        </div>;
};

<ClickHouseSupportedBadge />

<div id="dbt-clickhouse-adapter">
  ## El adaptador dbt-clickhouse
</div>

**dbt** (data build tool) permite a los ingenieros de analítica transformar datos en sus almacenes de datos simplemente escribiendo sentencias `select`. dbt se encarga de materializar estas sentencias `select` como objetos en la base de datos, en forma de tablas y vistas, realizando la T de [Extract Load and Transform (ELT)](https://en.wikipedia.org/wiki/Extract,_load,_transform). Puede crear un modelo definido por una sentencia `SELECT`.

Dentro de dbt, estos modelos pueden referenciarse entre sí y organizarse en capas para construir conceptos de nivel superior. El código SQL repetitivo necesario para conectar modelos se genera automáticamente. Además, dbt identifica las dependencias entre modelos y garantiza que se creen en el orden adecuado mediante un grafo acíclico dirigido (DAG).

dbt es compatible con ClickHouse mediante un [adaptador con soporte para ClickHouse](https://github.com/ClickHouse/dbt-clickhouse).

<div id="related-pages">
  ## Páginas relacionadas
</div>

| Página                                                                                                                    | Descripción                                                                |
| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [Funcionalidades y configuraciones](/docs/es/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations) | Descripción de las funcionalidades y configuraciones generales disponibles |
| [Materializaciones](/docs/es/integrations/connectors/data-ingestion/etl-tools/dbt/materializations)                            | Materializaciones disponibles y sus configuraciones                        |
| [Vistas materializadas](/docs/es/integrations/connectors/data-ingestion/etl-tools/dbt/materialization-materialized-view)       | Documentación específica de la materialización materialized\_view          |
| [Guías](/docs/es/integrations/connectors/data-ingestion/etl-tools/dbt/guides)                                                  | Guías para usar dbt con ClickHouse                                         |

<div id="supported-features">
  ## Funcionalidades compatibles
</div>

Lista de funcionalidades compatibles:

* [x] Materialización de tabla
* [x] Materialización de vista
* [x] Materialización incremental
* [x] Materialización incremental de Microbatch
* [x] Materializaciones de vista materializada (usa la forma `TO` de MATERIALIZED VIEW, experimental)
* [x] Seeds
* [x] Sources
* [x] Generación de documentación
* [x] Pruebas
* [x] Snapshots
* [x] La mayoría de las macros de dbt-utils (ahora incluidas en dbt-core)
* [x] Materialización efímera
* [x] Materialización de tabla distribuida (experimental)
* [x] Materialización incremental distribuida (experimental)
* [x] Contratos
* [x] Configuraciones de columna específicas de ClickHouse (Codec, TTL...)
* [x] Configuración de tablas específica de ClickHouse (índices, proyecciones...)

Se admiten todas las funcionalidades hasta dbt-core 1.10, incluida la opción `--sample`, y se han corregido todas las advertencias de desuso de cara a futuras versiones. Las **integraciones de catálogo** (por ejemplo, Iceberg) introducidas en dbt 1.10 aún no son compatibles de forma nativa en el adaptador, pero hay soluciones alternativas disponibles. Consulta la [sección Compatibilidad con catálogos](/docs/es/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations#catalog-support) para obtener más información.

Este adaptador todavía no está disponible para su uso en [dbt Cloud](https://docs.getdbt.com/docs/dbt-cloud/cloud-overview), pero esperamos ponerlo a disposición pronto. Ponte en contacto con el equipo de soporte para obtener más información al respecto.

<div id="concepts-and-supported-materializations">
  ## Conceptos de dbt y materializaciones compatibles
</div>

dbt introduce el concepto de modelo. Este se define como una sentencia SQL que potencialmente combina muchas tablas. Un modelo puede "materializarse" de varias maneras. Una materialización representa una estrategia de construcción para la consulta SELECT del modelo. El código detrás de una materialización es SQL repetitivo que envuelve tu consulta SELECT en una sentencia para crear una nueva relación o actualizar una existente.

dbt proporciona 5 tipos de materialización. Todos ellos son compatibles con `dbt-clickhouse`:

* **view** (predeterminado): El modelo se construye como una vista en la base de datos. En ClickHouse, esto se construye como una [vista](/docs/es/reference/statements/create/view).
* **table**: El modelo se construye como una tabla en la base de datos. En ClickHouse, esto se construye como una [tabla](/docs/es/reference/statements/create/table).
* **ephemeral**: El modelo no se construye directamente en la base de datos, sino que se incorpora en los modelos dependientes como CTE (expresiones de tabla comunes).
* **incremental**: El modelo se materializa inicialmente como una tabla y, en ejecuciones posteriores, dbt inserta filas nuevas y actualiza las filas modificadas en la tabla.
* **materialized view**: El modelo se construye como una vista materializada en la base de datos. En ClickHouse, esto se construye como una [vista materializada](/docs/es/reference/statements/create/view#materialized-view).

La sintaxis y las cláusulas adicionales definen cómo deben actualizarse estos modelos si cambian sus datos subyacentes. Por lo general, dbt recomienda comenzar con la materialización view hasta que el rendimiento se convierta en una preocupación. La materialización table ofrece una mejora del rendimiento en tiempo de consulta al capturar los resultados de la consulta del modelo como una tabla, a costa de un mayor almacenamiento. El enfoque incremental desarrolla aún más esta idea para permitir que las actualizaciones posteriores de los datos subyacentes se capturen en la tabla de destino.

El [adaptador actual](https://github.com/silentsokolov/dbt-clickhouse) para ClickHouse también admite las materializaciones **dictionary**, **distributed table** y **distributed incremental**. El adaptador también admite [snapshots](https://docs.getdbt.com/docs/building-a-dbt-project/snapshots#check-strategy) y [seeds](https://docs.getdbt.com/docs/building-a-dbt-project/seeds) de dbt.

Las siguientes son [características experimentales](/docs/es/reference/settings/beta-and-experimental-features) en `dbt-clickhouse`:

| Tipo                                    | ¿Compatible?                                     | Detalles                                                                                                                                                                                                                                                                                                               |
| --------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Materialización de vista materializada  | Sí. La creación con explicit target está en Beta | Crea una [vista materializada](/docs/es/reference/statements/create/view#materialized-view).                                                                                                                                                                                                                                |
| Materialización de tabla distribuida    | Sí, Experimental                                 | Crea una [tabla distribuida](/docs/es/reference/engines/table-engines/special/distributed).                                                                                                                                                                                                                                 |
| Materialización incremental distribuida | Sí, Experimental                                 | Modelo incremental basado en la misma idea que la tabla distribuida. Ten en cuenta que no todas las estrategias son compatibles; visita [su sección de documentación](/docs/es/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#materialization-distributed-incremental) para obtener más información. |
| Materialización de Diccionario          | Sí, Experimental                                 | Crea un [Diccionario](/docs/es/reference/engines/table-engines/special/dictionary).                                                                                                                                                                                                                                         |

<div id="setup-of-dbt-and-the-clickhouse-adapter">
  ## Configuración de dbt y del adaptador de ClickHouse
</div>

<div id="install-dbt-core-and-dbt-clickhouse">
  ### Instalar dbt-core y dbt-clickhouse
</div>

dbt ofrece varias opciones para instalar la interfaz de línea de comandos (CLI), que se detallan [aquí](https://docs.getdbt.com/dbt-cli/install/overview). Recomendamos utilizar `pip` para instalar tanto dbt como dbt-clickhouse.

```sh theme={null}
pip install dbt-core dbt-clickhouse
```

<div id="provide-dbt-with-the-connection-details-for-our-clickhouse-instance">
  ### Proporcione a dbt los datos de conexión de nuestra instancia de ClickHouse.
</div>

Configure el perfil `clickhouse-service` en el archivo `~/.dbt/profiles.yml` y proporcione las propiedades de esquema, host, puerto, usuario y contraseña. La lista completa de opciones de configuración de la conexión está disponible en la página [Características y configuraciones](/docs/es/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations):

```yaml theme={null}
clickhouse-service:
  target: dev
  outputs:
    dev:
      type: clickhouse
      schema: [ default ] # Base de datos de ClickHouse para modelos dbt

      # Opcional
      host: [ localhost ]
      port: [ 8123 ]  # El valor predeterminado es 8123, 8443, 9000 o 9440 según la configuración de secure y driver 
      user: [ default ] # Usuario para todas las operaciones de base de datos
      password: [ <empty string> ] # Contraseña del usuario
      secure: True  # Usar TLS (protocolo nativo) o HTTPS (protocolo HTTP)
```

<div id="create-a-dbt-project">
  ### Crear un proyecto de dbt
</div>

Ahora puedes usar este perfil en uno de tus proyectos existentes o crear uno nuevo mediante:

```sh theme={null}
dbt init project_name
```

Dentro del directorio `project_name`, actualiza el archivo `dbt_project.yml` para especificar un nombre de perfil para conectarte al servidor de ClickHouse.

```yaml theme={null}
profile: 'clickhouse-service'
```

<div id="test-connection">
  ### Probar la conexión
</div>

Ejecuta `dbt debug` con la herramienta de línea de comandos para confirmar si dbt puede conectarse a ClickHouse. Verifica que la respuesta incluya `Connection test: [OK connection ok]`, lo que indica que la conexión se ha realizado correctamente.

Ve a la [página de guías](/docs/es/integrations/connectors/data-ingestion/etl-tools/dbt/guides) para obtener más información sobre cómo usar dbt con ClickHouse.

<div id="testing-and-deploying-your-models-ci-cd">
  ### Probar y desplegar tus modelos (CI/CD)
</div>

Hay muchas formas de probar y desplegar tu proyecto de dbt. dbt ofrece algunas recomendaciones sobre [flujos de trabajo recomendados](https://docs.getdbt.com/best-practices/best-practice-workflows#pro-tips-for-workflows) y [trabajos de CI](https://docs.getdbt.com/docs/deploy/ci-jobs). Vamos a analizar varias estrategias, pero ten en cuenta que puede ser necesario ajustarlas en profundidad para adaptarlas a tu caso de uso específico.

<div id="ci-with-simple-data-tests-and-unit-tests">
  #### CI/CD con pruebas de datos simples y pruebas unitarias
</div>

Una forma sencilla de poner en marcha tu pipeline de CI es ejecutar un clúster de ClickHouse dentro de tu job y luego ejecutar tus modelos en él. Puedes insertar datos de demostración en este clúster antes de ejecutar tus modelos. También puedes usar un [seed](https://docs.getdbt.com/reference/commands/seed) para poblar el entorno de staging con un subconjunto de tus datos de producción.

Una vez insertados los datos, puedes ejecutar tus [pruebas de datos](https://docs.getdbt.com/docs/build/data-tests) y tus [pruebas unitarias](https://docs.getdbt.com/docs/build/unit-tests).

Tu step de CD puede ser tan simple como ejecutar `dbt build` contra tu clúster de ClickHouse de producción.

<div id="more-complete-ci-stage">
  #### Etapa de CI/CD más completa: usar datos recientes y probar solo los modelos afectados
</div>

Una estrategia habitual consiste en usar trabajos de [Slim CI](https://docs.getdbt.com/best-practices/best-practice-workflows#run-only-modified-models-to-test-changes-slim-ci), en los que solo se vuelven a desplegar los modelos modificados (y sus dependencias ascendentes y descendentes). Este enfoque utiliza artefactos de tus ejecuciones de producción (es decir, el [manifiesto de dbt](https://docs.getdbt.com/reference/artifacts/manifest-json)) para reducir el tiempo de ejecución de tu proyecto y garantizar que no haya divergencias de esquema entre entornos.

Para mantener tus entornos de desarrollo sincronizados y evitar ejecutar tus modelos sobre despliegues obsoletos, puedes usar [clone](https://docs.getdbt.com/reference/commands/clone) o incluso [defer](https://docs.getdbt.com/reference/node-selection/defer).

Recomendamos usar un clúster o servicio de ClickHouse dedicado para el entorno de pruebas (es decir, un entorno de staging) para evitar afectar al funcionamiento de tu entorno de producción. Para garantizar que el entorno de pruebas sea representativo, es importante que uses un subconjunto de tus datos de producción y que ejecutes dbt de una forma que evite divergencias de esquema entre entornos.

* Si no necesitas datos recientes para las pruebas, puedes restaurar una copia de seguridad de tus datos de producción en el entorno de staging.
* Si necesitas datos recientes para las pruebas, puedes usar una combinación de la [función de tabla `remoteSecure()`](/docs/es/reference/functions/table-functions/remote) y vistas materializadas actualizables para insertar con la frecuencia deseada. Otra opción es usar almacenamiento de objetos como intermediario y escribir datos periódicamente desde tu servicio de producción para luego importarlos al entorno de staging mediante las funciones de tabla de almacenamiento de objetos o ClickPipes (para la ingestión continua).

Usar un entorno dedicado para las pruebas de CI también te permite realizar pruebas manuales sin afectar a tu entorno de producción. Por ejemplo, puede que quieras apuntar una herramienta de BI a este entorno para hacer pruebas.

Para el despliegue (es decir, el paso de CD), recomendamos usar los artefactos de tus despliegues de producción para actualizar solo los modelos que hayan cambiado. Esto requiere configurar almacenamiento de objetos (por ejemplo, S3) como almacenamiento intermedio para tus artefactos de dbt. Una vez configurado, puedes ejecutar un comando como `dbt build --select state:modified+ --state path/to/last/deploy/state.json` para reconstruir selectivamente la cantidad mínima de modelos necesaria en función de lo que haya cambiado desde la última ejecución en producción.

<div id="troubleshooting-common-issues">
  ## Solución de problemas frecuentes
</div>

<div id="troubleshooting-connections">
  ### Conexiones
</div>

Si tienes problemas para conectarte a ClickHouse desde dbt, asegúrate de que se cumplan los siguientes criterios:

* El motor debe ser uno de los [motores compatibles](/docs/es/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#supported-table-engines).
* Debes tener los permisos adecuados para acceder a la base de datos.
* Si no usas el motor de tabla predeterminado de la base de datos, debes especificar un motor de tabla en la configuración de tu modelo.

<div id="understanding-long-running-operations">
  ### Comprender las operaciones de larga duración
</div>

Algunas operaciones pueden tardar más de lo esperado debido a consultas específicas de ClickHouse. Para obtener más información sobre qué consultas tardan más, aumente el [nivel de registro](https://docs.getdbt.com/reference/global-configs/logs#log-level) a `debug`; esto mostrará el tiempo empleado por cada consulta. Por ejemplo, puede lograrse añadiendo `--log-level debug` a los comandos de dbt.

<div id="limitations">
  ## Limitaciones
</div>

El adaptador actual de ClickHouse para dbt tiene varias limitaciones que debe tener en cuenta:

* El plugin usa una sintaxis que requiere ClickHouse versión 25.3 o posterior. No probamos versiones anteriores de ClickHouse. Actualmente tampoco probamos tablas Replicated.
* Distintas ejecuciones de `dbt-adapter` pueden entrar en conflicto si se ejecutan al mismo tiempo, ya que internamente pueden usar los mismos nombres de tabla para las mismas operaciones. Para más información, consulte el issue [#420](https://github.com/ClickHouse/dbt-clickhouse/issues/420).
* Actualmente, el adaptador materializa los modelos como tablas mediante [INSERT INTO SELECT](/docs/es/reference/statements/insert-into#inserting-the-results-of-select). En la práctica, esto implica duplicación de datos si la ejecución vuelve a realizarse. Los datasets muy grandes (PB) pueden dar lugar a tiempos de ejecución extremadamente largos, lo que hace inviables algunos modelos. Para mejorar el rendimiento, use vistas materializadas de ClickHouse implementando la vista como `materialized: materialization_view`. Además, procure minimizar el número de filas que devuelve cualquier consulta usando `GROUP BY` siempre que sea posible. Priorice modelos que resuman los datos frente a los que simplemente los transforman manteniendo el mismo número de filas del source.
* Para usar tablas Distributed para representar un modelo, debe crear manualmente las tablas replicadas subyacentes en cada nodo. La tabla Distributed puede, a su vez, crearse sobre ellas. El adaptador no gestiona la creación del cluster.
* Cuando dbt crea una relación (table/view) en una database, normalmente la crea como: `{{ database }}.{{ schema }}.{{ table/view id }}`. ClickHouse no tiene el concepto de esquemas. Por lo tanto, el adaptador usa `{{schema}}.{{ table/view id }}`, donde `schema` es la database de ClickHouse.
* Los modelos efímeros/CTE no funcionan si se colocan antes de `INSERT INTO` en una sentencia insert de ClickHouse; consulte [https://github.com/ClickHouse/ClickHouse/issues/30323](https://github.com/ClickHouse/ClickHouse/issues/30323). Esto no debería afectar a la mayoría de los modelos, pero debe prestarse atención a dónde se coloca un modelo efímero en las definiciones de modelos y otras sentencias SQL. {/* TODO revisar esta limitación, parece que el issue ya se cerró y la corrección se introdujo en la 24.10 */}

<div id="fivetran">
  ## Fivetran
</div>

El conector `dbt-clickhouse` también está disponible para su uso en las [transformaciones de Fivetran](https://fivetran.com/docs/transformations/dbt), lo que permite integrar y transformar datos sin problemas directamente en la plataforma de Fivetran mediante `dbt`.