Insertar datos en ClickHouse Cloud con 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.

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

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.

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.

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.