Inserir dados no ClickHouse Cloud usando clickhouse-client

clickhouse-client é a CLI oficial para se conectar ao ClickHouse. Ele já vem incluído no binário do ClickHouse.

Instale-o usando o instalador universal:

curl https://clickhouse.com/ | sh

Isso baixa o binário mais recente do clickhouse no diretório atual. Verifique a instalação:

./clickhouse client --version

Você deverá ver uma saída exibindo o número da versão do ClickHouse, confirmando que o clickhouse-client está pronto para uso.

Crie um pequeno arquivo CSV de exemplo para que este guia de início rápido possa ser seguido sem depender de outros arquivos. Execute o seguinte no 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

Os comandos abaixo presumem que você exportou CLICKHOUSE_HOST, CLICKHOUSE_USER e CLICKHOUSE_PASSWORD como variáveis de ambiente, conforme descrito no guia de início rápido Obtain your Cloud connection details. Caso contrário, você pode substituí-los diretamente pelos seus próprios valores.

Teste a conectividade executando uma consulta simples no seu serviço Cloud:

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

Se a conexão for bem-sucedida, 1 aparecerá no terminal. Se ocorrer um erro de conexão, verifique se o serviço está ativo no console do Cloud e se o hostname e a senha estão corretos.

Primeiro, crie uma tabela no seu serviço Cloud para receber os dados:

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

Agora insira os dados do seu arquivo CSV local. Este é o passo-chave - o clickhouse-client lê o arquivo pela stdin e o envia por streaming para o serviço remoto:

./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 envia o conteúdo do arquivo CSV diretamente para o seu serviço na Cloud. O formato CSVWithNames informa ao ClickHouse que a primeira linha contém os nomes das colunas.

Execute uma consulta no seu serviço Cloud para confirmar se as linhas foram recebidas:

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

Você verá 10 — o número de linhas no CSV de exemplo.

Visualize os dados:

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

Esse mesmo fluxo de trabalho funciona com Parquet, TSV, JSON, Avro, ORC e muitos outros formatos suportados - basta alterar a cláusula FORMAT e enviar o arquivo apropriado via pipe.