Inserir dados no ClickHouse Cloud usando clickhouse-client

Aprenda a usar o clickhouse-client para inserir dados de arquivos CSV e Parquet locais em um serviço do ClickHouse Cloud pela linha de comando.

Todos os guias de início rápido

Analytics em tempo realArmazenamento de dadosObservabilidadeAI/MLCloud

Pré-requisitos

Você também deve ter concluído os seguintes guias de início rápido:

• Crie seu primeiro serviço no Cloud - você precisará de um serviço do ClickHouse Cloud em execução para inserir dados
• Obtenha os detalhes de conexão do seu serviço no Cloud - você precisará do hostname, nome de usuário e senha para se conectar

O que você vai criar

Neste guia de início rápido, você usará o clickhouse-client — o cliente oficial de CLI do ClickHouse — para inserir dados de um arquivo CSV local em um serviço do ClickHouse Cloud. Você instalará o clickhouse-client, preparará um conjunto de dados de exemplo, se conectará ao seu serviço no Cloud, criará uma tabela e inserirá dados da sua máquina local. Ao final, você saberá como usar o clickhouse-client para carregar arquivos locais no ClickHouse Cloud, em um fluxo de trabalho compatível com CSV, Parquet, JSON e muitos outros formatos.

1. Instale o 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.

2. Prepare um arquivo CSV de exemplo

   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
   
3. Conecte-se ao seu serviço Cloud

   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.

   A porta 9440 é a porta segura do protocolo nativo do ClickHouse Cloud. A flag --secure habilita a criptografia TLS. Ambos são obrigatórios para todas as conexões com o Cloud.

4. Crie uma tabela de destino e insira dados

   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.

5. Verifique se os dados foram inseridos

   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.

Próximos passos

Neste guia de início rápido, você instalou o clickhouse-client, conectou-o a um serviço do ClickHouse Cloud e o usou para enviar dados de um arquivo CSV local para a Cloud. Essa mesma abordagem funciona com Parquet, JSON e dezenas de outros formatos.

Confira a seguir os próximos guias de início rápido:

• Crie sua primeira tabela MergeTree

Ou aprofunde-se na documentação de referência:

• Referência do clickhouse-client
• Formatos de entrada/saída compatíveis

Check out the ClickHouse academy for on-demand and live training

Todos os guias de início rápido