La ingestión eficiente de datos es la base de las implementaciones de ClickHouse de alto rendimiento. Seleccionar la estrategia de inserción adecuada puede afectar drásticamente al rendimiento, el coste y la fiabilidad. Esta sección describe las prácticas recomendadas, las ventajas e inconvenientes y las opciones de configuración para ayudarle a tomar la decisión correcta para su carga de trabajo.
Inserciones sincrónicas por defecto
Utilice inserciones sincrónicas si puede agrupar los datos en lotes en el clienteSi no es posible, consulte Inserciones asincrónicas a continuación. Inserciones por lotes en modo síncrono
Independientemente del tamaño de las inserciones, recomendamos mantener el número de consultas de inserción en torno a una consulta de inserción por segundo. El motivo de esta recomendación es que las partes creadas se fusionan en segundo plano en partes más grandes (para optimizar los datos para las consultas de lectura), y enviar demasiadas consultas de inserción por segundo puede dar lugar a situaciones en las que la fusión en segundo plano no pueda seguir el ritmo del número de partes nuevas. No obstante, puede usar una frecuencia mayor de consultas de inserción por segundo cuando utilice inserciones asíncronas (consulte Inserciones asíncronas). Garantizar reintentos idempotentes
- La inserción se realizó correctamente, pero el cliente nunca recibió una confirmación debido a una interrupción de red.
- La inserción falló en el servidor y se agotó el tiempo de espera.
En ambos casos, es seguro reintentar la inserción, siempre que el contenido y el orden del lote se mantengan idénticos. Por este motivo, es fundamental que los clientes reintenten de forma consistente, sin modificar ni reordenar los datos.
Elige el destino de inserción adecuado
- Insertar directamente en una tabla MergeTree o ReplicatedMergeTree. Esta es la opción más eficiente cuando el cliente puede realizar balanceo de carga entre segmentos. Con
internal_replication = true, ClickHouse se encarga de la replicación de forma transparente.
- Insertar en una tabla distribuida. Esto permite a los clientes enviar datos a cualquier nodo y dejar que ClickHouse los reenvíe al segmento correcto. Es más sencillo, pero ligeramente menos eficiente debido al paso adicional de reenvío. Sigue siendo recomendable usar
internal_replication = true.
En ClickHouse Cloud, todos los nodos leen y escriben en un único segmento. Las inserciones se equilibran automáticamente entre nodos. Puedes enviar las inserciones directamente al endpoint expuesto.
Elegir el formato de entrada adecuado es crucial para una ingestión de datos eficiente en ClickHouse. Con más de 70 formatos compatibles, seleccionar la opción de mayor rendimiento puede afectar significativamente la velocidad de inserción, el uso de CPU y memoria, y la eficiencia general del sistema.
Aunque la flexibilidad es útil para la ingeniería de datos y las importaciones basadas en archivos, las aplicaciones deben priorizar los formatos orientados al rendimiento:
- formato Native (recomendado): El más eficiente. Orientado a columnas, con un análisis mínimo requerido en el servidor. Se usa de forma predeterminada en los clientes de Go y Python.
- RowBinary: Formato eficiente basado en filas, ideal si la transformación a formato columnar es difícil del lado del cliente. Lo utiliza el cliente de Java.
- JSONEachRow: Fácil de usar, pero costoso de analizar. Adecuado para casos de uso de bajo volumen o integraciones rápidas.
La compresión desempeña un papel fundamental para reducir la sobrecarga de red, acelerar las inserciones y disminuir los costos de almacenamiento en ClickHouse. Si se utiliza de forma eficaz, mejora el rendimiento de la ingestión sin requerir cambios en el formato de los datos ni en el esquema.
Comprimir los datos de inserción reduce el tamaño de la carga útil que se envía por la red, lo que minimiza el uso de ancho de banda y acelera la transmisión.
En las inserciones, la compresión es especialmente eficaz cuando se utiliza con el formato Native, que ya se ajusta al modelo interno de almacenamiento columnar de ClickHouse. En esta configuración, el servidor puede descomprimir y almacenar los datos directamente de forma eficiente, con una transformación mínima.
Usa LZ4 por velocidad y ZSTD por relación de compresión
- LZ4: Rápido y ligero. Reduce significativamente el tamaño de los datos con una sobrecarga mínima de CPU, lo que lo hace ideal para inserciones de alto rendimiento y lo convierte en la opción predeterminada en la mayoría de los clientes de ClickHouse.
- ZSTD: Ofrece una mayor relación de compresión, pero consume más CPU. Es útil cuando los costes de transferencia de red son altos, como en escenarios entre regiones o entre proveedores Cloud, aunque aumenta ligeramente el consumo de cómputo del lado del cliente y el tiempo de descompresión en el servidor.
Práctica recomendada: usa LZ4, salvo que tengas un ancho de banda limitado o costes de salida de datos; en ese caso, considera ZSTD.
En las pruebas del benchmark FastFormats, las inserciones Native comprimidas con LZ4 redujeron el tamaño de los datos en más de un 50 %, lo que redujo el tiempo de ingestión de 150 s a 131 s para un conjunto de datos de 5.6 GiB. Al cambiar a ZSTD, ese mismo conjunto de datos se comprimió hasta 1.69 GiB, pero aumentó ligeramente el tiempo de procesamiento en el servidor. La compresión reduce el uso de recursos
Ordenar previamente si el costo es bajo
No se recomienda enviar muchos lotes pequeños en modo síncrono, ya que esto provoca la creación de muchas partes. Esto dará lugar a un rendimiento deficiente de las consultas y a errores de “too many part”. async_insert.
Las inserciones asíncronas son compatibles tanto con las interfaces HTTP como con native TCP.
Cuando están habilitadas (async_insert = 1), las inserciones se almacenan en búfer y solo se escriben en disco una vez que se cumple una de las condiciones de vaciado:
El primer umbral que se alcanza desencadena el vaciado.
Este proceso de agrupación por lotes es invisible para los clientes y ayuda a ClickHouse a fusionar de forma eficiente el tráfico de inserción procedente de múltiples fuentes. Sin embargo, hasta que no se produce un vaciado, los datos no pueden consultarse. Es importante destacar que existen múltiples búferes por combinación de forma de inserción y configuración y que, en los clusters, los búferes se mantienen por nodo, lo que permite un control detallado en entornos multiinquilino. Por lo demás, la mecánica de inserción es idéntica a la descrita para las inserciones síncronas.
Elegir un modo de retorno
wait_for_async_insert.
Cuando se establece en 1 (el valor predeterminado), ClickHouse solo confirma la inserción después de que los datos se hayan vaciado correctamente en disco. Esto garantiza sólidas garantías de durabilidad y simplifica el manejo de errores: si algo sale mal durante el vaciado, el error se devuelve al cliente. Este modo se recomienda para la mayoría de los escenarios de producción, especialmente cuando los fallos de inserción deben rastrearse de forma fiable.
Los benchmarks muestran que escala bien con la concurrencia, tanto si ejecuta 200 como 500 clientes, gracias a las inserciones adaptativas y a un comportamiento estable en la creación de partes.
Configurar wait_for_async_insert = 0 habilita el modo “fire-and-forget”. En este caso, el servidor confirma la inserción en cuanto los datos se almacenan en el búfer, sin esperar a que lleguen al almacenamiento.
Esto ofrece inserciones de latencia ultrabaja y máximo rendimiento, ideal para datos de alta velocidad y baja criticidad. Sin embargo, esto implica concesiones: no hay garantía de que los datos se persistan, los errores solo aparecen durante el vaciado y no existe una cola dead-letter para las inserciones fallidas; para rastrear fallos es necesario inspeccionar los registros del servidor y las tablas del sistema posteriormente. Use este modo solo si su workload puede tolerar la pérdida de datos.
Los benchmarks también demuestran una reducción sustancial de partes y un menor uso de CPU cuando los vaciados del búfer son poco frecuentes (por ejemplo, cada 30 segundos), pero el riesgo de fallo silencioso sigue presente.
Nuestra recomendación firme es usar async_insert=1,wait_for_async_insert=1 si utiliza inserciones asíncronas. Usar wait_for_async_insert=0 es muy arriesgado porque es posible que su cliente de INSERT no detecte si hay errores, y además puede provocar una posible sobrecarga si su cliente sigue escribiendo rápidamente en una situación en la que el ClickHouse server necesita ralentizar las escrituras y crear cierta contrapresión para garantizar la fiabilidad del service.
Inserciones asíncronas adaptativas
async_insert_use_adaptive_busy_timeout). En lugar de un intervalo de vaciado fijo, el tiempo de espera se ajusta dinámicamente entre un mínimo (async_insert_busy_timeout_min_ms, 50 ms de forma predeterminada) y un máximo (async_insert_busy_timeout_max_ms, 200 ms de forma predeterminada o 1000 ms en Cloud) en función de la tasa de llegada de datos.
Cuando los datos llegan con frecuencia, el tiempo de espera se mantiene más cerca del mínimo para vaciar antes y reducir la latencia de extremo a extremo. Cuando los datos son dispersos, aumenta hacia el máximo para acumular lotes más grandes. Esto resulta especialmente útil en el modo predeterminado (wait_for_async_insert=1), donde un tiempo de espera fijo alto obligaría a los clientes a quedar bloqueados durante todo el intervalo incluso cuando los datos ya están listos para vaciarse.
La validación del esquema y el análisis de los datos se realizan durante el vaciado del búfer, no cuando se recibe el insert. Si alguna fila de una consulta de inserción tiene un error de análisis o de tipo, no se vacía ningún dato de esa consulta — se rechaza toda la carga útil de la consulta. En el modo predeterminado (wait_for_async_insert=1), el error se devuelve al cliente. En el modo fire-and-forget, los errores se escriben en los logs del servidor y en la tabla system.asynchronous_inserts.
Cada vaciado crea al menos una parte por cada valor distinto de la clave de partición en el búfer. Incluso en tablas sin clave de partición, un solo vaciado puede producir varias partes si los datos almacenados en el búfer superan max_insert_block_size (valor predeterminado: ~1 millón de filas).
Aunque uses inserciones asíncronas, puedes seguir encontrándote con errores de “too many parts” si la clave de particionamiento tiene una cardinalidad alta. Deduplicación y fiabilidad
Habilitación de inserciones asíncronas
-
Habilitación de inserciones asíncronas a nivel de usuario. Este ejemplo usa el usuario
default; si crea un usuario distinto, sustituya ese nombre de usuario:
ALTER USER default SETTINGS async_insert = 1
-
Puede especificar la configuración de las inserciones asíncronas mediante la cláusula SETTINGS de las consultas de inserción:
INSERT INTO YourTable SETTINGS async_insert=1, wait_for_async_insert=1 VALUES (...)
-
También puede especificar la configuración de las inserciones asíncronas como parámetros de conexión al usar un cliente de ClickHouse para un lenguaje de programación.
Por ejemplo, así puede hacerlo dentro de una connection string de JDBC cuando usa el JDBC driver de Java de ClickHouse para conectarse a ClickHouse Cloud:
"jdbc:ch://HOST.clickhouse.cloud:8443/?user=default&password=PASSWORD&ssl=true&custom_http_params=async_insert=1,wait_for_async_insert=1"
Las inserciones asíncronas no se aplican a las consultas INSERT INTO ... SELECT. Cuando la inserción contiene una cláusula SELECT, la consulta siempre se ejecuta de forma síncrona, independientemente de la configuración de async_insert.
Vaciado de búferes al apagar
SYSTEM FLUSH ASYNC INSERT QUEUE
Comparación con las tablas Buffer
- No se requieren cambios de DDL. Las inserciones asíncronas son transparentes: se habilita una configuración, no se crean tablas adicionales.
- Búfer por forma. Las inserciones asíncronas mantienen búferes independientes para cada combinación única de forma de consulta y configuración, lo que permite aplicar políticas de vaciado granulares. Las tablas Buffer usan un único búfer por tabla de destino.
- Durabilidad. En el modo predeterminado (
wait_for_async_insert=1), los datos se confirman en disco antes de que el cliente reciba la confirmación. Las tablas Buffer funcionan en modo fire-and-forget: los datos almacenados en el búfer se pierden si se produce un fallo.
- Comportamiento del clúster. En los clústeres, los búferes de inserción asíncrona se mantienen por nodo. Las tablas Buffer requieren crearse explícitamente en cada nodo.
Elija una interfaz: HTTP o nativa
Content-Encoding: lz4), la compresión se aplica a toda la carga útil en lugar de a bloques de datos individuales. Esta interfaz suele preferirse en entornos donde la simplicidad del protocolo, el balanceo de carga o una amplia compatibilidad de formatos son más importantes que el rendimiento puro.
Para obtener una descripción más detallada de estas interfaces, consulte aquí. 
