Referencia técnica - ClickHouse Documentation

Detalles de la configuración

Gestión de usuarios y roles

Considere no usar el usuario default; en su lugar, cree uno específico para usarlo únicamente con este destino de Fivetran. Los siguientes comandos, ejecutados con el usuario default, crearán un nuevo fivetran_user con los privilegios necesarios.

CREATE USER fivetran_user IDENTIFIED BY '<password>'; -- utiliza un generador de contraseñas seguro

GRANT CURRENT GRANTS ON *.* TO fivetran_user;

Además, puede revocar el acceso del fivetran_user a determinadas bases de datos. Por ejemplo, al ejecutar la siguiente sentencia, restringimos el acceso a la base de datos default:

REVOKE ALL ON default.* FROM fivetran_user;

Puede ejecutar estas sentencias en la consola SQL de ClickHouse.

Configuración avanzada

El destino de ClickHouse Cloud admite un archivo de configuración JSON opcional para casos de uso avanzados. Este archivo le permite ajustar con precisión el comportamiento del destino al anular la configuración predeterminada que controla los tamaños de lote, el paralelismo, los pools de conexiones y los tiempos de espera de las solicitudes.

Esta configuración es completamente opcional. Si no se carga ningún archivo, el destino usa valores predeterminados razonables que funcionan bien para la mayoría de los casos de uso.

El archivo debe ser un JSON válido y ajustarse al esquema que se describe a continuación. Si necesita modificar la configuración después de la configuración inicial, puede editar la configuración del destino en el dashboard de Fivetran y cargar un archivo actualizado. El archivo de configuración tiene una sección de nivel superior:

{
  "destination_configurations": { ... }
}

Dentro de ella, puede especificar las siguientes configuraciones que controlan el comportamiento interno del propio conector de destino de ClickHouse. Estas configuraciones afectan a cómo el conector procesa los datos antes de enviarlos a ClickHouse.

Configuración	Tipo	Predeterminado	Rango permitido	Descripción
`write_batch_size`	integer	`100000`	5,000 – 100,000	Número de filas por lote para las operaciones de inserción, actualización y reemplazo.
`select_batch_size`	integer	`1500`	200 – 1,500	Número de filas por lote para las consultas SELECT utilizadas durante las actualizaciones.
`mutation_batch_size`	integer	`1500`	200 – 1,500	Número de filas por lote para las mutaciones ALTER TABLE UPDATE en modo de historial. Redúzcalo si se están generando sentencias SQL grandes.
`hard_delete_batch_size`	integer	`1500`	200 – 1,500	Número de filas por lote para las operaciones de eliminación definitiva en sincronizaciones normales y en modo de historial. Redúzcalo si se están generando sentencias SQL grandes.

Todos los campos son opcionales. Si no se especifica un campo, se usa el valor predeterminado. Si un valor está fuera del rango permitido, el destino informará de un error durante la sincronización. Los campos desconocidos se ignoran silenciosamente (se registra una advertencia) y no causan errores, lo que permite la compatibilidad con versiones futuras cuando se añaden nuevas configuraciones. Ejemplo:

{
  "destination_configurations": {
    "write_batch_size": 50000,
    "select_batch_size": 200
  }
}

Asignación de conversión de tipos

El destino de ClickHouse de Fivetran asigna los tipos de datos de Fivetran a los tipos de ClickHouse de la siguiente manera:

Tipo de Fivetran	Tipo de ClickHouse
BOOLEAN	Bool
SHORT	Int16
INT	Int32
LONG	Int64
BIGDECIMAL	Decimal(P, S)
FLOAT	Float32
DOUBLE	Float64
LOCALDATE	Date32
LOCALDATETIME	DateTime64(0, ‘UTC’)
INSTANT	DateTime64(9, ‘UTC’)
STRING	String
LOCALTIME	String * **
BINARY	String *
XML	String *
JSON	String *

