데이터 저장용 외장 디스크(External Disks for Storing Data)

데이터 저장용 외장 디스크(External Disks for Storing Data)

ClickHouse에서 처리된 데이터는 보통 ClickHouse 서버가 실행되는 머신의 로컬 파일시스템에 저장됩니다. 이 문서에서는 S3, Azure Blob Storage 같은 외부 스토리지를 MergeTree 또는 Log 계열 테이블의 데이터 저장에 사용하도록 구성하는 방법과 관련 설정들을 설명할게요.

출처: 문서

본문

ClickHouse에서 처리된 데이터는 보통 ClickHouse 서버가 실행되는 머신의 로컬 파일시스템에 저장됩니다. 그러면 대용량 디스크가 필요하며 비쌀 수 있습니다. 데이터를 로컬에 저장하지 않기 위해 다양한 저장 옵션이 지원됩니다:

  1. Amazon S3 오브젝트 스토리지.
  2. Azure Blob Storage.
  3. 지원되지 않음: Hadoop 분산 파일 시스템 (HDFS)

ClickHouse는 또한 외부 테이블 엔진을 지원하는데, 이것은 이 페이지에서 설명하는 외부 저장 옵션과 다릅니다. 외부 테이블 엔진은 Parquet 같은 일반 파일 형식으로 저장된 데이터를 읽을 수 있게 하기 때문입니다. 이 페이지에서는 ClickHouse MergeTree 계열 또는 Log 계열 테이블의 저장 구성을 설명합니다.

  1. Amazon S3 디스크에 저장된 데이터로 작업하려면 S3 테이블 엔진을 사용하세요.
  2. Azure Blob Storage에 저장된 데이터로 작업하려면 AzureBlobStorage 테이블 엔진을 사용하세요.
  3. Hadoop 분산 파일 시스템(지원되지 않음)의 데이터로 작업하려면 HDFS 테이블 엔진을 사용하세요.

외부 스토리지 구성하기

MergeTree와 Log 계열 테이블 엔진은 각각 타입이 s3, azure_blob_storage, hdfs(지원 안 됨)인 디스크를 사용해 S3, AzureBlobStorage, HDFS(지원 안 됨)에 데이터를 저장할 수 있습니다.

s3 디스크 타입은 Alibaba Cloud Object Storage Service 같은 S3 호환 오브젝트 스토리지 제공자와도 사용할 수 있습니다. 제공자의 S3 호환 엔드포인트로 endpoint를 구성하고 제공자별 호환성 요구 사항을 고려하세요.

디스크 구성에는 다음이 필요합니다:

  1. s3, azure_blob_storage, hdfs(지원 안 됨), local_blob_storage, web 중 하나와 같은 type 섹션.
  2. 특정 외부 스토리지 타입의 구성.

24.1 clickhouse 버전부터 새 구성 옵션을 사용할 수 있습니다. 이는 다음을 지정해야 합니다:

  1. object_storage와 같은 type
  2. s3, azure_blob_storage(24.3부터는 그냥 azure), hdfs(지원 안 됨), local_blob_storage(24.3부터는 그냥 local), web 중 하나와 같은 object_storage_type.

선택적으로 metadata_type을 지정할 수 있습니다(기본적으로 local과 같음). 그러나 plain, web, 그리고 24.4부터는 plain_rewritable로도 설정할 수 있습니다. plain 메타데이터 타입의 사용은 plain 스토리지 섹션에서 설명되고, web 메타데이터 타입은 web 오브젝트 스토리지 타입에서만 사용할 수 있으며, local 메타데이터 타입은 메타데이터 파일을 로컬에 저장합니다(각 메타데이터 파일은 오브젝트 스토리지의 파일 매핑과 그것에 대한 추가 메타 정보를 포함합니다). 예를 들어:

<s3>
    <type>s3</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3>

는 다음 구성(버전 24.1부터)과 같습니다:

<s3>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>local</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3>

다음 구성:

<s3_plain>
    <type>s3_plain</type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

는 다음과 같습니다:

<s3_plain>
    <type>object_storage</type>
    <object_storage_type>s3</object_storage_type>
    <metadata_type>plain</metadata_type>
    <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
    <use_environment_credentials>1</use_environment_credentials>
