메인 콘텐츠로 건너뛰기
이 엔진은 Amazon S3 생태계와의 통합을 제공합니다. HDFS 엔진과 유사하지만, S3 전용 기능을 제공합니다.

​
예시

CREATE TABLE s3_engine_table (name String, value UInt32)
    ENGINE=S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/test-data.csv.gz', 'CSV', 'gzip')
    SETTINGS input_format_with_names_use_header = 0;

INSERT INTO s3_engine_table VALUES ('one', 1), ('two', 2), ('three', 3);

SELECT * FROM s3_engine_table LIMIT 2;

┌─name─┬─value─┐
│ one  │     1 │
│ two  │     2 │
└──────┴───────┘

​
테이블 생성

CREATE TABLE s3_engine_table (name String, value UInt32)
    ENGINE = S3(path [, NOSIGN | aws_access_key_id, aws_secret_access_key,] format, [compression], [partition_strategy], [partition_columns_in_data_file], [extra_credentials])
    [PARTITION BY expr]
    [SETTINGS ...]

​
엔진 매개변수

  • path — 파일 경로를 포함한 버킷 URL입니다. readonly 모드에서는 다음 와일드카드를 지원합니다: *, **, ?, {abc,def}, {N..M}. 여기서 N, M은 숫자이고 'abc', 'def'는 문자열입니다. 자세한 내용은 아래를 참조하십시오.
  • NOSIGN - 자격 증명 대신 이 키워드를 지정하면 모든 요청이 서명되지 않습니다.
  • format — 파일의 포맷입니다.
  • aws_access_key_id, aws_secret_access_key - AWS 계정 사용자의 장기 자격 증명입니다. 이를 사용해 요청을 인증할 수 있습니다. 이 매개변수는 선택 사항입니다. 자격 증명을 지정하지 않으면 설정 파일의 값이 사용됩니다. 자세한 내용은 Using S3 for Data Storage를 참조하십시오.
  • compression — 압축 유형입니다. 지원되는 값: none, gzip/gz, brotli/br, xz/LZMA, zstd/zst. 이 매개변수는 선택 사항입니다. 기본적으로 파일 확장자를 기준으로 압축을 자동 감지합니다.
  • partition_strategy – 옵션: WILDCARD 또는 HIVE입니다. WILDCARD는 경로에 {_partition_id}가 있어야 하며, 이 값은 파티션 키로 대체됩니다. HIVE는 와일드카드를 허용하지 않으며, 경로를 테이블 루트로 간주하고, 파일 이름은 Snowflake ID, 확장자는 파일 포맷으로 하는 Hive 스타일의 파티션 디렉터리를 생성합니다. 기본값은 WILDCARD입니다.
  • partition_columns_in_data_file - HIVE 파티션 전략에서만 사용됩니다. 데이터 파일에 파티션 컬럼이 기록되어 있다고 ClickHouse가 예상할지 여부를 지정합니다. 기본값은 false입니다.
  • storage_class_name - 옵션: STANDARD 또는 INTELLIGENT_TIERING이며, AWS S3 Intelligent Tiering을 지정할 수 있습니다.
  • extra_credentials - 선택 사항입니다. ClickHouse Cloud에서 역할 기반 접근을 위한 role_arn을 전달하는 데 사용됩니다. 구성 단계는 Secure S3를 참조하십시오.

​
데이터 캐시

S3 테이블 엔진은 로컬 디스크에 데이터를 캐시하는 기능을 지원합니다. 파일 시스템 캐시 구성 옵션과 사용 방법은 이 섹션을 참조하십시오. 캐싱은 스토리지 객체의 경로와 ETag를 기준으로 이루어지므로 ClickHouse는 오래된 캐시 버전을 읽지 않습니다. 캐싱을 활성화하려면 filesystem_cache_name = '<name>' 및 enable_filesystem_cache = 1 설정을 사용하십시오. 
SELECT *
FROM s3('http://minio:10000/clickhouse//test_3.csv', 'minioadmin', 'minioadminpassword', 'CSV')
SETTINGS filesystem_cache_name = 'cache_for_s3', enable_filesystem_cache = 1;
설정 파일에서 cache를 정의하는 방법은 두 가지입니다.
  1. ClickHouse 설정 파일에 다음 섹션을 추가합니다.
<clickhouse>
    <filesystem_caches>
        <cache_for_s3>
            <path>캐시 디렉터리 경로</path>
            <max_size>10Gi</max_size>
        </cache_for_s3>
    </filesystem_caches>
