S3 세션 설정

S3 세션 설정 (s3_*)

이 페이지에서는 S3 처리와 관련된 다양한 s3_* 세션 설정들을 다뤄요. 기준 URL, 연결/요청 시간 초과, 업로드 파트 크기, 파일 생성·절단 동작, URI 스타일 등을 설정해요. 이 설정들은 system.settings 테이블에서 확인할 수 있으며 ClickHouse 소스에서 자동 생성돼요.

출처: 문서

본문

이 설정들은 system.settings에서 확인할 수 있으며 소스에서 자동 생성돼요.

s3_base

s3 테이블 함수와 S3 테이블 엔진, 그리고 그 구성을 공유하는 테이블 함수(s3Cluster, gcs, oss)에서 상대 URL을 해석하는 데 사용되는 기준 URL이에요. 설정되면 스킴이 없는 URL은 RFC 3986에 따라 url_base와 같은 규칙으로 s3_base에 대해 해석돼요. 이미 스킴을 가진 URL은 그대로 사용돼요. 예를 들어 s3_base가 s3://clickhouse-public-datasets/이면, s3('hits_compatible/hits.csv')는 s3://clickhouse-public-datasets/hits_compatible/hits.csv를 읽어요. 기준 URL은 s3 테이블 함수가 받아들이는 어떤 형태든 사용할 수 있어요(예: s3://bucket/, https://bucket.s3.amazonaws.com/, https://endpoint/bucket/).

s3_check_objects_after_upload

S3에 업로드한 각 객체를 head 요청으로 확인해 업로드가 성공했는지 확인해요.

s3_connect_timeout_ms

s3 디스크의 호스트에 대한 연결 시간 초과예요.

s3_create_new_file_on_insert

s3 엔진 테이블에서 각 삽입 시 새 파일을 만들지 여부를 활성화 또는 비활성화해요. 활성화하면 각 삽입 시 다음과 같은 패턴의 키로 새 S3 객체가 생성돼요: 초기: data.Parquet.gz -> data.1.Parquet.gz -> data.2.Parquet.gz 등. 가능한 값:

0 — INSERT 쿼리가 새 파일을 만들거나, 파일이 이미 있고 s3_truncate_on_insert가 설정되지 않았으면 실패해요.
1 — INSERT 쿼리가 s3_truncate_on_insert가 설정되지 않은 경우 접미사(두 번째부터)를 사용해 각 삽입 시 새 파일을 만들어요.

자세한 내용은 여기를 참고하세요.

s3_ignore_file_doesnt_exist

특정 키를 읽을 때 파일이 존재하지 않아도 그 부재를 무시해요. 가능한 값:

1 — SELECT가 빈 결과를 반환해요.
0 — SELECT가 예외를 던져요.

s3_list_object_keys_size

ListObject 요청에 의해 한 번에 반환될 수 있는 최대 파일 수예요.

s3_min_upload_part_size

S3로 멀티파트 업로드 동안 업로드할 파트의 최소 크기예요.

s3_path_filter_limit

쿼리 필터에서 추출할 수 있는 _path 값의 최대 개수로, glob 나열 대신 파일 반복에 사용되요. 0은 비활성화를 의미해요.

s3_request_timeout_ms

S3에서/로 데이터를 보내고 받는 유휴 시간 초과예요. 단일 TCP 읽기 또는 쓰기 호출이 그만큼 블로킹되면 실패해요.

s3_skip_empty_files

S3 엔진 테이블에서 빈 파일을 건너뛰는 것을 활성화 또는 비활성화해요. 가능한 값:

0 — 빈 파일이 요청된 형식과 호환되지 않으면 SELECT가 예외를 던져요.
1 — SELECT가 빈 파일에 대해 빈 결과를 반환해요.

s3_slow_all_threads_after_network_error

true로 설정하면 같은 백업 엔드포인트에 S3 요청을 실행하는 모든 스레드가, 단일 s3 요청이 재시도 가능한 네트워크 오류(예: 소켓 시간 초과)를 만난 후 느려져요. false로 설정하면 각 스레드가 다른 스레드와 독립적으로 S3 요청 백오프를 처리해요.

s3_strict_upload_part_size

S3로 멀티파트 업로드 동안 업로드할 파트의 정확한 크기예요(일부 구현은 가변 크기 파트를 지원하지 않아요).

s3_throw_on_zero_files_match

ListObjects 요청이 어떤 파일과도 일치할 수 없으면 오류를 던져요.

s3_truncate_on_insert

s3 엔진 테이블에서 삽입 전 절단(truncate)을 활성화 또는 비활성화해요. 비활성화하면 S3 객체가 이미 존재할 때 삽입 시도 시 예외가 발생해요. 가능한 값:

0 — INSERT 쿼리가 새 파일을 만들거나, 파일이 이미 있고 s3_create_new_file_on_insert가 설정되지 않았으면 실패해요.
1 — INSERT 쿼리가 파일의 기존 내용을 새 데이터로 대체해요.