</s3_plain>

전체 스토리지 구성의 예는 다음과 같습니다:

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>s3</type>
                <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
                <use_environment_credentials>1</use_environment_credentials>
            </s3>
        </disks>
        <policies>
            <s3>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3>
        </policies>
    </storage_configuration>
</clickhouse>

24.1 버전부터는 다음과 같이 보일 수도 있습니다:

<clickhouse>
    <storage_configuration>
        <disks>
            <s3>
                <type>object_storage</type>
                <object_storage_type>s3</object_storage_type>
                <metadata_type>local</metadata_type>
                <endpoint>https://s3.eu-west-1.amazonaws.com/clickhouse-eu-west-1.clickhouse.com/data/</endpoint>
                <use_environment_credentials>1</use_environment_credentials>
            </s3>
        </disks>
        <policies>
            <s3>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3>
        </policies>
    </storage_configuration>
</clickhouse>

특정 종류의 스토리지를 모든 MergeTree 테이블의 기본 옵션으로 만들려면 구성 파일에 다음 섹션을 추가하세요:

<clickhouse>
    <merge_tree>
        <storage_policy>s3</storage_policy>
    </merge_tree>
</clickhouse>

특정 테이블에 대해 특정 스토리지 정책을 구성하려면 테이블 생성 시 설정에서 정의할 수 있습니다:

CREATE TABLE test (a Int32, b String)
ENGINE = MergeTree() ORDER BY a
SETTINGS storage_policy = 's3';

storage_policy 대신 disk를 사용할 수도 있습니다. 이 경우 구성 파일에 storage_policy 섹션이 있을 필요가 없고 disk 섹션만으로 충분합니다.

CREATE TABLE test (a Int32, b String)
ENGINE = MergeTree() ORDER BY a
SETTINGS disk = 's3';

refresh_parts_interval과 table_disk

이 설정은 파츠가 외부에서 쓰여지고 메타데이터 발견이 스토리지에서 새로고침되어야 하는 비(非)Replicated MergeTree 테이블을 위한 것입니다. MergeTree 설정 refresh_parts_interval은 기본 스토리지에서 데이터 파츠 목록의 주기적 새로고침을 활성화합니다(예: 외부에 쓰여진 파츠를 수집하기 위해). 중요한 구분은 복제본 간 공유 메타데이터 vs 복제본 로컬 메타데이터(예: 복제본당 로컬 메타데이터를 가진 S3)입니다. 메타데이터가 공유될 때만 새 파츠가 모든 복제본에 보이게 됩니다. 오브젝트 스토리지를 사용한다고 해서 메타데이터가 공유된다는 뜻은 아닙니다.

  • 오브젝트 스토리지(예:disk = 's3')는 공유 메타데이터를 의미하지 않습니다. 메타데이터가 복제본당 로컬로 저장될 때(기본), 각 복제본은 오브젝트 스토리지의 blob에 대한 포인터를 독립적으로 관리합니다. 한 복제본에서 한 변경은 다른 복제본에 보이지 않습니다. 그 경우 refresh_parts_interval은 새 파츠를 복제본 간에 보이게 하지 않는데, 각 복제본이 읽는 메타데이터가 복제본 로컬이기 때문입니다.
  • 자동 파츠 새로고침은 파일시스템 메타데이터가 공유되어야 합니다(또는 테이블이 refresh를 적용할 수 있도록 테이블 소유의 읽기 전용 메타데이터를 사용하는 것). table_disk = true를 테이블 로컬 디스크와 함께 설정하는 것(예: SETTINGS disk = disk(type=object_storage, ...), table_disk = true)은 올바른 의미론을 얻는 한 가지 방법입니다: 테이블이 메타데이터 수명 주기를 소유하고 스토리지는 읽기 전용으로 취급되므로 refresh_parts_interval이 실행되고 외부에서 추가된 파츠를 발견할 수 있습니다.
  • 전역적으로 정의된 디스크(예: storage_configuration의 disk = 's3')와 기본 로컬 메타데이터로는 각 복제본이 자체 메타데이터 상태를 가집니다. blob이 S3에 있을 수는 있어도 refresh_parts_interval의 목적상 스토리지는 공유된 것으로 간주되지 않으며, ClickHouse 밖이나 다른 복제본에서 만들어진 새 파츠는 감지되지 않습니다.