BINARY, XML, LOCALTIME y JSON se almacenan como String porque el tipo String de ClickHouse puede representar un conjunto arbitrario de bytes. El destino añade un comentario a la columna para indicar el tipo de dato original. El tipo de dato JSON de ClickHouse no se usa, ya que fue marcado como obsoleto y nunca se recomendó para uso en producción. ** NOTA: Incidencia para hacer seguimiento del soporte del tipo LOCALTIME: clickhouse-fivetran-destination #15.

Rangos de valores de fecha y hora

Las fuentes de Fivetran pueden enviar valores de fecha y hora en el intervalo 0001-01-01, 9999-12-31. Los tipos de fecha de ClickHouse Cloud tienen rangos más reducidos, por lo que los valores fuera del rango admitido se ajustan silenciosamente al límite más cercano:

Tipo de Fivetran	Tipo de ClickHouse Cloud	Valor mín.	Valor máx.
LOCALDATE	Date32	1900-01-01	2299-12-31
LOCALDATETIME	DateTime64(0, ‘UTC’)	1900-01-01 00:00:00	2262-04-11 23:47:16
INSTANT	DateTime64(9, ‘UTC’)	1900-01-01 00:00:00	2262-04-11 23:47:16

El límite superior de INSTANT es 2262-04-11 23:47:16 porque DateTime64(9) almacena nanosegundos desde la época Unix como int64, y 2^63 - 1 nanosegundos corresponde a esta fecha. ClickHouse admite DateTime64 con precisión <= 9 hasta 2299-12-31 23:59:59.
El límite superior de LOCALDATETIME también está limitado a 2262-04-11 23:47:16 debido a un error conocido en el driver de Go para ClickHouse, donde se llama a time.Time.UnixNano() para todas las precisiones de DateTime64 antes del escalado, lo que provoca un overflow de int64 para fechas posteriores a 2262 incluso con precisión 0.

Tablas de destino

El destino de ClickHouse Cloud usa el motor de tipo Replacing de la familia SharedMergeTree (específicamente, SharedReplacingMergeTree), con control de versiones mediante la columna _fivetran_synced. Cada columna, excepto las claves primarias (de ordenación) y las columnas de metadatos de Fivetran, se crea como Nullable(T), donde T es un tipo de ClickHouse Cloud basado en la asignación de tipos de datos. La estructura de la tabla varía según el modo de sincronización configurado para el conector: eliminación lógica (predeterminado) o modo de historial (SCD Type 2).

Modo de eliminación lógica

En el modo de eliminación lógica, cada tabla de destino incluye las siguientes columnas de metadatos:

Columna	Tipo	Descripción
`_fivetran_synced`	`DateTime64(9, 'UTC')`	Marca temporal de la sincronización del registro por parte de Fivetran. Se usa como columna de versión para `SharedReplacingMergeTree`.
`_fivetran_deleted`	`Bool`	Marcador de eliminación lógica. Se establece en `true` cuando se elimina el registro de origen.
`_fivetran_id`	`String`	Identificador único generado automáticamente. Solo está presente cuando la tabla de origen no tiene claves primarias.

Una única clave primaria en la tabla de origen

Por ejemplo, la tabla de origen users tiene como clave primaria la columna id (INT) y una columna normal name (STRING). La tabla de destino se definirá de la siguiente manera:

