S3 테이블 엔진

이 엔진은 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. 읽기 전용 모드에서 다음 와일드카드를 지원해요: *, **, ?, {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, deflate, brotli/br, xz/LZMA, zstd/zst, lz4, bz2, snappy. 선택 매개변수. 기본적으로 파일 확장자로 압축을 자동 감지해요. snappy의 경우 와이어 형식은 snappy_mode 설정(기본 basic)으로 선택돼요
partition_strategy – 옵션: wildcard 또는 hive. wildcard는 경로에 {_partition_id}가 필요하며, 파티션 키로 대체돼요. hive는 와일드카드를 허용하지 않고 경로를 테이블 루트로 간주하며, Snowflake ID를 파일명으로, 파일 형식을 확장자로 하는 Hive 스타일 파티션 디렉터리를 생성해요. 명시적 전략 없이 {_partition_id}가 있는 경로는 wildcard를 사용해요. 다른 glob이 있는 경로는 파티션 전략을 사용하지 않고 PARTITION BY를 무시해요. glob이 없는 경로는 file_like_engine_default_partition_strategy가 hive일 때 hive를 사용하고, 그렇지 않으면 파티션 전략을 사용하지 않아요
partition_columns_in_data_file - hive 파티션 전략에서만 사용돼요. ClickHouse에 파티션 컬럼이 데이터 파일에 쓰일 것으로 기대하는지 알려줘요. 기본값 false
storage_class_name - 옵션: STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER_IR, EXPRESS_ONEZONE. 즉시 검색이 가능한 S3 스토리지 클래스만 지원돼요 (GLACIER, DEEP_ARCHIVE 같은 아카이브 클래스는 지원되지 않음). 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;

구성 파일에서 캐시를 정의하는 두 가지 방법이 있어요.

clickhouse 구성 파일에 다음 섹션을 추가해요:

<clickhouse>
    <filesystem_caches>
        <cache_for_s3>
            <path>path to cache directory</path>
            <max_size>10Gi</max_size>
        </cache_for_s3>
    </filesystem_caches>
</clickhouse>

clickhouse storage_configuration 섹션에서 캐시 구성(따라서 캐시 스토리지)을 재사용해요. 여기에 설명됨

PARTITION BY

PARTITION BY — 선택. 대부분의 경우 파티션 키가 필요하지 않고, 필요하다 해도 일반적으로 월 단위보다 더 세밀한 파티션 키가 필요하지 않아요. 파티셔닝은 (ORDER BY 표현식과 대조적으로) 쿼리를 빠르게 하지 않아요. 너무 세밀한 파티셔닝을 사용하면 안 돼요. 클라이언트 식별자나 이름으로 데이터를 파티셔닝하지 마세요 (대신 클라이언트 식별자나 이름을 ORDER BY 표현식의 첫 컬럼으로 만들어요).

월 단위 파티셔닝에는 toYYYYMM(date_column) 표현식을 사용해요. 여기서 date_column은 Date 타입의 날짜 컬럼이에요. 여기서 파티션 이름은 "YYYYMM" 형식이에요.

파티션 전략

wildcard: 파일 경로의 {_partition_id} 와일드카드를 실제 파티션 키로 대체해요. 읽기는 지원되지 않아요. 경로에 {_partition_id}가 포함되면 기본으로 선택돼요. partition_strategy가 설정되지 않으면 다른 glob이 있는 경로는 파티션 전략을 사용하지 않고 PARTITION BY를 무시해요. glob이 없는 경로는 file_like_engine_default_partition_strategy가 hive일 때 hive를 사용하고, 그렇지 않으면 파티션 전략을 사용하지 않아요.

hive는 읽기와 쓰기를 위한 hive 스타일 파티셔닝을 구현해요. 읽기는 재귀 glob 패턴을 사용해 구현되며 SELECT * FROM s3('table_root/**.parquet')와 동일해요. 쓰기는 <prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)> 형식을 사용해 파일을 생성해요.

참고: hive 파티션 전략을 사용할 때 use_hive_partitioning 설정은 효과가 없어요.

hive 파티션 전략 예시:

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);

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);

select _path, * from t_03363_parquet;

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

파티션된 데이터 쿼리하기

이 예시는 ClickHouse와 MinIO를 통합하는 docker compose 레시피를 사용해요. 엔드포인트와 인증 값을 바꿔 S3로도 같은 쿼리를 재현할 수 있어요.

ENGINE 구성의 S3 엔드포인트가 S3 객체(파일명)의 일부로 매개변수 토큰 {_partition_id}를 사용하고, SELECT 쿼리가 그 결과 객체 이름(예: test_3.csv)을 선택한다는 점을 유의해요.

예시에서 보여주듯 파티션된 S3 테이블에서 조회하는 것은 현재 직접 지원되지 않지만, S3 테이블 함수를 사용해 개별 파티션을 조회해 수행할 수 있어요. S3에 파티션된 데이터를 쓰는 주요 사용 사례는 그 데이터를 다른 ClickHouse 시스템으로 전송하는 것을 가능하게 하는 것이에요 (예: 온프레미스 시스템에서 ClickHouse Cloud로 이동). ClickHouse 데이터셋은 종종 매우 크고 네트워크 신뢰성이 때로는 완벽하지 않으므로 데이터셋을 부분 집합으로 전송하는 것이 합리적이며, 그래서 파티션된 쓰기(partitioned writes)를 사용하는 거예요.

테이블 생성