자동 파츠 새로고침을 위해 메타데이터가 공유되도록 하거나 위처럼 table_disk = true로 테이블 수준 디스크를 사용하세요. 복제본 로컬 메타데이터로 refresh_parts_interval만 신뢰하는 것은 파츠를 예상대로 새로고침하지 않을 것입니다.

refresh_parts_interval은 ReplicatedMergeTree 테이블에는 사용되지 않습니다. Replicated 테이블은 이미 복제 메커니즘을 통해 파츠를 동기화합니다. 이 설정은 파츠가 외부에서 쓰여지고 메타데이터 새로고침이 필요할 때 비(非)replicated MergeTree 테이블에만 적용됩니다.

동적 구성

미리 정의된 디스크 없이 스토리지 구성을 지정할 수도 있습니다. 구성 파일이 아니라 CREATE/ATTACH 쿼리 설정으로 구성할 수 있습니다. 다음 예제 쿼리는 위의 동적 디스크 구성에 기반하며 URL에 저장된 테이블의 데이터를 캐시하기 위해 로컬 디스크를 사용하는 방법을 보여줍니다.

ATTACH TABLE uk_price_paid UUID 'cf712b4f-2ca8-435c-ac23-c4393efe52f7'
(
    price UInt32,
    date Date,
    postcode1 LowCardinality(String),
    postcode2 LowCardinality(String),
    type Enum8('other' = 0, 'terraced' = 1, 'semi-detached' = 2, 'detached' = 3, 'flat' = 4),
    is_new UInt8,
    duration Enum8('unknown' = 0, 'freehold' = 1, 'leasehold' = 2),
    addr1 String,
    addr2 String,
    street LowCardinality(String),
    locality LowCardinality(String),
    town LowCardinality(String),
    district LowCardinality(String),
    county LowCardinality(String)
)
ENGINE = MergeTree
ORDER BY (postcode1, postcode2, addr1, addr2)
  SETTINGS disk = disk(
    type=web,
    endpoint='https://raw.githubusercontent.com/ClickHouse/web-tables-demo/main/web/'
  );

아래 예제는 외부 스토리지에 캐시를 추가합니다. 아래 강조된 설정에서 type=web 디스크가 type=cache 디스크 안에 중첩되어 있음을 주목하세요. 이 예제는 type=web을 사용하지만 로컬 디스크를 포함해 어떤 디스크 타입이든 동적으로 구성할 수 있습니다. 로컬 디스크는 기본값이 없는 서버 구성 매개변수 custom_local_disks_base_directory 안에 있어야 하는 경로 인자를 요구하므로, 로컬 디스크를 사용할 때 그것도 설정하세요.

구성 기반 구성과 SQL 정의 구성을 결합하는 것도 가능합니다. 여기서 web은 서버 구성 파일에서 옵니다.

S3 스토리지 사용하기

필수 매개변수

매개변수 설명
endpoint path 또는 virtual hosted 스타일의 S3 엔드포인트 URL. 데이터 저장을 위한 버킷과 루트 경로를 포함해야 합니다.
access_key_id 인증에 사용되는 S3 access key ID.
secret_access_key 인증에 사용되는 S3 secret access key.

선택적 매개변수