</clickhouse>
  1. ClickHouse storage_configuration 섹션의 캐시 구성(따라서 캐시 스토리지도)을 재사용합니다. 여기에 설명되어 있습니다

​
PARTITION BY

PARTITION BY — 선택 사항입니다. 대부분의 경우 파티션 키는 필요하지 않으며, 필요하더라도 일반적으로 월 단위보다 더 세분화된 파티션 키는 필요하지 않습니다. 파티셔닝은 쿼리 속도를 높이지 않습니다(ORDER BY 표현식과는 다릅니다). 지나치게 세분화된 파티셔닝은 절대 사용하지 마십시오. 데이터를 클라이언트 식별자나 이름을 기준으로 파티셔닝하지 마십시오(대신 클라이언트 식별자 또는 이름을 ORDER BY 표현식의 첫 번째 컬럼으로 지정하십시오). 월별 파티셔닝에는 toYYYYMM(date_column) 표현식을 사용하십시오. 여기서 date_column은 Date 타입의 날짜 컬럼입니다. 이 경우 파티션 이름은 "YYYYMM" 포맷입니다.

​
파티션 전략

WILDCARD (기본값): 파일 경로의 {_partition_id} 와일드카드를 실제 파티션 키로 대체합니다. 읽기는 지원하지 않습니다. HIVE는 읽기 및 쓰기에 Hive 스타일 파티셔닝을 사용합니다. 읽기는 재귀적 glob pattern을 사용해 구현되며, 이는 SELECT * FROM s3('table_root/**.parquet')와 동일합니다. 쓰기는 다음 포맷으로 파일을 생성합니다: <prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>. 참고: HIVE 파티션 전략을 사용할 때 use_hive_partitioning 설정은 효과가 없습니다. HIVE 파티션 전략의 예시: 
arthur :) CREATE TABLE t_03363_parquet (year UInt16, country String, counter UInt8)
ENGINE = S3(s3_conn, filename = 't_03363_parquet', format = Parquet, partition_strategy='hive')
PARTITION BY (year, country);

arthur :) INSERT INTO t_03363_parquet VALUES
    (2022, 'USA', 1),
    (2022, 'Canada', 2),
    (2023, 'USA', 3),
    (2023, 'Mexico', 4),
    (2024, 'France', 5),
    (2024, 'Germany', 6),
    (2024, 'Germany', 7),
    (1999, 'Brazil', 8),
    (2100, 'Japan', 9),
    (2024, 'CN', 10),
    (2025, '', 11);

arthur :) select _path, * from t_03363_parquet;

    ┌─_path──────────────────────────────────────────────────────────────────────┬─year─┬─country─┬─counter─┐
 1. │ test/t_03363_parquet/year=2100/country=Japan/7329604473272971264.parquet   │ 2100 │ Japan   │       9 │
 2. │ test/t_03363_parquet/year=2024/country=France/7329604473323302912.parquet  │ 2024 │ France  │       5 │
 3. │ test/t_03363_parquet/year=2022/country=Canada/7329604473314914304.parquet  │ 2022 │ Canada  │       2 │
 4. │ test/t_03363_parquet/year=1999/country=Brazil/7329604473289748480.parquet  │ 1999 │ Brazil  │       8 │
 5. │ test/t_03363_parquet/year=2023/country=Mexico/7329604473293942784.parquet  │ 2023 │ Mexico  │       4 │
 6. │ test/t_03363_parquet/year=2023/country=USA/7329604473319108608.parquet     │ 2023 │ USA     │       3 │
 7. │ test/t_03363_parquet/year=2025/country=/7329604473327497216.parquet        │ 2025 │         │      11 │
 8. │ test/t_03363_parquet/year=2024/country=CN/7329604473310720000.parquet      │ 2024 │ CN      │      10 │
 9. │ test/t_03363_parquet/year=2022/country=USA/7329604473298137088.parquet     │ 2022 │ USA     │       1 │
10. │ test/t_03363_parquet/year=2024/country=Germany/7329604473306525696.parquet │ 2024 │ Germany │       6 │
11. │ test/t_03363_parquet/year=2024/country=Germany/7329604473306525696.parquet │ 2024 │ Germany │       7 │
    └────────────────────────────────────────────────────────────────────────────┴──────┴─────────┴─────────┘

​
파티션된 데이터 쿼리

