Configuraciones generales de materialización
Motores de tabla compatibles
Nota: para las vistas materializadas, se admiten todos los motores de la familia *MergeTree.
Motores de tabla compatibles experimentales
Si tienes problemas para conectarte a ClickHouse desde dbt con alguno de los motores anteriores, informa del problema
aquí.
Una nota sobre la configuración del modelo
settings se refiere a la cláusula SETTINGS
usada en sentencias DDL del tipo CREATE TABLE/VIEW, por lo que, en general, se trata de configuraciones específicas del
motor de tabla concreto de ClickHouse. La nueva
query_settings se usa para añadir una cláusula SETTINGS a las consultas INSERT y DELETE utilizadas para la materialización del modelo (
incluidas las materializaciones incrementales).
Hay cientos de configuraciones en ClickHouse, y no siempre está claro cuál es una configuración de “tabla” y cuál es una
configuración de “usuario” (aunque estas últimas suelen estar
disponibles en la tabla system.settings). En general, se recomiendan los valores predeterminados, y cualquier uso de estas propiedades
debe investigarse y probarse cuidadosamente.
Configuración de columna
NOTA: Las opciones de configuración de columna que se indican a continuación requieren que se apliquen los contratos de modelo.
Ejemplo de configuración de esquema
Añadir tipos complejos
data_type del contrato. Para solucionarlo, recomendamos usar la función CAST() en el SQL del modelo para definir explícitamente el tipo deseado. Por ejemplo:
Materialización: vista
dbt_project.yml):
models/<model_name>.sql):
Materialización: tabla
dbt_project.yml):
models/<model_name>.sql):
Índices de omisión de datos
table mediante la configuración indexes:
Proyecciones
table y distributed_table mediante la configuración projections. Cada entrada de proyección requiere una clave query o una index (no ambas).
Nota: En las tablas distribuidas, la proyección se aplica a las tablas _local, no a la tabla proxy distribuida.
Nota: Especificar tanto query como index en la misma entrada de proyección genera un error de compilación.
Proyecciones de consultas
query para definir una consulta de proyección completa:
Proyecciones de índices
index como una abreviatura sintáctica para las proyecciones de índices ligeras que utilizan la columna virtual _part_offset. Pase un único nombre de columna o una lista de columnas según las que se desee ordenar:
Materialización: incremental
dbt_project.yml:
models/<model_name>.sql:
Configuraciones
Estrategias para modelos incrementales
dbt-clickhouse admite tres estrategias para modelos incrementales.
La estrategia predeterminada (heredada)
La estrategia Delete+Insert
delete+insert utiliza eliminaciones ligeras para eliminar las filas afectadas y después inserta las nuevas. Como no copia toda la tabla, ofrece un rendimiento significativamente superior al de la estrategia «heredado». Al configurar use_lw_deletes: true en el perfil, delete+insert se convierte en la estrategia incremental predeterminada.
Hay consideraciones importantes al utilizar esta estrategia:
- Opera directamente sobre la tabla afectada sin crear tablas intermedias ni temporales, por lo que, si se produce un issue durante la operación, es probable que los datos del modelo incremental queden en un estado no válido.
- Requiere el ajuste de ClickHouse
allow_nondeterministic_mutations. El adaptador lo habilita automáticamente para sus propias sesiones siempre que sea posible. Cuando no puede habilitarse (por ejemplo, porque es de solo lectura para tu usuario de dbt), el comportamiento depende de cómo se haya elegido la estrategia: los modelos que dependen de la estrategia predeterminada recurren silenciosamente a la estrategia heredado, los modelos que configuran explícitamentedelete+insertomicrobatchfallan en tiempo de ejecución yuse_lw_deletes: trueen el perfil falla al establecer la conexión. - En casos muy poco frecuentes, el uso de
incremental_predicatesno deterministas podría provocar una condición de carrera en los elementos actualizados o eliminados. Para garantizar resultados coherentes, los predicados incrementales solo deben incluir subconsultas sobre datos que no se modificarán durante la materialización incremental.
La estrategia Microbatch (requiere dbt-core >= 1.9)
microbatch es una característica de dbt-core desde la versión 1.9, diseñada para gestionar de forma eficiente transformaciones de grandes volúmenes de datos de series temporales. En dbt-clickhouse, se basa en la estrategia incremental delete_insert existente y divide la carga incremental en lotes de series temporales predefinidos según las configuraciones del modelo event_time y batch_size.
Además de gestionar transformaciones de gran tamaño, microbatch permite:
- Reprocesar lotes fallidos.
- Detectar automáticamente la ejecución paralela de lotes.
- Eliminar la necesidad de lógica condicional compleja para la carga histórica.
Configuraciones disponibles de Microbatch
La estrategia Append
inserts_only en versiones anteriores de dbt-clickhouse. Este enfoque simplemente añade
filas nuevas a la relación existente.
Como resultado, las filas duplicadas no se eliminan y no hay ninguna tabla temporal ni intermedia. Es el enfoque más rápido
si se permiten duplicados
en los datos o si la consulta incremental los excluye mediante la cláusula/filtro WHERE.
La estrategia insert_overwrite (Experimental)
[IMPORTANT] Actualmente, la estrategia insert_overwrite no es totalmente funcional con materializaciones distribuidas.Realiza los siguientes pasos:
- Crea una tabla temporal de preparación con la misma estructura que la relación del modelo incremental:
CREATE TABLE <staging> AS <target>. - Inserta únicamente los registros nuevos (generados por
SELECT) en la tabla de preparación. - Reemplaza únicamente las particiones nuevas (presentes en la tabla de preparación) en la tabla de destino.
- Es más rápido que la estrategia predeterminada porque no copia la tabla completa.
- Es más seguro que otras estrategias porque no modifica la tabla original hasta que la operación INSERT se completa correctamente: en caso de fallo intermedio, la tabla original no se modifica.
- Aplica la buena práctica de ingeniería de datos de la “inmutabilidad de las particiones”, lo que simplifica el procesamiento incremental y paralelo de datos, las reversiones, etc.
partition_by esté definido en la configuración del modelo. Ignora cualquier otro
parámetro de la configuración del modelo específico de otras estrategias.
Materialización: materialized_view
materialized_view crea una vista materializada de ClickHouse que actúa como un disparador de inserción, transformando e insertando automáticamente nuevas filas de una tabla de origen en una tabla de destino. Esta es una de las materializaciones más potentes disponibles en dbt-clickhouse.
Dado su alcance, esta materialización tiene su propia página dedicada. Ve a la guía de vistas materializadas para consultar la documentación completa
Materialización: diccionario (experimental)
dbt run, el diccionario se reemplaza por la definición actual del modelo mediante CREATE OR REPLACE DICTIONARY.
Configuraciones
Ejemplo con una fuente de ClickHouse
Ejemplo con una fuente HTTP
source_type='http' (o la opción table), el SQL del modelo no se utiliza como fuente, pero dbt sigue requiriendo un cuerpo; use select 1 como marcador de posición:
Materialización: distributed_table (experimental)
- Crea una vista temporal con una consulta SQL para obtener la estructura correcta
- Crea tablas locales vacías a partir de la vista
- Crea una tabla distribuida a partir de las tablas locales.
- Los datos se insertan en la tabla distribuida, por lo que se distribuyen entre los segmentos sin duplicarse.
- Las consultas de dbt-clickhouse ahora incluyen automáticamente la configuración
insert_distributed_sync = 1para garantizar que las operaciones posteriores de materialización incremental se ejecuten correctamente. Esto podría hacer que algunas inserciones en tablas distribuidas se ejecuten más lentamente de lo esperado.
Ejemplo de modelo de tabla distribuida
Migraciones generadas
Configuraciones
materialización: distributed_incremental (experimental)
- La estrategia Append solo inserta datos en la tabla distribuida.
- La estrategia Delete+Insert crea una tabla temporal distribuida para trabajar con todos los datos en cada segmento.
- La estrategia predeterminada (heredada) crea tablas temporales e intermedias distribuidas por la misma razón.
Ejemplo de modelo incremental Distributed
Migraciones generadas
Instantánea
snapshots/<model_name>.sql:
Contratos y restricciones
CHECK sobre toda la tabla/modelo. No se admiten restricciones CHECK de clave primaria, clave foránea, únicas ni a nivel de columna.
(Consulta la documentación de ClickHouse sobre las claves primarias/de ORDER BY.)