매개변수 설명 기본값
region S3 리전 이름. -
support_batch_delete 배치 삭제 지원 여부를 확인할지 제어합니다. GCS가 배치 삭제를 지원하지 않으므로 Google Cloud Storage(GCS)를 사용할 때 false로 설정하세요. true
use_environment_credentials 환경 변수에서 AWS 자격 증명을 읽습니다: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, 존재하면 AWS_SESSION_TOKEN. 참고: 환경 자격 증명은 모든 S3 디스크에서 공유됩니다. 디스크마다 다른 자격 증명을 사용하려면 디스크별로 명시적 access_key_id와 secret_access_key를 지정하세요. false
use_insecure_imds_request true면 Amazon EC2 메타데이터에서 자격 증명을 얻을 때 안전하지 않은 IMDS 요청을 사용합니다. false
expiration_window_seconds 만료 기반 자격 증명이 만료되었는지 확인하기 위한 유예 기간(초). 120
proxy S3 엔드포인트에 대한 프록시 구성. proxy 블록 안의 각 uri 요소는 프록시 URL을 포함해야 합니다. -
connect_timeout_ms 소켓 연결 타임아웃(밀리초). 10000 (10초)
request_timeout_ms 요청 타임아웃(밀리초). 5000 (5초)
s3_retry_attempts 실패한 요청에 대한 재시도 횟수. 500
s3_max_single_read_retries 읽기 중 연결 끊김에 대한 재시도 횟수. 4
min_bytes_for_seek 순차 읽기 대신 seek 연산을 사용할 최소 바이트 수. 1 MB
metadata_path S3 메타데이터 파일을 저장할 로컬 파일시스템 경로. /var/lib/clickhouse/disks/<disk_name>/
skip_access_check true면 시작 중 디스크 접근 검사를 건너<니다. false
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 SSE-KMS용 암호화 컨텍스트 헤더(server_side_encryption_kms_key_id와 함께 사용). -
server_side_encryption_kms_bucket_key_enabled SSE-KMS용 S3 버킷 키를 활성화합니다(server_side_encryption_kms_key_id와 함께 사용). 버킷 수준 설정과 일치
s3_max_put_rps 스로틀 전 초당 최대 PUT 요청 수. 0 (무제한)
s3_max_put_burst RPS 한도에 도달하기 전 동시 PUT 요청 최대 수. s3_max_put_rps와 같음
s3_max_get_rps 스로틀 전 초당 최대 GET 요청 수. 0 (무제한)
s3_max_get_burst RPS 한도에 도달하기 전 동시 GET 요청 최대 수. s3_max_get_rps와 같음
key_template re2 구문을 사용해 객체 키 생성 형식을 정의합니다. storage_metadata_write_full_object_key 플래그가 필요합니다. endpoint의 root path와 호환되지 않습니다. key_compatibility_prefix가 필요합니다. -
key_compatibility_prefix key_template과 함께 필요. 더 오래된 메타데이터 버전을 읽기 위한 endpoint의 이전 root path를 지정합니다. -
read_only 디스크에서 읽기만 허용합니다. -

Google Cloud Storage(GCS)도 s3 타입으로 지원됩니다. GCS 기반 MergeTree 참고.

Plain 스토리지 사용하기

22.10에서 새 디스크 타입 s3_plain이 도입되었으며, 이는 write-once 스토리지를 제공합니다. 구성 매개변수는 s3 디스크 타입과 같습니다. s3 디스크 타입과 달리 데이터를 있는 그대로 저장합니다. 즉 무작위로 생성된 blob 이름 대신 ClickHouse가 로컬 디스크에 파일을 저장하는 것과 같은 방식의 일반 파일 이름을 사용하며, 메타데이터를 로컬에 저장하지 않습니다. 예를 들어 s3의 데이터에서 파생됩니다. 이 디스크 타입은 기존 데이터에 머지를 실행하지 않고 새 데이터 삽입을 허용하지 않으므로 테이블의 정적 버전을 유지할 수 있습니다. 이 디스크 타입의 사용 사례는 그 위에 백업을 만드는 것이며, BACKUP TABLE data TO Disk('plain_disk_name', 'backup_name')으로 할 수 있습니다. 그 후 RESTORE TABLE data AS data_restored FROM Disk('plain_disk_name', 'backup_name')를 하거나 ATTACH TABLE data (...) ENGINE = MergeTree() SETTINGS disk = 'plain_disk_name'을 사용할 수 있습니다.

24.1부터 plain 메타데이터 타입을 사용해 어떤 오브젝트 스토리지 디스크(s3, azure, hdfs(지원 안 됨), local)든 구성할 수 있습니다.

S3 Plain Rewritable 스토리지 사용하기