이 예시에서는 ClickHouse와 MinIO를 통합하는 docker compose recipe를 사용합니다. 엔드포인트와 authentication 값을 바꾸면 S3를 사용해 동일한 쿼리를 재현할 수 있습니다. ENGINE 구성의 S3 엔드포인트는 S3 객체(파일 이름)의 일부로 매개변수 토큰 {_partition_id}를 사용합니다. 또한 SELECT 쿼리는 이렇게 생성된 객체 이름(예: test_3.csv)을 대상으로 조회합니다.
예시에서 보듯이, 파티션된 S3 테이블에 대한 쿼리는 현재 직접 지원되지 않지만, S3 테이블 함수를 사용해 개별 파티션을 쿼리하는 방식으로 수행할 수 있습니다.S3에 파티션된 데이터를 쓰는 주된 사용 사례는 해당 데이터를 다른 ClickHouse 시스템으로 전송할 수 있게 하는 것입니다(예: 온프레미스 시스템에서 ClickHouse Cloud로 이전하는 경우). ClickHouse 데이터셋은 대체로 매우 크고, 네트워크 신뢰성이 완벽하지 않은 경우도 있으므로 데이터셋을 부분 집합으로 나누어 전송하는 것이 합리적입니다. 따라서 파티션별 쓰기가 유용합니다.

​
테이블 생성

CREATE TABLE p
(
    `column1` UInt32,
    `column2` UInt32,
    `column3` UInt32
)
ENGINE = S3(
           'http://minio:10000/clickhouse//test_{_partition_id}.csv',
           'minioadmin',
           'minioadminpassword',
           'CSV')
PARTITION BY column3

​
데이터 삽입

INSERT INTO p VALUES (1, 2, 3), (3, 2, 1), (78, 43, 45)

​
파티션 3 조회

이 쿼리에서는 S3 테이블 함수를 사용합니다
SELECT *
FROM s3('http://minio:10000/clickhouse//test_3.csv', 'minioadmin', 'minioadminpassword', 'CSV')

┌─c1─┬─c2─┬─c3─┐
│  1 │  2 │  3 │
└────┴────┴────┘

​
파티션 1 조회

SELECT *
FROM s3('http://minio:10000/clickhouse//test_1.csv', 'minioadmin', 'minioadminpassword', 'CSV')

┌─c1─┬─c2─┬─c3─┐
│  3 │  2 │  1 │
└────┴────┴────┘

​
파티션 45에서 조회

SELECT *
FROM s3('http://minio:10000/clickhouse//test_45.csv', 'minioadmin', 'minioadminpassword', 'CSV')

┌─c1─┬─c2─┬─c3─┐
│ 78 │ 43 │ 45 │
└────┴────┴────┘

​
제한 사항

자연스럽게 Select * from p를 시도할 수 있지만, 앞서 언급했듯이 이 쿼리는 실패하므로 앞의 쿼리를 사용하십시오. 
SELECT * FROM p

Received exception from server (version 23.4.1):
Code: 48. DB::Exception: Received from localhost:9000. DB::Exception: Reading from a partitioned S3 storage is not implemented yet. (NOT_IMPLEMENTED)

​
데이터 삽입

행은 새 파일에만 삽입할 수 있습니다. 머지 사이클이나 파일 분할 작업은 지원되지 않습니다. 파일이 한 번 기록되면 이후 삽입은 실패합니다. 이를 방지하려면 s3_truncate_on_insert 및 s3_create_new_file_on_insert 설정을 사용할 수 있습니다. 자세한 내용은 여기를 참조하십시오.

​
가상 컬럼

  • _path — 파일 경로입니다. 유형: LowCardinality(String).
  • _file — 파일 이름입니다. 유형: LowCardinality(String).
  • _size — 파일 크기(바이트 단위)입니다. 유형: Nullable(UInt64). 크기를 알 수 없으면 값은 NULL입니다.
  • _time — 파일의 마지막 수정 시간입니다. 유형: Nullable(DateTime). 시간을 알 수 없으면 값은 NULL입니다.
  • _etag — 파일의 ETag입니다. 유형: LowCardinality(String). ETag를 알 수 없으면 값은 NULL입니다.
  • _tags — 파일의 태그입니다. 유형: Map(String, String). 태그가 없으면 값은 빈 맵 {}'입니다.
가상 컬럼에 대한 자세한 내용은 여기를 참조하십시오.

