AzureBlobStorage 테이블 엔진

AzureBlobStorage 테이블 엔진

Azure Blob Storage 생태계와의 통합을 제공하는 테이블 엔진이에요.

출처: 문서

본문

이 엔진은 Azure Blob Storage 생태계와의 통합을 제공해요.

테이블 만들기 (Create table)

CREATE TABLE azure_blob_storage_table (name String, value UInt32)
    ENGINE = AzureBlobStorage(connection_string|storage_account_url, container_name, blobpath, [account_name, account_key, format, compression, partition_strategy, partition_columns_in_data_file, extra_credentials(client_id=, tenant_id=)])
    [PARTITION BY expr]
    [SETTINGS ...]

엔진 매개변수 (Engine parameters)

  • endpoint — 컨테이너와 접두사를 가진 AzureBlobStorage 엔드포인트 URL. 사용된 인증 방법이 필요하다면 선택적으로 account_name을 담을 수 있어요(http://azurite1:{port}/[account_name]{container_name}/{data_prefix}). 또는 이 매개변수들을 storage_account_url, account_name, container로 별도 제공할 수 있어요. 접두사 지정에는 endpoint를 사용해야 해요.
  • endpoint_contains_account_name — endpoint가 account_name을 포함하는지 지정하는 플래그. 특정 인증 방법에서만 필요해요. (기본값: true)
  • connection_string|storage_account_url — connection_string은 account name과 key를 포함해요(연결 문자열 만들기). 또는 여기에 storage account url을 제공하고 account name과 account key를 별도 매개변수로(account_name, account_key 참고) 제공할 수도 있어요.
  • container_name — 컨테이너 이름.
  • blobpath — 파일 경로. 읽기 전용 모드에서 다음 와일드카드를 지원해요: *, **, ?, {abc,def}, {N..M}(N, M은 숫자, 'abc', 'def'는 문자열).
  • account_name — storage_account_url을 사용하면 account name을 여기 지정할 수 있어요.
  • account_key — storage_account_url을 사용하면 account key를 여기 지정할 수 있어요.
  • format — 파일의 형식(format).
  • compression — 지원 값: none, gzip/gz, deflate, brotli/br, xz/LZMA, zstd/zst, lz4, bz2, snappy. 기본적으로 파일 확장자로 압축을 자동 감지해요(auto로 설정하는 것과 같음). 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.
  • extra_credentials - 인증에 client_id와 tenant_id를 사용해요. extra_credentials가 제공되면 account_name과 account_key보다 우선해요.

예시 (Example)

사용자는 로컬 Azure Storage 개발을 위해 Azurite 에뮬레이터를 사용할 수 있어요. 자세한 내용은 여기를 참고해요. 로컬 Azurite 인스턴스를 사용하면 아래 명령의 http://azurite1:10000을 http://localhost:10000으로 대체해야 할 수 있어요. 여기서는 Azurite가 호스트 azurite1에서 사용 가능하다고 가정해요.

CREATE TABLE test_table (key UInt64, data String)
    ENGINE = AzureBlobStorage('DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite1:10000/devstoreaccount1/;', 'testcontainer', 'test_table', 'CSV');

INSERT INTO test_table VALUES (1, 'a'), (2, 'b'), (3, 'c');

SELECT * FROM test_table;

┌─key──┬─data──┐
│  1   │   a   │
│  2   │   b   │
│  3   │   c   │
└──────┴───────┘

가상 컬럼 (Virtual columns)

  • _path — 파일 경로. 타입: LowCardinality(String).
  • _file — 파일 이름. 타입: LowCardinality(String).
  • _size — 바이트 단위의 파일 크기. 타입: Nullable(UInt64). 크기를 알 수 없으면 값은 NULL이에요.
  • _time — 파일의 마지막 수정 시간. 타입: Nullable(DateTime). 시간을 알 수 없으면 값은 NULL이에요.

인증 (Authentication)

현재 3가지 인증 방법이 있어요.

  • Managed Identity — endpoint, connection_string 또는 storage_account_url을 제공해 사용할 수 있어요.
  • SAS Token — endpoint, connection_string 또는 storage_account_url을 제공해 사용할 수 있어요. URL에 ?가 있으면 식별돼요. 예시는 azureBlobStorage를 참고해요.
  • Workload Identity — endpoint 또는 storage_account_url을 제공해 사용할 수 있어요. 설정에 use_workload_identity 매개변수가 설정되면 인증에 workload identity를 사용해요.

데이터 캐시 (Data cache)

Azure 테이블 엔진은 로컬 디스크의 데이터 캐싱을 지원해요. 파일시스템 캐시 구성 옵션과 사용법은 이 섹션을 참고해요. 캐싱은 스토리지 객체의 경로와 ETag에 따라 이루어지므로, ClickHouse는 오래된 캐시 버전을 읽지 않아요. 캐싱을 켜려면 설정 filesystem_cache_name = '<name>'과 enable_filesystem_cache = 1을 사용해요.

SELECT *
FROM azureBlobStorage('DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite1:10000/devstoreaccount1/;', 'testcontainer', 'test_table', 'CSV')
SETTINGS filesystem_cache_name = 'cache_for_azure', enable_filesystem_cache = 1;
  • 다음 섹션을 clickhouse 설정 파일에 추가해요.
<clickhouse>
    <filesystem_caches>
        <cache_for_azure>
            <path>path to cache directory</path>
            <max_size>10Gi</max_size>
        </cache_for_azure>
    </filesystem_caches>
</clickhouse>
  • clickhouse storage_configuration 섹션의 캐시 구성(따라서 캐시 저장소)을 재사용해요. 여기 설명됨

PARTITION BY

PARTITION BY — 선택 사항. 대부분의 경우 파티션 키가 필요 없고, 필요하다면 일반적으로 월 단위보다 세밀한 파티션 키는 필요 없어요. 파티셔닝은 쿼리를 빠르게 하지 않아요(ORDER BY 표현식과 대조적으로). 너무 세밀한 파티셔닝은 절대 사용하지 마세요. 클라이언트 식별자나 이름으로 데이터를 파티셔닝하지 마세요(대신 클라이언트 식별자나 이름을 ORDER BY 표현식의 첫 번째 컬럼으로 만들어요). 월 단위 파티셔닝에는 toYYYYMM(date_column) 표현식을 사용해요. 여기서 date_column은 Date 타입의 날짜 컬럼이에요. 여기 파티션 이름은 "YYYYMM" 형식이에요.

파티션 전략 (Partition strategy)

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

hive는 읽기와 쓰기에 hive 스타일 파티셔닝을 구현해요. 읽기는 재귀적 glob 패턴으로 구현돼요. 쓰기는 <prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)> 형식으로 파일을 생성해요. 참고: hive 파티션 전략을 사용할 때 use_hive_partitioning 설정은 효과가 없어요.

hive 파티션 전략 예시:

create table azure_table (year UInt16, country String, counter UInt8) ENGINE=AzureBlobStorage(account_name='devstoreaccount1', account_key='Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==', storage_account_url = 'http://localhost:30000/devstoreaccount1', container='cont', blob_path='hive_partitioned', format='Parquet', compression='auto', partition_strategy='hive') PARTITION BY (year, country);

insert into azure_table values (2020, 'Russia', 1), (2021, 'Brazil', 2);

select _path, * from azure_table;

┌─_path──────────────────────────────────────────────────────────────────────┬─year─┬─country─┬─counter─┐
│ cont/hive_partitioned/year=2020/country=Russia/7351305360873664512.parquet │ 2020 │ Russia  │       1 │
│ cont/hive_partitioned/year=2021/country=Brazil/7351305360894636032.parquet │ 2021 │ Brazil  │       2 │
└────────────────────────────────────────────────────────────────────────────┴──────┴─────────┴─────────┘

더 알아보기 (Learn more)