새 디스크 타입 s3_plain_rewritable가 24.4에서 도입되었습니다. s3_plain 디스크 타입과 유사하게 메타데이터 파일을 위한 추가 스토리지가 필요하지 않습니다. 대신 메타데이터가 S3에 저장됩니다. s3_plain 디스크 타입과 달리 s3_plain_rewritable은 머지 실행을 허용하고 INSERT 연산을 지원합니다. 뮤테이션과 테이블 복제는 지원되지 않습니다. 이 디스크 타입의 사용 사례는 비(replicated) MergeTree 테이블입니다. s3 디스크 타입이 비(replicated) MergeTree 테이블에 적합하지만, 테이블에 로컬 메타데이터가 필요 없고 제한된 연산 집합을 받아들일 수 있다면 s3_plain_rewritable 디스크 타입을 선택할 수 있습니다. 예를 들어 시스템 테이블에 유용할 수 있습니다. 24.5부터 plain_rewritable 메타데이터 타입을 사용해 어떤 오브젝트 스토리지 디스크(s3, azure, local)든 구성할 수 있습니다.

Azure Blob Storage 사용하기

MergeTree 계열 테이블 엔진은 타입 azure_blob_storage의 디스크를 사용해 Azure Blob Storage에 데이터를 저장할 수 있습니다.

연결 매개변수

매개변수 설명 기본값
storage_account_url (필수) Azure Blob Storage 계정 URL. 예: http://account.blob.core.windows.net 또는 http://azurite1:10000/devstoreaccount1. -
container_name 대상 컨테이너 이름. default-container
container_already_exists 컨테이너 생성 동작 제어: false: 새 컨테이너 생성 / true: 기존 컨테이너에 직접 연결 / 미설정: 컨테이너 존재 여부 확인 후 필요 시 생성 -

인증 매개변수(디스크는 사용 가능한 모든 방법 및 Managed Identity Credential을 시도합니다):

매개변수 설명
connection_string 연결 문자열을 사용한 인증.
account_name Shared Key를 사용한 인증(account_key와 함께 사용).
account_key Shared Key를 사용한 인증(account_name과 함께 사용).

한도 매개변수

매개변수 설명
max_single_part_upload_size Blob Storage에 대한 단일 블록 업로드의 최대 크기.
min_bytes_for_seek seek 가능 영역의 최소 크기.
max_single_read_retries Blob Storage에서 데이터 청크를 읽으려는 최대 시도 횟수.
max_single_download_retries Blob Storage에서 읽을 수 있는 버퍼를 다운로드하려는 최대 시도 횟수.
thread_pool_size IDiskRemote 인스턴스화를 위한 최대 스레드 수.
max_inflight_parts_for_one_file 단일 객체에 대한 동시 put 요청의 최대 수.

기타 매개변수

매개변수 설명 기본값
metadata_path Blob Storage용 메타데이터 파일을 저장할 로컬 파일시스템 경로. /var/lib/clickhouse/disks/<disk_name>/
skip_access_check true면 시작 중 디스크 접근 검사를 건너<니다. false
metadata_keep_free_space_bytes 예약할 여유 메타데이터 디스크 공간 양. -

작동 구성의 예는 통합 테스트 디렉터리에서 찾을 수 있습니다(예: test_merge_tree_azure_blob_storage 또는 test_azure_blob_storage_zero_copy_replication).

제로 카피 복제는 프로덕션에 준비되지 않았습니다 제로 카피 복제는 ClickHouse 22.8 이상 버전에서 기본적으로 비활성화되어 있습니다. 이 기능은 프로덕션 사용에 권장되지 않습니다.

HDFS 스토리지 사용하기 (지원되지 않음)

이 샘플 구성에서:

  • 디스크 타입은 hdfs(지원 안 됨)
  • 데이터는 hdfs://hdfs1:9000/clickhouse/에 호스팅됩니다

한편 HDFS는 지원되지 않으므로 사용 시 문제가 있을 수 있습니다. 문제가 발생하면 수정 사항으로 풀 리퀘스트를 만들어 주세요. HDFS는 극단적인 경우 작동하지 않을 수 있다는 점을 기억하세요.

데이터 암호화 사용하기