​
구현 세부 정보

  • 읽기와 쓰기는 병렬로 수행될 수 있습니다.
  • 다음은 지원되지 않습니다:
    • ALTER 및 SELECT...SAMPLE 작업
    • 인덱스
    • zero-copy 복제는 가능하지만 지원되지는 않습니다.
zero-copy 복제는 운영 환경용으로는 아직 준비되지 않았습니다ClickHouse 버전 22.8 이상에서는 zero-copy 복제가 기본적으로 비활성화되어 있습니다. 이 기능은 운영 환경에서 사용하지 않는 것이 좋습니다.

​
경로의 와일드카드

path 인수에는 bash와 유사한 와일드카드를 사용해 여러 파일을 지정할 수 있습니다. 처리할 파일은 실제로 존재해야 하며 전체 경로 패턴과 일치해야 합니다. 파일 목록은 CREATE 시점이 아니라 SELECT 시점에 결정됩니다.
  • * — 빈 문자열을 포함해 /를 제외한 임의 개수의 문자로 대체됩니다.
  • ** — 빈 문자열을 포함해 /를 포함한 임의 개수의 문자로 대체됩니다.
  • ? — 임의의 단일 문자로 대체됩니다.
  • {some_string,another_string,yet_another_one} — 'some_string', 'another_string', 'yet_another_one' 중 하나의 문자열로 대체됩니다.
  • {N..M} — N부터 M까지 범위의 임의의 숫자로 대체되며, 양 끝값을 포함합니다. N과 M 앞에는 000..078처럼 0이 올 수 있습니다.
{} 구문은 remote 테이블 함수와 유사합니다.
파일 목록에 앞에 0이 붙은 숫자 범위가 포함되어 있으면 각 자릿수별로 중괄호 구문을 따로 사용하거나 ?를 사용하십시오.
와일드카드 예시 1 file-000.csv, file-001.csv, … , file-999.csv라는 이름의 파일로 테이블을 생성합니다: 
CREATE TABLE big_table (name String, value UInt32)
    ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/my_folder/file-{000..999}.csv', 'CSV');
와일드카드를 사용한 예시 2 S3에 URI가 다음과 같은 CSV 형식의 파일이 여러 개 있다고 가정합니다: 이 6개 파일 모두로 구성된 테이블을 만드는 방법은 여러 가지가 있습니다:
  1. 파일 접미사의 범위를 지정합니다:
CREATE TABLE table_with_range (name String, value UInt32)
    ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/some_file_{1..3}', 'CSV');
  1. some_file_ 접두사가 붙은 모든 파일을 가져옵니다(두 폴더 모두에 이 접두사를 가진 추가 파일이 없어야 합니다):
CREATE TABLE table_with_question_mark (name String, value UInt32)
    ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/some_file_?', 'CSV');
  1. 두 폴더에 있는 모든 파일을 가져오십시오(모든 파일은 쿼리에서 설명한 포맷과 스키마를 충족해야 합니다):
