DeltaLake 테이블 엔진

S3, GCP, Azure 스토리지의 기존 Delta Lake 테이블과의 통합을 제공하는 테이블 엔진이에요. 읽기와 쓰기를 모두 지원해요(쓰기는 25.10부터 S3와 GCS, 26.9부터 Azure).

출처: 문서

본문

이 엔진은 S3, GCP, Azure 스토리지의 기존 Delta Lake 테이블과의 통합을 제공하고, 읽기와 쓰기를 모두 지원해요(S3와 GCS는 v25.10부터, Azure는 v26.9부터 쓰기 지원).

DeltaLake 테이블 만들기 (Create a DeltaLake table)

기본적으로 Delta Lake 테이블은 S3, GCP 또는 Azure 스토리지에 이미 존재해야 하며, 아래 명령은 DDL 컬럼 정의 없이 그것에 붙어요. allow_delta_lake_create_table = 1이면, _delta_log가 없는 위치에 명시적 컬럼이 있는 CREATE TABLE이 delta-kernel-rs를 통해 초기 커밋을 써서 새 Delta Lake 테이블을 대신 만들어요(파티션 테이블 생성은 아직 미지원). Unity DataLakeCatalog 데이터베이스 안에서는 테이블이 카탈로그에도 등록돼요.

S3
GCP
Azure

문법 (Syntax)

CREATE TABLE table_name
ENGINE = DeltaLake(url, [aws_access_key_id, aws_secret_access_key,] [extra_credentials])

엔진 매개변수 (Engine parameters)

url — 기존 Delta Lake 테이블로의 경로가 있는 버킷 URL.
aws_access_key_id, aws_secret_access_key — AWS 계정 사용자의 장기 자격 증명. 요청을 인증하는 데 사용할 수 있어요. 선택 매개변수. 자격 증명이 지정되지 않으면 설정 파일에서 사용돼요.
extra_credentials - 선택 사항. ClickHouse Cloud에서 역할 기반 접근을 위한 role_arn을 전달하는 데 사용돼요. 구성 단계는 Secure S3를 참고해요.

엔진 매개변수는 명명된 컬렉션(Named Collections)으로 지정할 수 있어요.

예시 (Example)

CREATE TABLE deltalake
ENGINE = DeltaLake('http://mars-doc-test.s3.amazonaws.com/clickhouse-bucket-3/test_table/', 'ABC123', 'Abc+123')

명명된 컬렉션 사용:

<clickhouse>
    <named_collections>
        <deltalake_conf>
            <url>http://mars-doc-test.s3.amazonaws.com/clickhouse-bucket-3/</url>
            <access_key_id>ABC123</access_key_id>
            <secret_access_key>Abc+123</secret_access_key>
        </deltalake_conf>
    </named_collections>
</clickhouse>

CREATE TABLE deltalake
ENGINE = DeltaLake(deltalake_conf, filename = 'test_table')

문법 (Syntax)

-- Using HTTPS URL (recommended)
CREATE TABLE table_name
ENGINE = DeltaLake('https://storage.googleapis.com/<bucket>/<path>/', '<access_key_id>', '<secret_access_key>')

gs://clickhouse-docs-example-bucket 같은 gsutil URI는 지원되지 않아요. https://storage.googleapis.com으로 시작하는 URL을 사용해 주세요.

인자 (Arguments)

url — Delta Lake 테이블의 GCS 버킷 URL. https://storage.googleapis.com/<bucket>/<path>/ 형식(GCS XML API 엔드포인트) 또는 자동 변환되는 gs://<bucket>/<path>/을 사용해야 해요.
access_key_id — GCS 액세스 키. Google Cloud Console → Cloud Storage → Settings → Interoperability로 만들 수 있어요.
secret_access_key — GCS 시크릿.

명명된 컬렉션 (Named collections)

명명된 컬렉션도 사용할 수 있어요. 예를 들어:

CREATE NAMED COLLECTION gcs_creds AS
access_key_id = '<access_key>',
secret_access_key = '<secret>';

CREATE TABLE gcpDeltaLake
ENGINE = DeltaLake(gcs_creds, url = 'https://storage.googleapis.com/<bucket>/<path>')

문법 (Syntax)

CREATE TABLE table_name
ENGINE = DeltaLake(connection_string|storage_account_url, container_name, blobpath, [account_name, account_key, format, compression])

인자 (Arguments)

connection_string — Azure 연결 문자열.
storage_account_url — Azure 스토리지 계정 URL(예: https://account.blob.core.windows.net).
container_name — Azure 컨테이너 이름.
blobpath — 컨테이너 안의 Delta Lake 테이블 경로.
account_name — Azure 스토리지 계정 이름.
account_key — Azure 스토리지 계정 키.

DeltaLake 테이블로 데이터 쓰기 (Write data using a DeltaLake table)

DeltaLake 테이블 엔진으로 테이블을 만든 후 다음으로 데이터를 넣을 수 있어요.

SET allow_delta_lake_writes = 1;

INSERT INTO deltalake(id, firstname, lastname, gender, age)
VALUES (1, 'John', 'Smith', 'M', 32);

Delta Lake 쓰기는 기본적으로 꺼진 베타 기능이며 SET allow_delta_lake_writes = 1;(26.7 버전부터 사용 가능, 이전 버전은 SET allow_experimental_delta_lake_writes = 1;)로 켜야 해요. 테이블 엔진으로의 쓰기는 delta kernel을 통해서만 지원돼요. 쓰기는 S3와 GCS에서, 그리고 Azure는 26.9 버전부터 동작해요. Azure workload identity 인증(extra_credentials(client_id = ..., tenant_id = ...))은 delta kernel에서 지원되지 않아요.

데이터 캐시 (Data cache)

DeltaLake 테이블 엔진과 테이블 함수는 S3, AzureBlobStorage, HDFS 스토리지와 같은 데이터 캐싱을 지원해요. 자세한 내용은 "S3 테이블 엔진"을 참고해요.

더 알아보기 (Learn more)

deltaLake 테이블 함수