S3 또는 HDFS(지원 안 됨) 외장 디스크, 또는 로컬 디스크에 저장된 데이터를 암호화할 수 있습니다. 암호화 모드를 켜려면 구성 파일에서 타입 encrypted의 디스크를 정의하고 데이터가 저장될 디스크를 선택해야 합니다. encrypted 디스크는 쓰여지는 모든 파일을 즉석에서 암호화하고, encrypted 디스크에서 파일을 읽을 때 자동으로 복호화합니다. 따라서 encrypted 디스크를 일반 디스크처럼 사용할 수 있습니다.

예를 들어 ClickHouse가 어떤 테이블의 데이터를 disk1에 store/all_1_1_0/data.bin 파일로 쓸 때, 실제로 이 파일은 /path1/store/all_1_1_0/data.bin 경로를 따라 물리적 디스크에 쓰여집니다. 같은 파일을 disk2에 쓸 때는 암호화 모드에서 /path1/path2/store/all_1_1_0/data.bin 경로로 물리적 디스크에 실제로 쓰여집니다.

필수 매개변수

매개변수 타입 설명
type String 암호화 디스크를 만들려면 encrypted로 설정해야 합니다.
disk String 기본 스토리지에 사용할 디스크 타입.
key Uint64 암호화 및 복호화용 키. key_hex로 16진수로 지정할 수 있습니다. id 속성으로 여러 키를 지정할 수 있습니다.

선택적 매개변수

매개변수 타입 기본값 설명
path String 루트 디렉터리 데이터가 저장될 디스크의 위치.
current_key_id String - 암호화에 사용되는 키 ID. 지정된 모든 키는 복호화에 사용할 수 있습니다.
algorithm Enum AES_128_CTR 암호화 알고리즘. 옵션: AES_128_CTR (16바이트 키) / AES_192_CTR (24바이트 키) / AES_256_CTR (32바이트 키)

로컬 캐시 사용하기

22.3 버전부터 스토리지 구성에서 디스크 위에 로컬 캐시를 구성할 수 있습니다. 22.3~22.7 버전에서는 캐시가 s3 디스크 타입에서만 지원됩니다. >= 22.8 버전에서는 S3, Azure, Local, Encrypted 등 어떤 디스크 타입에서든 캐시가 지원됩니다. >= 23.5 버전에서는 S3, Azure, HDFS(지원 안 됨) 같은 원격 디스크 타입에서만 캐시가 지원됩니다. 캐시는 LRU 캐시 정책을 사용합니다. 22.8 이상 버전용 구성 예:

<cache>
    <type>cache</type>
    <disk>s3</disk>
    <path>/var/lib/clickhouse/cache/</path>
    <max_size>10Gi</max_size>
    <cache_on_write_operations>1</cache_on_write_operations>
</cache>

파일 캐시 디스크 구성 설정: 이 설정들은 디스크 구성 섹션에서 정의해야 합니다.

매개변수 타입 기본값 설명
path String - 필수. 캐시가 저장될 디렉터리의 경로.
max_size Size - 필수. 바이트 또는 읽기 가능한 형식(예: 10Gi)의 최대 캐시 크기. 한도에 도달하면 LRU 정책으로 파일이 제거됩니다. ki, Mi, Gi 형식 지원(v22.10부터).
cache_on_write_operations Boolean false INSERT 쿼리와 백그라운드 머지에 대한 write-through 캐시를 활성화합니다. 쿼리별로 enable_filesystem_cache_on_write_operations로 재정의할 수 있습니다.
enable_filesystem_query_cache_limit Boolean false max_query_cache_size에 기반한 쿼리별 캐시 크기 한도를 활성화합니다.
cache_hits_threshold Integer 0 더 이상 사용되지 않음; 효과 없음.
enable_bypass_cache_with_threshold Boolean false 큰 읽기 범위에 대해 캐시를 건너<니다.
bypass_cache_threshold Size 256Mi 캐시 우회를 트리거하는 읽기 범위 크기(enable_bypass_cache_with_threshold 필요).
max_file_segment_size Size 8Mi 단일 캐시 파일의 최대 크기(바이트 또는 읽기 가능한 형식).
max_elements Integer 10000000 최대 캐시 파일 수.
load_metadata_threads Integer 16 시작 시 캐시 메타데이터를 로드하는 스레드 수.
use_split_cache Boolean false 파일을 system/data로 분리 사용.
split_cache_ratio Double 0.1 split_cache를 위한 시스템 세그먼트의 총 캐시 크기 대비 비율.

