clickhouse-client로 ClickHouse Cloud에 데이터 삽입

명령줄에서 clickhouse-client를 사용하여 로컬 CSV 및 Parquet 파일의 데이터를 ClickHouse Cloud 서비스에 삽입하는 방법을 알아봅니다.

모든 빠른 시작

실시간 분석데이터 웨어하우징관측성AI/MLCloud

사전 요구 사항

다음 빠른 시작도 완료해야 합니다:

• 첫 번째 Cloud 서비스 만들기 - 데이터를 삽입하려면 실행 중인 ClickHouse Cloud 서비스가 필요합니다
• Cloud 연결 정보 확인하기 - 연결하려면 호스트명, 사용자 이름, 비밀번호가 필요합니다

구축할 내용

이 quickstart에서는 공식 ClickHouse CLI 클라이언트인 clickhouse-client를 사용해 로컬 CSV 파일의 데이터를 ClickHouse Cloud 서비스에 삽입합니다. clickhouse-client를 설치하고, 샘플 데이터셋을 준비하고, Cloud 서비스에 연결한 다음, 테이블을 생성하고 로컬 머신에서 데이터를 삽입합니다. 이 과정을 마치면 clickhouse-client를 사용해 로컬 파일을 ClickHouse Cloud에 로드하는 방법을 익히게 됩니다. 이 워크플로는 CSV, Parquet, JSON을 비롯한 다양한 포맷에서 사용할 수 있습니다.

1. clickhouse-client 설치

   clickhouse-client는 ClickHouse에 연결하는 공식 CLI입니다. ClickHouse 바이너리에 포함되어 있습니다.

   범용 설치 프로그램을 사용해 설치합니다:

   curl https://clickhouse.com/ | sh
   

   이렇게 하면 최신 clickhouse 바이너리가 현재 디렉터리에 다운로드됩니다. 설치를 확인하십시오:

   ./clickhouse client --version
   

   ClickHouse 버전 번호가 표시되면 clickhouse-client를 사용할 준비가 되었음을 확인할 수 있습니다.

2. 샘플 CSV 파일 준비

   이 quickstart만으로 진행할 수 있도록 작은 샘플 CSV 파일을 만듭니다. 터미널에서 다음을 실행하세요:

   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. Cloud 서비스에 연결

   아래 명령은 Cloud 연결 세부 정보 확인 빠른 시작에 설명된 대로 CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD를 환경 변수로 내보내 두었다고 가정합니다. 아직 그렇게 하지 않았다면 해당 값을 직접 사용해 대체할 수 있습니다.

   간단한 쿼리를 실행해 Cloud 서비스 연결을 테스트합니다:

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

   연결에 성공하면 터미널에 1이 출력됩니다. 연결 오류가 발생하면 Cloud Console에서 서비스가 실행 중인지, 호스트명과 비밀번호가 올바른지 확인하세요.

   포트 9440은 ClickHouse Cloud의 보안 네이티브 프로토콜 포트입니다. --secure 플래그는 TLS 암호화를 활성화합니다. 이는 모든 Cloud 연결에 필요합니다.

4. 대상 테이블 생성 및 데이터 삽입

   먼저, 데이터를 받을 테이블을 Cloud 서비스에 생성하세요:

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

   이제 로컬 CSV 파일의 데이터를 삽입합니다. 이것이 핵심 단계입니다. clickhouse-client는 stdin에서 파일을 읽어 원격 서비스로 스트리밍합니다:

   ./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는 CSV 파일의 내용을 Cloud 서비스로 직접 전송합니다. CSVWithNames 포맷은 첫 번째 행에 컬럼 헤더가 들어 있음을 ClickHouse에 알려줍니다.

5. 데이터가 삽입되었는지 확인

   행이 정상적으로 들어왔는지 확인하려면 Cloud 서비스에 쿼리하십시오:

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

   10이 표시되어야 합니다. 이는 샘플 CSV의 행 수입니다.

   데이터를 미리 확인합니다:

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

   이 동일한 워크플로는 Parquet, TSV, JSON, Avro, ORC 및 그 밖의 여러 지원 포맷에도 사용할 수 있습니다. FORMAT 절만 변경하고 적절한 파일을 파이프로 넘기면 됩니다.

다음 단계

이 빠른 시작에서는 clickhouse-client를 설치하고, 이를 ClickHouse Cloud 서비스에 연결한 다음, 로컬 CSV 파일의 데이터를 Cloud로 스트리밍했습니다. 이와 동일한 방식으로 Parquet, JSON 및 그 밖의 수십 가지 포맷도 사용할 수 있습니다.

다음 빠른 시작도 확인하세요:

• 첫 번째 MergeTree 테이블 만들기

또는 참고 문서를 통해 더 자세히 알아보세요:

• clickhouse-client 참고
• 지원되는 입력/출력 포맷

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

모든 빠른 시작