CREATE TABLE p
(
    `column1` UInt32,
    `column2` UInt32,
    `column3` UInt32
)
ENGINE = S3(
           'http://minio:10000/clickhouse//test_{_partition_id}.csv',
           'minioadmin',
           'minioadminpassword',
           'CSV',
           partition_strategy='wildcard')
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 이상에서 기본적으로 비활성화돼요. 이 기능은 프로덕션 사용에 권장되지 않아요.

경로의 와일드카드

path 인자는 bash 스타일 와일드카드를 사용해 여러 파일을 지정할 수 있어요. 처리되는 파일은 존재해야 하고 전체 경로 패턴과 일치해야 해요. 파일 목록은 (CREATE 시점이 아닌) SELECT 중에 결정돼요.

* — /를 제외한 어떤 수의 문자(빈 문자열 포함)를 대체해요
** — /를 포함한 어떤 수의 문자(빈 문자열 포함)를 대체해요
? — 단일 문자를 대체해요
{some_string,another_string,yet_another_one} — 문자열 'some_string', 'another_string', 'yet_another_one' 중 하나를 대체해요
{N..M} — N에서 M까지(양쪽 경계 포함)의 어떤 수를 대체해요. N과 M은 앞에 0을 가질 수 있어요. 예: 000..078

{}가 있는 구조는 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 형식의 파일이 여러 개 있다고 가정해요.

여섯 파일 모두로 구성된 테이블을 만드는 방법은 여러 가지가 있어요.

파일 접미사 범위 지정:

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');

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');

두 폴더의 모든 파일 가져오기 (모든 파일이 쿼리에 설명된 형식과 스키마를 만족해야 함):

CREATE TABLE table_with_asterisk (name String, value UInt32)
    ENGINE = S3('https://clickhouse-public-datasets.s3.amazonaws.com/my-bucket/{some,another}_folder/*', 'CSV');

상대 URL 해석

s3_base 설정은 S3 엔진에서 상대 URL을 사용할 수 있게 해줘요. s3_base가 설정되고 경로에 스킴이 없으면 RFC 3986에 따라 기본 URL에 대해 해석돼요. 해석 규칙에 대한 전체 설명은 s3 table function docs를 참고해요. 해석된 URL은 저장된 테이블 정의에 구체화(materialize)되므로 테이블은 생성 후 s3_base 값에 의존하지 않아요.

SET s3_base = 'https://datasets-documentation.s3.eu-west-3.amazonaws.com/';
CREATE TABLE aapl_stock (Date Date, Open Float32, High Float32, Low Float32, Close Float32, Volume Float32, OpenInt Int32)
    ENGINE = S3('aapl_stock.csv', NOSIGN, 'CSVWithNames');

스토리지 설정

s3_truncate_on_insert - 삽입 전에 파일을 잘라낼 수 있게 해줘요. 기본 비활성화
s3_create_new_file_on_insert - 형식에 접미사가 있으면 각 삽입 시 새 파일을 만들 수 있게 해줘요. 기본 비활성화
s3_skip_empty_files - 읽는 동안 빈 파일을 건너뛸 수 있게 해줘요. 기본 활성화
s3_base - 엔진에 전달된 상대 URL을 해석하기 위한 기본 URL. 기본 비어 있음(비활성화)

S3 관련 설정

다음 설정은 쿼리 실행 전에 설정하거나 구성 파일에 넣을 수 있어요.

s3_max_single_part_upload_size — 단일 파트 업로드를 사용해 S3에 업로드할 객체의 최대 크기. 기본값은 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. 각 in-flight 파트는 첫 s3_upload_part_size_multiply_factor개 파트에 대해 s3_min_upload_part_size 크기의 버퍼를 갖고, 파일이 충분히 크면 더 많은 버퍼를 가져요. upload_part_size_multiply_factor 참고. 기본 설정으로 8G보다 작은 파일은 업로드된 한 파일이 320Mb 이하를 소비해요. 더 큰 파일에서는 소비가 더 커요

보안 고려: 악의적인 사용자가 임의의 S3 URL을 지정할 수 있다면 SSRF 공격을 피하기 위해 s3_max_redirects를 0으로 설정해야 해요. 또는 서버 구성에 remote_host_filter를 지정해야 해요.

엔드포인트 기반 설정

다음 설정은 주어진 엔드포인트(URL의 정확한 접두사와 일치)에 대해 구성 파일에서 지정할 수 있어요.

endpoint — 엔드포인트의 접두사를 지정해요. 필수
access_key_id와 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 암호화로 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, 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-T...der> -->
        <!-- <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를 가진 아카이브 파일이 여러 개 있다고 가정해요.

이 아카이브에서 데이터를 추출하는 것은 ::를 사용하면 가능해요. Glob은 url 부분과 :: 뒤의 부분(아카이브 내부 파일의 이름 담당) 둘 다에서 사용할 수 있어요.

SELECT *
FROM s3(
   'https://s3-us-west-1.amazonaws.com/umbrella-static/top-1m-2018-01-1{0..2}.csv.zip :: *.csv',
   NOSIGN
);

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')

선택적 external_id도 role_arn과 함께 제공할 수 있어요. 이는 AWS STS AssumeRole 호출의 ExternalId 매개변수로 전달되어, 역할의 신뢰 정책이 공유 비밀을 요구해 confused deputy problem을 완화할 수 있게 해줘요.

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', external_id = 'my-external-id'), 'CSV')

S3 테이블 엔진