Insertar datos en ClickHouse Cloud con clickhouse-client

Aprende a usar clickhouse-client para insertar datos desde archivos CSV y Parquet locales en un servicio de ClickHouse Cloud desde la línea de comandos.

Todas las guías de inicio rápido

Analítica en tiempo realData WarehousingObservabilidadIA/MLCloud

Requisitos previos

También deberías haber completado las siguientes guías de inicio rápido:

• Crea tu primer servicio de ClickHouse Cloud - necesitarás un servicio de ClickHouse Cloud en ejecución para insertar datos
• Obtén los datos de conexión de Cloud - necesitarás tu hostname, nombre de usuario y contraseña para conectarte

Lo que crearás

En esta guía de inicio rápido usarás clickhouse-client —el cliente oficial de ClickHouse CLI— para insertar datos desde un archivo CSV local en un servicio de ClickHouse Cloud. Instalarás clickhouse-client, prepararás un conjunto de datos de ejemplo, te conectarás a tu servicio de ClickHouse Cloud, crearás una tabla e insertarás datos desde tu equipo local. Al final, sabrás cómo usar clickhouse-client para cargar archivos locales en ClickHouse Cloud, en un flujo de trabajo compatible con CSV, Parquet, JSON y muchos otros formatos.

1. Instalar clickhouse-client

   clickhouse-client es la interfaz de línea de comandos oficial para conectarse a ClickHouse. Está incluido en el binario de ClickHouse.

   Instálalo con el instalador universal:

   curl https://clickhouse.com/ | sh
   

   Esto descarga la versión más reciente del binario clickhouse en tu directorio actual. Verifica la instalación:

   ./clickhouse client --version
   

   Deberías ver una salida que muestre el número de versión de ClickHouse, lo que confirma que clickhouse-client está listo para usarse.

2. Prepara un archivo CSV de ejemplo

   Crea un pequeño archivo CSV de ejemplo para que esta guía de inicio rápido sea autosuficiente. Ejecuta lo siguiente en tu terminal:

   cat <<'EOF' > sample_data.csv
   timestamp,event_type,user_id,duration_ms,status
   2024-01-15 10:30:00,page_view,1001,120,success
   2024-01-15 10:31:15,click,1002,45,success
   2024-01-15 10:32:00,page_view,1003,200,success
   2024-01-15 10:33:30,purchase,1001,1500,success
   2024-01-15 10:34:00,click,1004,60,error
   2024-01-15 10:35:45,page_view,1002,95,success
   2024-01-15 10:36:10,purchase,1005,2200,success
   2024-01-15 10:37:00,click,1003,30,success
   2024-01-15 10:38:20,page_view,1004,150,error
   2024-01-15 10:39:00,purchase,1002,1800,success
   EOF
   
3. Conéctate a tu servicio en Cloud

   Los siguientes comandos asumen que has exportado CLICKHOUSE_HOST, CLICKHOUSE_USER y CLICKHOUSE_PASSWORD como variables de entorno, tal como se describe en la guía de inicio rápido para obtener los detalles de conexión de tu servicio en Cloud. Si no lo has hecho, puedes sustituirlos directamente por tus valores.

   Prueba la conectividad ejecutando una consulta sencilla en tu servicio en Cloud:

   ./clickhouse client \
     --host $CLICKHOUSE_HOST \
     --port 9440 \
     --user $CLICKHOUSE_USER \
     --password $CLICKHOUSE_PASSWORD \
     --secure \
     -q "SELECT 1"
   

   Si la conexión se establece correctamente, verás 1 en la terminal. Si aparece un error de conexión, comprueba que tu servicio esté activo en la consola de Cloud y que tu hostname y contraseña sean correctos.

   El puerto 9440 es el puerto seguro del protocolo nativo de ClickHouse Cloud. La opción --secure habilita el cifrado TLS. Ambos son necesarios para todas las conexiones a Cloud.

4. Crear una tabla de destino e insertar datos

   Primero, crea una tabla en tu servicio de Cloud para recibir los datos:

   ./clickhouse client \
     --host $CLICKHOUSE_HOST \
     --port 9440 \
     --user $CLICKHOUSE_USER \
     --password $CLICKHOUSE_PASSWORD \
     --secure \
     -q "
       CREATE TABLE IF NOT EXISTS events (
         timestamp DateTime,
         event_type LowCardinality(String),
         user_id UInt32,
         duration_ms UInt32,
         status LowCardinality(String)
       )
       ENGINE = MergeTree
       ORDER BY (event_type, timestamp)
     "
   

   Ahora inserta los datos de tu archivo CSV local. Este es el paso clave: clickhouse-client lee el archivo desde stdin y lo envía al servicio remoto en streaming:

   ./clickhouse client \
     --host $CLICKHOUSE_HOST \
     --port 9440 \
     --user $CLICKHOUSE_USER \
     --password $CLICKHOUSE_PASSWORD \
     --secure \
     -q "INSERT INTO events FORMAT CSVWithNames" < sample_data.csv
   

   clickhouse-client envía el contenido del archivo CSV directamente a tu servicio de Cloud. El formato CSVWithNames indica a ClickHouse que la primera fila contiene los nombres de las columnas.

5. Verifica que se hayan insertado los datos

   Ejecuta una consulta en tu servicio de Cloud para confirmar que las filas se insertaron correctamente:

   ./clickhouse client \
     --host $CLICKHOUSE_HOST \
     --port 9440 \
     --user $CLICKHOUSE_USER \
     --password $CLICKHOUSE_PASSWORD \
     --secure \
     -q "SELECT count() FROM events"
   

   Deberías ver 10: el número de filas del CSV de muestra.

   Previsualiza los datos:

   ./clickhouse client \
     --host $CLICKHOUSE_HOST \
     --port 9440 \
     --user $CLICKHOUSE_USER \
     --password $CLICKHOUSE_PASSWORD \
     --secure \
     -q "SELECT * FROM events ORDER BY timestamp LIMIT 5"
   

   Este mismo flujo de trabajo funciona con Parquet, TSV, JSON, Avro, ORC y muchos otros formatos compatibles - solo cambia la cláusula FORMAT y pasa el archivo adecuado por la tubería.

Siguientes pasos

En esta guía de inicio rápido instalaste clickhouse-client, lo conectaste a un servicio de ClickHouse Cloud y lo usaste para cargar datos desde un archivo CSV local en Cloud. Este mismo enfoque funciona con Parquet, JSON y decenas de otros formatos.

A continuación, consulta estas guías de inicio rápido:

• Crea tu primera tabla MergeTree

O profundiza con la documentación de referencia:

• Referencia de clickhouse-client
• Formatos de entrada/salida compatibles

Todas las guías de inicio rápido