Errores comunes
La prueba de privilegios falló o las operaciones fallan por problemas de permisos
ALTER, CREATE DATABASE, CREATE TABLE, INSERT y SELECT sobre *.* (todas las bases de datos y tablas).
La comprobación de privilegios consulta
system.grants y solo tiene en cuenta los privilegios otorgados directamente al usuario. No detecta los privilegios asignados mediante un rol de ClickHouse. Consulta la sección privilegios basados en roles para obtener más información.Error al esperar a que finalicen todas las mutaciones
ALTER TABLE ... UPDATE o ALTER TABLE ... DELETE, pero el conector agotó el tiempo de espera mientras esperaba a que se completara en todas las réplicas. La parte de la “causa inicial” del error suele contener el error original de ClickHouse (normalmente el código 341, “Unfinished”).
Esto puede ocurrir cuando:
- El clúster de ClickHouse Cloud está sometido a una carga elevada.
- Uno o más nodos dejaron de estar disponibles durante la ejecución de la mutación.
- Comprobar el progreso de la mutación: Ejecute la siguiente consulta para comprobar si hay mutaciones pendientes:
- Comprobar el estado del clúster: Asegúrese de que todos los nodos estén en buen estado.
- Esperar y reintentar: Las mutaciones terminan completándose una vez que el clúster vuelve a estar en buen estado. Fivetran reintentará la sincronización automáticamente.
Error de incompatibilidad de columnas
- Se añadieron o eliminaron columnas manualmente en la tabla de ClickHouse.
- Un cambio de esquema en el origen no se propagó correctamente.
- Recuerde no modificar manualmente las tablas gestionadas por Fivetran. Consulte buenas prácticas.
- Restaure la columna: Si sabe qué tipo debería tener la columna, restáurela al tipo esperado tomando como referencia la correspondencia de transformación de tipos.
- Vuelva a sincronizar la tabla: En el panel de Fivetran, active una resincronización histórica para la tabla afectada.
- Eliminar y volver a crear: Como último recurso, elimine la tabla de destino y deje que Fivetran la vuelva a crear durante la siguiente sincronización.
El AST es demasiado grande (código 168)
mutation_batch_size y hard_delete_batch_size en el archivo de configuración avanzada. Ambos tienen como valor predeterminado 1500 y aceptan valores entre 200 y 1500.
Límite de memoria superado / OOM (código 241)
- Reducir
write_batch_size: Intenta bajarlo a 50,000 para tablas grandes. - Reducir la carga de la base de datos: Comprueba la carga del servicio de ClickHouse Cloud para ver si está sobrecargado.
- Ampliar el servicio de ClickHouse Cloud para disponer de más memoria.
EOF inesperado / Error de conexión
FAILURE_WITH_TASK sin stack trace en los logs de Fivetran.
Causa:
- La lista de acceso IP no está configurada para permitir el tráfico de Fivetran.
- Problemas transitorios de red entre Fivetran y ClickHouse Cloud.
- Datos de origen corruptos o no válidos que provocan que el conector de destino falle.
- Comprobar la lista de acceso IP: En ClickHouse Cloud, ve a Settings > Security y añade las direcciones IP de Fivetran o permite el acceso desde cualquier origen.
- Reintentar: Las versiones recientes del conector reintentan automáticamente los errores EOF. Los errores esporádicos (1–2 al día) probablemente sean transitorios.
- Si el problema persiste: Abre un ticket de soporte con ClickHouse e indica la ventana de tiempo del error. Pide también al soporte de Fivetran que investigue la calidad de los datos de origen.
No se puede mapear el tipo UInt64
LONG a Int64, nunca a UInt64. Este error se produce cuando el tipo de una columna se modifica manualmente en una tabla gestionada por Fivetran.
Soluciones:
- No modifique manualmente los tipos de las columnas en las tablas gestionadas por Fivetran.
- Para solucionarlo: vuelva a cambiar la columna al tipo esperado (por ejemplo,
Int64) o elimine la tabla y vuelva a sincronizarla. - Para tipos personalizados: Cree una vista materializada sobre la tabla gestionada por Fivetran.
La tabla no tiene claves primarias
ORDER BY. Cuando el origen no tiene una clave primaria, Fivetran agrega _fivetran_id automáticamente. Este error se produce en casos excepcionales en los que el origen define una PK, pero los datos no la contienen.
Soluciones:
- Contacta con el soporte de Fivetran para investigar la canalización de origen.
- Comprueba el esquema de origen: Asegúrate de que las columnas de la clave primaria estén presentes en los datos.
Fallo en los privilegios basados en roles
user_name = NULL y role_name = 'my_role', por lo que esta comprobación no los detecta.
Solución:
Concede los privilegios directamente al usuario de Fivetran:
Buenas prácticas
Servicio de ClickHouse dedicado para Fivetran
- Servicio A (escritura): destino de Fivetran + otras herramientas de ingestión (ClickPipes, conectores de Kafka)
- Servicio B (lectura): herramientas de BI, dashboards, consultas ad hoc
Optimización de las consultas de lectura
SharedReplacingMergeTree para las tablas de destino de Fivetran, que es la versión del motor de tabla ReplacingMergeTree en ClickHouse Cloud. Las filas duplicadas con la misma clave primaria son normales: la deduplicación se produce de forma asíncrona durante las fusiones en segundo plano. En el momento de la lectura, debes tener cuidado para evitar devolver filas duplicadas, ya que es posible que algunas filas aún no se hayan deduplicado.
Usar la palabra clave FINAL es la forma más sencilla de evitar filas duplicadas, ya que fuerza la fusión, en el momento de la lectura, de cualquier fila que todavía no se haya deduplicado:
FINAL; por ejemplo, filtrando por las columnas clave mediante una condición WHERE. Para obtener más información, consulta la sección rendimiento de FINAL de la guía de ReplacingMergeTree.
Si esas optimizaciones no son suficientes, tienes otras opciones para evitar usar FINAL sin dejar de gestionar correctamente los duplicados:
- Si quieres consultar una columna numérica que siempre aumenta, puedes usar
max(the_column). - Si necesitas recuperar el valor más reciente de algunas columnas para una clave concreta, puedes usar
argMax(the_column, _fivetran_id).
Fivetran replica la clave primaria de la tabla de origen como la cláusula
ORDER BY de ClickHouse. Cuando la tabla de origen no tiene PK, _fivetran_id (un UUID) pasa a ser la clave de ordenación, lo que puede provocar un rendimiento deficiente en las consultas, ya que ClickHouse construye su índice primario disperso a partir de las columnas de ORDER BY.
Recomendaciones en este caso, si ninguna otra optimización es suficiente:
- Trate las tablas de Fivetran como tablas de staging sin procesar. No las consulte directamente para análisis.
- Si las consultas siguen sin ofrecer un rendimiento suficiente, use una vista materializada actualizable para crear una copia de la tabla con un
ORDER BYoptimizado para sus patrones de consulta. A diferencia de las vistas materializadas incrementales, las vistas materializadas actualizables vuelven a ejecutar la consulta completa según una programación, lo que gestiona correctamente las operacionesUPDATEyDELETEque Fivetran ejecuta durante las sincronizaciones:
Evite las vistas materializadas incrementales (no actualizables) en tablas gestionadas por Fivetran. Como Fivetran ejecuta operaciones
UPDATE y DELETE para mantener los datos sincronizados, las vistas materializadas incrementales no reflejarán estos cambios y contendrán datos obsoletos o incorrectos.No modifiques manualmente las tablas gestionadas por Fivetran
ALTER TABLE ... MODIFY COLUMN) en las tablas gestionadas por Fivetran. El conector espera el esquema que creó. Los cambios manuales pueden provocar errores de correspondencia de tipos y fallos por incompatibilidades de esquema.
Usa vistas materializadas para las transformaciones personalizadas.
Operaciones de depuración
- Consulte el
system.query_logde ClickHouse para detectar problemas del lado del servidor. - Solicite ayuda a Fivetran si los problemas son del lado del cliente.