Referencia técnica

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.

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.

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.

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
  }
}

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

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:

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

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

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

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.

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.

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.

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:

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

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:

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.

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.

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.

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.

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.