CREATE TABLE table_with_asterisk (name String, value UInt32)
    ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/*', 'CSV');

​
스토리지 설정

  • s3_truncate_on_insert - 파일에 삽입하기 전에 해당 파일을 TRUNCATE할 수 있습니다. 기본값은 비활성화입니다.
  • s3_create_new_file_on_insert - 포맷에 suffix가 있으면 각 삽입 시 새 파일을 생성할 수 있습니다. 기본값은 비활성화입니다.
  • s3_skip_empty_files - 읽는 동안 빈 파일을 건너뛸 수 있습니다. 기본값은 활성화입니다.

​
S3 관련 설정

다음 설정은 쿼리 실행 전에 지정하거나 설정 파일에 넣을 수 있습니다.
  • s3_max_single_part_upload_size — S3에 싱글파트 업로드(singlepart upload)로 업로드할 객체의 최대 크기입니다. 기본값은 32Mb입니다.
  • s3_min_upload_part_size — S3 Multipart upload에서 멀티파트 업로드 시 업로드할 파트의 최소 크기입니다. 기본값은 16Mb입니다.
  • s3_max_redirects — 허용되는 S3 리디렉션 홉 수의 최댓값입니다. 기본값은 10입니다.
  • s3_single_read_retries — 단일 읽기 중 최대 재시도 횟수입니다. 기본값은 4입니다.
  • s3_max_put_rps — 스로틀링이 적용되기 전 초당 최대 PUT 요청 수입니다. 기본값은 0(무제한)입니다.
  • s3_max_put_burst — 초당 요청 수 제한에 도달하기 전에 동시에 실행할 수 있는 최대 요청 수입니다. 기본적으로(0 값) s3_max_put_rps와 같습니다.
  • s3_max_get_rps — 스로틀링이 적용되기 전 초당 최대 GET 요청 수입니다. 기본값은 0(무제한)입니다.
  • s3_max_get_burst — 초당 요청 수 제한에 도달하기 전에 동시에 실행할 수 있는 최대 요청 수입니다. 기본적으로(0 값) s3_max_get_rps와 같습니다.
  • s3_upload_part_size_multiply_factor - S3에 단일 쓰기를 수행할 때 s3_multiply_parts_count_threshold개의 파트가 업로드될 때마다 s3_min_upload_part_size에 이 계수를 곱합니다. 기본값은 2입니다.
  • s3_upload_part_size_multiply_parts_count_threshold - 이 개수만큼의 파트가 S3에 업로드될 때마다 s3_min_upload_part_size에 s3_upload_part_size_multiply_factor를 곱합니다. 기본값은 500입니다.
  • s3_max_inflight_parts_for_one_file - 하나의 객체에 대해 동시에 실행할 수 있는 PUT 요청 수를 제한합니다. 이 수는 제한하는 것이 좋습니다. 값 0은 무제한을 의미합니다. 기본값은 20입니다. 전송 중인 각 파트에는 처음 s3_upload_part_size_multiply_factor개의 파트까지 크기가 s3_min_upload_part_size인 버퍼(buffer)가 할당되며, 파일이 충분히 크면 더 커집니다. upload_part_size_multiply_factor를 참조하십시오. 기본 설정에서는 8G 미만의 파일 하나를 업로드할 때 파일당 최대 320Mb만 사용합니다. 더 큰 파일은 사용량이 더 커집니다.
보안 고려 사항: 악의적인 사용자가 임의의 S3 URL을 지정할 수 있다면 SSRF 공격을 방지하기 위해 s3_max_redirects를 0으로 설정해야 합니다. 또는 대안으로 서버 구성에서 remote_host_filter를 지정해야 합니다.

​
엔드포인트 기반 설정

다음 설정은 지정된 엔드포인트에 대해 설정 파일에서 지정할 수 있습니다(URL의 정확한 접두사와 일치하는 엔드포인트에 적용됨).
  • endpoint — 엔드포인트의 접두사를 지정합니다. 필수입니다.
  • access_key_id and secret_access_key — 지정된 엔드포인트에 사용할 자격 증명을 지정합니다. 선택 사항입니다.
  • use_environment_credentials — true로 설정하면 S3 클라이언트가 지정된 엔드포인트에 대해 환경 변수와 Amazon EC2 메타데이터에서 자격 증명을 가져오려고 시도합니다. 선택 사항이며, 기본값은 false입니다.
  • region — S3 리전 이름을 지정합니다. 선택 사항입니다.
  • use_insecure_imds_request — true로 설정하면 S3 클라이언트가 Amazon EC2 메타데이터에서 자격 증명을 가져오는 동안 안전하지 않은 IMDS 요청을 사용합니다. 선택 사항이며, 기본값은 false입니다.
  • expiration_window_seconds — 만료 기반 자격 증명의 만료 여부를 확인할 때 적용되는 유예 시간입니다. 선택 사항이며, 기본값은 120입니다.
  • no_sign_request - 모든 자격 증명을 무시하여 요청에 서명하지 않도록 합니다. 공개 버킷에 접근할 때 유용합니다.
  • header — 지정된 엔드포인트로 보내는 요청에 지정한 HTTP 헤더를 추가합니다. 선택 사항이며, 여러 번 지정할 수 있습니다.
  • access_header - 다른 소스에서 가져온 자격 증명이 없는 경우, 지정된 엔드포인트로 보내는 요청에 지정한 HTTP 헤더를 추가합니다.
  • server_side_encryption_customer_key_base64 — 지정하면 SSE-C 암호화가 적용된 S3 객체에 접근하는 데 필요한 헤더가 설정됩니다. 선택 사항입니다.
  • server_side_encryption_kms_key_id - 지정하면 SSE-KMS encryption이 적용된 S3 객체에 접근하는 데 필요한 헤더가 설정됩니다. 빈 문자열을 지정하면 AWS 관리형 S3 키가 사용됩니다. 선택 사항입니다.
  • server_side_encryption_kms_encryption_context - server_side_encryption_kms_key_id와 함께 지정하면 SSE-KMS용 지정된 암호화 컨텍스트 헤더가 설정됩니다. 선택 사항입니다.
  • server_side_encryption_kms_bucket_key_enabled - server_side_encryption_kms_key_id와 함께 지정하면 SSE-KMS용 S3 버킷 키를 활성화하는 헤더가 설정됩니다. 선택 사항이며, true 또는 false를 사용할 수 있습니다. 기본값은 지정되지 않음이며, 버킷 수준 설정을 따릅니다.
  • max_single_read_retries — 단일 읽기 중 최대 시도 횟수입니다. 기본값은 4입니다. 선택 사항입니다.
  • max_put_rps, max_put_burst, max_get_rps and max_get_burst - 쿼리별 설정 대신 특정 엔드포인트에 적용할 스로틀링 설정입니다(위 설명 참조). 선택 사항입니다.
예시: 
<s3>
    <endpoint-name>
        <endpoint>https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/</endpoint>
        <!-- <access_key_id>ACCESS_KEY_ID</access_key_id> -->
        <!-- <secret_access_key>SECRET_ACCESS_KEY</secret_access_key> -->
        <!-- <region>us-west-1</region> -->
        <!-- <use_environment_credentials>false</use_environment_credentials> -->
        <!-- <use_insecure_imds_request>false</use_insecure_imds_request> -->
        <!-- <expiration_window_seconds>120</expiration_window_seconds> -->
        <!-- <no_sign_request>false</no_sign_request> -->
        <!-- <header>Authorization: Bearer SOME-TOKEN</header> -->
        <!-- <server_side_encryption_customer_key_base64>BASE64-ENCODED-KEY</server_side_encryption_customer_key_base64> -->
        <!-- <server_side_encryption_kms_key_id>KMS_KEY_ID</server_side_encryption_kms_key_id> -->
        <!-- <server_side_encryption_kms_encryption_context>KMS_ENCRYPTION_CONTEXT</server_side_encryption_kms_encryption_context> -->
        <!-- <server_side_encryption_kms_bucket_key_enabled>true</server_side_encryption_kms_bucket_key_enabled> -->
        <!-- <max_single_read_retries>4</max_single_read_retries> -->
    </endpoint-name>
</s3>

​
아카이브 다루기

S3에 다음 URI를 가진 여러 아카이브 파일이 있다고 가정합니다. 이러한 아카이브에서 데이터를 추출하려면 ::를 사용할 수 있습니다. 글롭 패턴은 URL 부분과 :: 뒤의 부분(아카이브 내부 파일 이름을 지정하는 부분) 모두에 사용할 수 있습니다. 
SELECT *
FROM s3(
   'https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-1{0..2}.csv.zip :: *.csv'
);
ClickHouse는 세 가지 아카이브 포맷을 지원합니다: ZIP TAR 7Z ZIP 및 TAR 아카이브는 지원되는 모든 저장소 위치에서 액세스할 수 있지만, 7Z 아카이브는 ClickHouse가 설치된 로컬 파일 시스템에서만 읽을 수 있습니다.

​
공개 버킷에 액세스하기

ClickHouse는 여러 유형의 소스에서 자격 증명을 가져오려고 시도합니다. 이 때문에 공개된 일부 버킷에 액세스할 때 문제가 발생하여 클라이언트가 403 오류 코드를 반환할 수 있습니다. 이 문제는 NOSIGN 키워드를 사용하여 클라이언트가 모든 자격 증명을 무시하고 요청에 서명하지 않도록 하면 방지할 수 있습니다. 
CREATE TABLE big_table (name String, value UInt32)
    ENGINE = S3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv', NOSIGN, 'CSVWithNames');

​
성능 최적화

s3 함수의 성능을 최적화하는 방법에 대한 자세한 내용은 상세 가이드를 참조하십시오.

​
역할 기반 접근

ClickHouse Cloud에서는 액세스 키 대신 역할 기반 접근을 사용해 S3 인증을 수행할 수 있습니다. 구성 단계는 Secure S3를 참조하십시오. 구성이 완료되면 extra_credentials 매개변수를 통해 roleARN을 전달할 수 있습니다: 
CREATE TABLE my_s3_table(name String, value UInt32)
ENGINE = S3('https://my-bucket.s3.amazonaws.com/data/*.csv', extra_credentials(role_arn = 'arn:aws:iam::111111111111:role/ClickHouseAccessRole-001'), 'CSV')

​
관련 항목

마지막 수정일 2026년 6월 10일