참고: 크기 값은 ki, Mi, Gi 같은 단위를 지원합니다(예: 10Gi).

파일 캐시 쿼리/프로필 설정

설정 타입 기본값 설명
enable_filesystem_cache Boolean true cache 디스크 타입을 사용할 때도 쿼리별 캐시 사용을 활성화/비활성화합니다.
read_from_filesystem_cache_if_exists_otherwise_bypass_cache Boolean false 활성화하면 데이터가 존재할 때만 캐시를 사용합니다; 새 데이터는 캐시되지 않습니다.
enable_filesystem_cache_on_write_operations Boolean false (Cloud: true) write-through 캐시를 활성화합니다. 캐시 구성에 cache_on_write_operations가 필요합니다.
enable_filesystem_cache_log Boolean false system.filesystem_cache_log에 상세 캐시 사용 로깅을 활성화합니다.
filesystem_cache_allow_background_download Boolean true 부분적으로 다운로드된 세그먼트를 백그라운드에서 마무리할 수 있게 합니다. 비활성화하면 현재 쿼리/세션에 대해 다운로드를 포그라운드로 유지합니다.
max_query_cache_size Size false 쿼리당 최대 캐시 크기. 캐시 구성에 enable_filesystem_query_cache_limit 필요.
filesystem_cache_skip_download_if_exceeds_per_query_cache_write_limit Boolean true max_query_cache_size에 도달했을 때의 동작 제어: true: 새 데이터 다운로드 중지 / false: 새 데이터를 위한 공간을 만들기 위해 이전 데이터 제거

캐시 구성 설정과 캐시 쿼리 설정은 최신 ClickHouse 버전에 해당합니다. 더 이른 버전에서는 일부가 지원되지 않을 수 있습니다.

캐시 시스템 테이블

테이블 이름 설명 요구 사항
system.filesystem_cache 파일시스템 캐시의 현재 상태를 표시합니다. 없음
system.filesystem_cache_log 쿼리별 상세 캐시 사용 통계를 제공합니다. enable_filesystem_cache_log = true 필요

캐시 명령

이 명령은 <cache_name>이 제공되지 않을 때만 지원됩니다. 서버에 구성된 파일시스템 캐시 목록을 보여줍니다. (22.8 이하 버전에서는 명령 이름이 SHOW CACHES)

응답: 구성된 캐시 목록.

특정 캐시의 캐시 구성과 일부 일반 통계를 보여줍니다. 캐시 이름은 SHOW FILESYSTEM CACHES 명령에서 가져올 수 있습니다. (22.8 이하 버전에서는 명령 이름이 DESCRIBE CACHE)

캐시 현재 메트릭 캐시 비동기 메트릭 캐시 프로필 이벤트
FilesystemCacheSize FilesystemCacheBytes CachedReadBufferReadFromSourceBytes, CachedReadBufferReadFromCacheBytes
FilesystemCacheElements FilesystemCacheFiles CachedReadBufferReadFromSourceMicroseconds, CachedReadBufferReadFromCacheMicroseconds
CachedReadBufferCacheWriteBytes, CachedReadBufferCacheWriteMicroseconds
CachedWriteBufferCacheWriteBytes, CachedWriteBufferCacheWriteMicroseconds

정적 Web 스토리지 사용하기 (읽기 전용)

