> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

<a href="/ko/get-started/quickstarts/home"><Badge size="lg" color="gray" icon="arrow-left">모든 빠른 시작</Badge></a>

<div className="mt-2 flex flex-wrap gap-2">
  <Badge size="lg" color="blue">실시간 분석</Badge>
  <Badge size="lg" color="blue">데이터 웨어하우징</Badge>
  <Badge size="lg" color="blue">관측성</Badge>
  <Badge size="lg" color="blue">AI/ML</Badge>
  <Badge size="lg" color="orange">Cloud</Badge>
</div>

<div id="prerequisites">
  ## 사전 요구 사항
</div>

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

* [첫 번째 Cloud 서비스 만들기](/ko/get-started/quickstarts/create-your-first-service-on-cloud) - 데이터를 삽입하려면 실행 중인 ClickHouse Cloud 서비스가 필요합니다
* [Cloud 연결 정보 확인하기](/ko/get-started/quickstarts/obtain-your-cloud-connection-details) - 연결하려면 호스트명, 사용자 이름, 비밀번호가 필요합니다

<div id="what-youll-build">
  ## 구축할 내용
</div>

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

<Steps titleSize="h3">
  <Step>
    ### clickhouse-client 설치

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

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

    ```bash theme={null}
    curl https://clickhouse.com/ | sh
    ```

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

    ```bash theme={null}
    ./clickhouse client --version
    ```

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

  <Step>
    ### 샘플 CSV 파일 준비

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

    ```bash theme={null}
    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
    ```
  </Step>

  <Step>
    ### Cloud 서비스에 연결

    아래 명령은 [Cloud 연결 세부 정보 확인](/ko/get-started/quickstarts/obtain-your-cloud-connection-details) 빠른 시작에 설명된 대로 `CLICKHOUSE_HOST`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`를 환경 변수로 내보내 두었다고 가정합니다. 아직 그렇게 하지 않았다면 해당 값을 직접 사용해 대체할 수 있습니다.

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

    ```bash theme={null}
    ./clickhouse client \
      --host $CLICKHOUSE_HOST \
      --port 9440 \
      --user $CLICKHOUSE_USER \
      --password $CLICKHOUSE_PASSWORD \
      --secure \
      -q "SELECT 1"
    ```

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

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

  <Step>
    ### 대상 테이블 생성 및 데이터 삽입

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

    ```bash theme={null}
    ./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에서 파일을 읽어 원격 서비스로 스트리밍합니다:

    ```bash theme={null}
    ./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에 알려줍니다.
  </Step>

  <Step>
    ### 데이터가 삽입되었는지 확인

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

    ```bash theme={null}
    ./clickhouse client \
      --host $CLICKHOUSE_HOST \
      --port 9440 \
      --user $CLICKHOUSE_USER \
      --password $CLICKHOUSE_PASSWORD \
      --secure \
      -q "SELECT count() FROM events"
    ```

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

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

    ```bash theme={null}
    ./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 및 그 밖의 여러 [지원 포맷](/ko/reference/formats)에도 사용할 수 있습니다. `FORMAT` 절만 변경하고 적절한 파일을 파이프로 넘기면 됩니다.
  </Step>
</Steps>

## 다음 단계

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

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

* [첫 번째 MergeTree 테이블 만들기](/ko/get-started/quickstarts/create-your-first-mergetree-table)

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

* [clickhouse-client 참고](/ko/concepts/features/interfaces/cli)
* [지원되는 입력/출력 포맷](/ko/reference/formats)

<Frame caption="Check out the ClickHouse academy for on-demand and live training">
  <a href="https://learn.clickhouse.com/" target="_blank">
    <img src="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/Y9kcWM6RbYppspJn/images/academy.png?fit=max&auto=format&n=Y9kcWM6RbYppspJn&q=85&s=d842bc871e006c08da3026a8a09e1d61" alt="ClickHouse Academy — Master ClickHouse with expert-designed training for every skill level" width="560" noZoom data-path="images/academy.png" />
  </a>
</Frame>

<div className="mt-8">
  <a href="/ko/get-started/quickstarts/home"><Badge size="lg" color="gray" icon="arrow-left">모든 빠른 시작</Badge></a>
</div>