> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Cloud에 파일 업로드하기
> Cloud에 파일을 업로드하는 방법을 알아보세요
이 페이지에서는 [ClickHouse CLI](/ko/products/cloud/features/cli)(`clickhousectl`)를 사용해 명령줄에서 로컬 파일(예: CSV)을 ClickHouse Cloud 서비스의 테이블로 업로드하는 방법을 설명합니다. 이 과정은 콘솔의 파일 업로드 마법사와 동일한 방식으로, 파일의 스키마를 확인하고 대상 테이블을 생성한 뒤 Query API를 통해 HTTP로 파일을 삽입합니다. `clickhouse` binary나 서비스 password는 필요하지 않습니다.
사전 요구 사항
ClickHouse CLI를 설치합니다:
```bash theme={null}
curl https://clickhouse.com/cli | sh
```
또한 `jq`도 필요합니다.
쓰기 작업에는 [API Key 인증](/ko/products/cloud/features/admin-features/api/openapi)이 필요하며, OAuth 로그인은 읽기 전용입니다:
```bash theme={null}
clickhousectl cloud auth login --api-key --api-secret
```
`clickhousectl cloud auth status`로 확인하십시오. `read/write` 범위의 항목이 표시되어야 합니다.
서비스 선택
이 가이드는 이미 실행 중인 서비스가 있다고 가정합니다. 없다면 CLI로 서비스를 생성하는 방법을 설명하는 [Cloud 빠른 시작](/ko/get-started/setup/cloud)을 참조하십시오. 이름으로 서비스의 ID를 조회합니다:
```bash theme={null}
CH_ID=$(clickhousectl cloud service list --json \
| jq -r '.[] | select(.name=="my-service") | .id')
```
파일 준비하기
다음 텍스트가 `data.csv`라는 CSV 파일에 들어 있다고 가정합니다. 첫 번째 줄이 헤더 행이므로 알맞은 입력 형식은 `CSVWithNames`입니다:
```text title="data.csv" theme={null}
user_id,url,visited_at,duration_ms
101,https://clickhouse.com/docs,2026-08-14 09:15:32,4210
102,https://clickhouse.com/pricing,2026-08-14 09:16:01,1830
101,https://clickhouse.com/cloud,2026-08-14 09:17:45,2650
103,https://clickhouse.com/blog,2026-08-15 11:02:10,980
102,https://clickhouse.com/docs/cloud,2026-08-15 11:05:44,3120
```
스키마 확인하기
콘솔 마법사가 각 소스 필드의 추론된 유형을 보여주는 것과 같이, CLI에서는 파일 샘플을 인라인으로 포함한 [`format`](/ko/reference/functions/table-functions/format) 테이블 함수에 `DESCRIBE`를 실행하여 동일한 결과를 얻을 수 있습니다:
```bash theme={null}
clickhousectl cloud service query --id "$CH_ID" --format PrettyCompact \
--query "DESCRIBE format(CSVWithNames, '$(head -n 3 data.csv)')"
```
첫 번째 `query` 호출 시 해당 서비스에 대한 Query API 엔드포인트와 서비스 범위의 API Key가 자동으로 프로비저닝됩니다:
```text theme={null}
Provisioning Query API endpoint + key for service 'my-service'...
┌─name────────┬─type───────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
1. │ user_id │ Nullable(Int64) │ │ │ │ │ │
2. │ url │ Nullable(String) │ │ │ │ │ │
3. │ visited_at │ Nullable(DateTime) │ │ │ │ │ │
4. │ duration_ms │ Nullable(Int64) │ │ │ │ │ │
└─────────────┴────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
```
샘플은 SQL 문자열 리터럴에 삽입되므로 작은따옴표(single quotes)나 백슬래시가 포함되어서는 안 됩니다. 이러한 문자가 포함된 파일이라면 해당 문자를 이스케이프하거나 `CREATE TABLE`을 직접 작성하십시오.
테이블 생성
마법사의 "Configure table" 단계에서 제공하는 모든 기능, 즉 추론된 유형, nullable 여부, 기본값, 제외할 필드, 테이블 엔진, sorting key, 파티셔닝, primary key 표현식 조정은 여기서 단순한 [`CREATE TABLE`](/ko/reference/statements/create/table) 문에 해당합니다. 예를 들어 추론된 유형을 더 엄격하게 지정하고 sorting key를 선택하려면 다음과 같이 작성합니다:
```bash theme={null}
clickhousectl cloud service query --id "$CH_ID" \
--query "CREATE TABLE default.website_visits (
user_id UInt32,
url String,
visited_at DateTime,
duration_ms UInt32
) ENGINE = MergeTree
ORDER BY (user_id, visited_at)"
```
이 명령은 `OK`를 출력합니다. 대신 기존 테이블에 로드하려면 이 단계를 건너뛰십시오.
파일 업로드
`INSERT ... FORMAT`은 stdin에서 데이터를 읽으므로, 쿼리와 파일을 파이프로 함께 전달하십시오:
```bash theme={null}
printf 'INSERT INTO default.website_visits FORMAT CSVWithNames\n' | cat - data.csv \
| clickhousectl cloud service query --id "$CH_ID"
```
이 명령은 `OK`를 출력합니다.
**쿼리와 데이터를 함께 파이프로 전달하십시오**
`--query`로 `INSERT`를 전달하면서 파일을 stdin으로 리디렉션하거나 파이프로 넘기는 방식(`--query "INSERT ..." < data.csv`)은 동작하지 않습니다. `--query`는 stdin을 읽지 않으므로 데이터가 어디로도 전달되지 않습니다. CLI는 아무것도 삽입하지 않은 채 조용히 넘어가는 대신 이 조합 자체를 거부합니다. 즉, 종료 코드 `1`로 종료하고, 행을 삽입하지 않으며, 다음을 출력합니다:
```text theme={null}
Error: --query cannot be combined with SQL or data on stdin. The Query API sends one request body, so redirected data is never read. Pipe the statement and its data together on stdin instead: printf 'INSERT INTO t FORMAT CSV\n' | cat - data.csv | clickhousectl cloud service query --id . Or read a whole statement from stdin with --queries-file -.
```
위 예시처럼 쿼리와 데이터는 항상 하나의 스트림으로 묶어 stdin을 통해 전송하십시오. 실제로 데이터를 담고 있는 stdin만 `--query`와 충돌하므로, stdin이 터미널이 아닌 스크립트나 파이프라인에서 `--query`를 단독으로 사용하는 것은 여전히 정상 동작합니다.
행이 정상적으로 저장되었는지 확인하십시오:
```bash theme={null}
clickhousectl cloud service query --id "$CH_ID" --json \
--query "SELECT count() FROM default.website_visits"
```
```text theme={null}
{"count()":5}
```
```bash theme={null}
clickhousectl cloud service query --id "$CH_ID" --format PrettyCompact \
--query "SELECT * FROM default.website_visits ORDER BY visited_at"
```
```text theme={null}
┌─user_id─┬─url───────────────────────────────┬──────────visited_at─┬─duration_ms─┐
1. │ 101 │ https://clickhouse.com/docs │ 2026-08-14 09:15:32 │ 4210 │
2. │ 102 │ https://clickhouse.com/pricing │ 2026-08-14 09:16:01 │ 1830 │
3. │ 101 │ https://clickhouse.com/cloud │ 2026-08-14 09:17:45 │ 2650 │
4. │ 103 │ https://clickhouse.com/blog │ 2026-08-15 11:02:10 │ 980 │
5. │ 102 │ https://clickhouse.com/docs/cloud │ 2026-08-15 11:05:44 │ 3120 │
└─────────┴───────────────────────────────────┴─────────────────────┴─────────────┘
```
동일한 방식이 ClickHouse가 지원하는 모든 [입력 형식](/ko/reference/formats/index)에 그대로 적용됩니다. 여기에는 `CSV`, `JSONEachRow`, `TabSeparatedWithNames` 등 콘솔의 업로드 마법사가 지원하는 모든 포맷이 포함됩니다. 다른 포맷을 사용하려면 `DESCRIBE format(...)` 스키마 추론 단계와 `INSERT ... FORMAT` 문에서 포맷 이름을 동일하게 바꾸고, 해당 포맷에 맞는 샘플 파일을 사용하십시오(`TabSeparatedWithNames`에는 TSV 샘플, `JSONEachRow`에는 JSON 라인 샘플을 사용하는 식입니다). 예를 들어 TSV 파일의 업로드 단계는 다음과 같습니다.
```bash theme={null}
printf 'INSERT INTO default.website_visits FORMAT TabSeparatedWithNames\n' | cat - data.tsv \
| clickhousectl cloud service query --id "$CH_ID"
```
정리
테스트 목적으로 실행한 것이라면, 테이블을 삭제하여 가져온 데이터를 제거하십시오:
```bash theme={null}
clickhousectl cloud service query --id "$CH_ID" \
--query "DROP TABLE default.website_visits"
```