이것은 읽기 전용 디스크입니다. 데이터는 읽기만 되고 절대 수정되지 않습니다. 새 테이블은 ATTACH TABLE 쿼리로 이 디스크에 로드됩니다(아래 예제 참고). 로컬 디스크는 실제로 사용되지 않으며, 각 SELECT 쿼리는 필요한 데이터를 가져오기 위해 http 요청을 발생시킵니다. 테이블 데이터의 모든 수정은 예외를 발생시키며, 즉 다음 유형의 쿼리는 허용되지 않습니다: CREATE TABLE, ALTER TABLE, RENAME TABLE, DETACH TABLE, TRUNCATE TABLE. Web 스토리지는 읽기 전용 목적으로 사용할 수 있습니다. 예시 용도는 샘플 데이터 호스팅 또는 데이터 마이그레이션입니다. clickhouse-static-files-uploader라는 도구가 주어진 테이블의 데이터 디렉터리를 준비합니다(SELECT data_paths FROM system.tables WHERE name = 'table_name'). 필요한 각 테이블에 대해 파일 디렉터리를 얻습니다. 이 파일들은 예를 들어 정적 파일을 제공하는 웹 서버에 업로드할 수 있습니다. 이 준비 후 DiskWeb을 통해 어떤 ClickHouse 서버에도 이 테이블을 로드할 수 있습니다. 이 샘플 구성에서:

  • 디스크 타입은 web
  • 데이터는 http://nginx:80/test1/에 호스팅됩니다
  • 로컬 스토리지에 캐시가 사용됩니다

웹 데이터셋이 일상적으로 사용될 것으로 예상되지 않는다면 쿼리 내에서 일시적으로 스토리지를 구성할 수도 있습니다. 동적 구성 섹션을 참고하고 구성 파일 편집을 건너뛰세요. 데모 데이터셋이 GitHub에 호스팅되어 있습니다. 웹 스토리지용 테이블을 준비하려면 clickhouse-static-files-uploader 도구를 참고하세요.

이 ATTACH TABLE 쿼리에서 제공된 UUID는 데이터 디렉터리 이름과 일치하며, endpoint는 raw GitHub 콘텐츠의 URL입니다. 준비된 테스트 케이스: 이 구성은 config에 추가한 다음 이 쿼리를 실행해야 합니다.

필수 매개변수

매개변수 설명
type web. 그렇지 않으면 디스크가 생성되지 않습니다.
endpoint path 형식의 엔드포인트 URL. 엔드포인트 URL은 데이터를 저장할 루트 경로(업로드된 위치)를 포함해야 합니다.

선택적 매개변수

web 오브젝트 스토리지 백엔드는 endpoint 매개변수만 읽습니다. 추가 web 전용 선택적 매개변수는 없습니다. 일반 디스크 옵션은 여전히 적용됩니다. 쿼리가 DB:Exception Unreachable URL 예외로 실패하면 http_connection_timeout, http_receive_timeout, keep_alive_timeout 설정을 조정해 볼 수 있습니다. 업로드할 파일을 얻으려면 clickhouse static-files-disk-uploader --metadata-path <path> --output-dir <dir>를 실행하세요(--metadata-path는 SELECT data_paths FROM system.tables WHERE name = 'table_name' 쿼리에서 찾을 수 있습니다). endpoint로 파일을 로드할 때 <endpoint>/store/ 경로에 로드되어야 하지만, 구성에는 endpoint만 포함되어야 합니다. 서버가 테이블을 시작할 때 디스크 로드에서 URL에 도달할 수 없으면 모든 오류가 포착됩니다. 이 경우 오류가 있었다면 DETACH TABLE table_name -> ATTACH TABLE table_name으로 테이블을 다시 로드할 수 있습니다(보이게 됩니다). 서버 시작 시 메타데이터가 성공적으로 로드되면 테이블을 즉시 사용할 수 있습니다. http_max_tries를 사용해 초기 시도를 포함한 HTTP 읽기 시도 횟수를 제한하세요. 재시도 사이의 초기 및 최대 지연을 구성하려면 http_retry_initial_backoff_ms와 http_retry_max_backoff_ms를 사용하세요.

제로 카피 복제 (프로덕션에 준비되지 않음)

제로 카피 복제는 S3와 HDFS(지원 안 됨) 디스크로 가능하지만 권장되지 않습니다. 제로 카피 복제는 데이터가 여러 머신에 원격으로 저장되어 동기화가 필요할 때, 데이터 자체가 아닌 메타데이터만(데이터 파츠의 경로) 복제된다는 것을 의미합니다.

제로 카피 복제는 프로덕션에 준비되지 않았습니다 제로 카피 복제는 ClickHouse 22.8 이상 버전에서 기본적으로 비활성화되어 있습니다. 이 기능은 프로덕션 사용에 권장되지 않습니다.

더 알아보기 (Learn more)