CREATE TABLE `users`
(
    `id`                Int32,
    `name`              Nullable(String),
    `_fivetran_synced`  DateTime64(9, 'UTC'),
    `_fivetran_deleted` Bool
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY id
SETTINGS index_granularity = 8192

En este caso, la columna id se utiliza como clave de ordenación de la tabla.

Múltiples claves primarias en la tabla de origen

Si la tabla de origen tiene varias claves primarias, se usan en el orden en que aparecen en la definición de la tabla de origen de Fivetran. Por ejemplo, hay una tabla de origen items con las columnas de clave primaria id (INT) y name (STRING), además de una columna adicional normal description (STRING). La tabla de destino se definirá de la siguiente manera:

CREATE TABLE `items`
(
    `id`                Int32,
    `name`              String,
    `description`       Nullable(String),
    `_fivetran_synced`  DateTime64(9, 'UTC'),
    `_fivetran_deleted` Bool
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (id, name)
SETTINGS index_granularity = 8192

En este caso, las columnas id y name se seleccionan como claves de ordenación de la tabla.

Sin claves primarias en la tabla de origen

Si la tabla de origen no tiene claves primarias, Fivetran añadirá un identificador único en forma de columna _fivetran_id. Considere una tabla events que en el origen solo tiene las columnas event (STRING) y timestamp (LOCALDATETIME). La tabla de destino en ese caso es la siguiente:

CREATE TABLE events
(
    `event`             Nullable(String),
    `timestamp`         Nullable(DateTime),
    `_fivetran_id`      String,
    `_fivetran_synced`  DateTime64(9, 'UTC'),
    `_fivetran_deleted` Bool
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY _fivetran_id
SETTINGS index_granularity = 8192

Dado que _fivetran_id es único y no hay otras opciones de clave primaria, se utiliza como clave de ordenación para la tabla.

Modo de historial (SCD Type 2)

Cuando el modo de historial está habilitado, el destino conserva todas las versiones de cada registro en lugar de sobrescribir los valores anteriores. Esto implementa Slowly Changing Dimension Type 2 (SCD Type 2), manteniendo un registro de auditoría completo de todos los cambios. En el modo de historial, cada tabla de destino incluye las siguientes columnas de metadatos:

Columna	Tipo	Descripción
`_fivetran_synced`	`DateTime64(9, 'UTC')`	Marca temporal de cuándo Fivetran sincronizó el registro. Se utiliza como columna de versión para `SharedReplacingMergeTree`.
`_fivetran_start`	`DateTime64(9, 'UTC')`	Marca temporal de cuándo esta versión del registro pasó a estar activa. Forma parte de la clave de ordenación de la tabla.
`_fivetran_end`	`Nullable(DateTime64(9, 'UTC'))`	Marca temporal de cuándo esta versión fue reemplazada. Se establece en `2262-04-11 23:47:16` para los registros activos actualmente.
`_fivetran_active`	`Nullable(Bool)`	Indica si esta es la versión activa actual del registro.
`_fivetran_id`	`String`	Identificador único generado automáticamente. Solo está presente cuando la tabla de origen no tiene claves primarias.

La columna _fivetran_start siempre se incluye en la cláusula ORDER BY como último elemento de la clave de ordenación compuesta. Esto permite que varias versiones del mismo registro (con distintas horas de inicio) coexistan en la tabla. Cuando se actualiza un registro:

El valor de _fivetran_end de la versión anterior se establece en el valor de _fivetran_start de la nueva versión menos un nanosegundo, y _fivetran_active se establece en false.
La nueva versión se inserta con _fivetran_active establecido en true y _fivetran_end establecido en 2262-04-11 23:47:16.000000000 (el valor máximo de DateTime64(9)).

Una única clave primaria en la tabla de origen

Por ejemplo, la tabla de origen users tiene una columna de clave primaria id (INT) y columnas regulares name (STRING) y status (STRING). La tabla de destino en modo de historial se definirá de la siguiente manera:

CREATE TABLE `users`
(
    `id`               Int32,
    `name`             Nullable(String),
    `status`           Nullable(String),
    `_fivetran_synced` DateTime64(9, 'UTC'),
    `_fivetran_start`  DateTime64(9, 'UTC'),
    `_fivetran_end`    Nullable(DateTime64(9, 'UTC')),
    `_fivetran_active` Nullable(Bool)
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (id, _fivetran_start)
SETTINGS index_granularity = 8192

En este caso, id y _fivetran_start forman la clave de ordenación compuesta. Tras unas cuantas sincronizaciones, la tabla podría contener los siguientes datos:

id	name	status	_fivetran_start	_fivetran_end	_fivetran_active
1	name 1	TODO	2025-11-10 20:57:00.000000000	2025-11-11 20:56:59.999000000	false
1	name 11	TODO	2025-11-11 20:57:00.000000000	2262-04-11 23:47:16.000000000	true
2	name 2	TODO	2025-11-10 20:57:00.000000000	2262-04-11 23:47:16.000000000	true

El registro id=1 tiene dos versiones: la original (name 1, inactiva) y la actualizada (name 11, activa). El registro id=2 tiene solo una versión, que está activa actualmente.

Múltiples claves primarias en la tabla de origen

Si la tabla de origen tiene varias claves primarias, todas se incluyen en el ORDER BY, junto con _fivetran_start como último elemento. Por ejemplo, la tabla de origen items tiene las columnas de clave primaria id (INT) y name (STRING), además de una columna adicional normal description (STRING). La tabla de destino en modo de historial se definirá de la siguiente manera:

CREATE TABLE `items`
(
    `id`               Int32,
    `name`             String,
    `description`      Nullable(String),
    `_fivetran_synced` DateTime64(9, 'UTC'),
    `_fivetran_start`  DateTime64(9, 'UTC'),
    `_fivetran_end`    Nullable(DateTime64(9, 'UTC')),
    `_fivetran_active` Nullable(Bool)
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (id, name, _fivetran_start)
SETTINGS index_granularity = 8192

En este caso, id, name y _fivetran_start forman la clave de ordenación compuesta.

Sin claves primarias en la tabla de origen

Si la tabla de origen no tiene claves primarias, Fivetran añadirá un identificador único como columna _fivetran_id, y _fivetran_start se añade a la clave de ordenación. Considere una tabla events que solo tiene las columnas event (STRING) y timestamp (LOCALDATETIME) en el origen. La tabla de destino en modo de historial es la siguiente:

CREATE TABLE events
(
    `event`            Nullable(String),
    `timestamp`        Nullable(DateTime),
    `_fivetran_id`     String,
    `_fivetran_synced` DateTime64(9, 'UTC'),
    `_fivetran_start`  DateTime64(9, 'UTC'),
    `_fivetran_end`    Nullable(DateTime64(9, 'UTC')),
    `_fivetran_active` Nullable(Bool)
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (_fivetran_id, _fivetran_start)
SETTINGS index_granularity = 8192

Dado que _fivetran_id y _fivetran_start constituyen la clave de ordenación compuesta.

Seleccionar la versión más reciente de los datos sin duplicados

SharedReplacingMergeTree realiza la deduplicación de datos en segundo plano solo durante los merges, en un momento desconocido. Sin embargo, es posible seleccionar ad hoc la versión más reciente de los datos sin duplicados con la palabra clave FINAL:

SELECT *
FROM example FINAL
LIMIT 1000 

Consulta la sección optimización de consultas de lectura” de la guía de solución de problemas para obtener consejos sobre optimización de consultas.

Reintentos ante fallos de red

El destino de ClickHouse Cloud reintenta los errores de red transitorios mediante un algoritmo de backoff exponencial. Esto es seguro incluso cuando el destino inserta los datos, ya que cualquier posible duplicado es gestionado por el motor de tabla SharedReplacingMergeTree.

​Detalles de la configuración

​Gestión de usuarios y roles

​Configuración avanzada

​Asignación de conversión de tipos

​Rangos de valores de fecha y hora

​Tablas de destino

​Modo de eliminación lógica

​Una única clave primaria en la tabla de origen

​Múltiples claves primarias en la tabla de origen

​Sin claves primarias en la tabla de origen

​Modo de historial (SCD Type 2)

​Una única clave primaria en la tabla de origen

​Múltiples claves primarias en la tabla de origen

​Sin claves primarias en la tabla de origen

​Seleccionar la versión más reciente de los datos sin duplicados

​Reintentos ante fallos de red

Detalles de la configuración

Gestión de usuarios y roles

Configuración avanzada

Asignación de conversión de tipos

Rangos de valores de fecha y hora

Tablas de destino

Modo de eliminación lógica

Una única clave primaria en la tabla de origen

Múltiples claves primarias en la tabla de origen

Sin claves primarias en la tabla de origen

Modo de historial (SCD Type 2)

Una única clave primaria en la tabla de origen

Múltiples claves primarias en la tabla de origen

Sin claves primarias en la tabla de origen

Seleccionar la versión más reciente de los datos sin duplicados

Reintentos ante fallos de red