Iceberg 카탈로그

Iceberg 카탈로그

iceberg 확장은 Iceberg REST 카탈로그 부착을 지원해요. Iceberg에 쓰기를 하려면 카탈로그 부착이 필요해요. 각 카탈로그 구현별 연결 방법과 REST 스펙 제한 대응 옵션을 살펴볼게요.

출처: 문서

본문

iceberg 확장은 Iceberg REST 카탈로그 부착을 지원해요. Iceberg에 쓰기를 하려면 카탈로그 부착이 필요해요. Iceberg REST 카탈로그를 부착하기 전에 개요의 지침을 따라 iceberg 확장을 설치해야 해요.

아래 섹션은 Iceberg REST 카탈로그를 부착하는 일반적인 방법을 설명해요. 카탈로그 구현별 지침은 Amazon S3 Tables, AWS Glue, Cloudflare R2 데이터 카탈로그, Apache Polaris, Lakekeeper, SeaweedFS, Google Cloud BigLake를 참고해요.

Iceberg REST 카탈로그 부착하기

대부분의 Iceberg REST 카탈로그는 OAuth2로 인증해요. OAuth2 서비스의 로그인 자격 증명을 저장하기 위해 기존 DuckDB secret 워크플로우를 사용할 수 있어요.

CREATE SECRET iceberg_secret (
    TYPE ICEBERG,
    CLIENT_ID '⟨admin⟩',
    CLIENT_SECRET '⟨password⟩',
    OAUTH2_SERVER_URI '⟨http://iceberg_rest_catalog_url.com/v1/oauth/tokens⟩'
);

이미 Bearer 토큰이 있다면 CREATE SECRET 문에 직접 전달할 수 있어요.

CREATE SECRET iceberg_secret (
    TYPE ICEBERG,
    TOKEN '⟨bearer_token⟩'
);

다음 ATTACH 문으로 Iceberg 카탈로그를 부착할 수 있어요.

LOAD httpfs;
ATTACH '⟨warehouse⟩' AS iceberg_catalog (
   TYPE ICEBERG,
   SECRET iceberg_secret, -- pass a specific secret name to prevent ambiguity
   ENDPOINT '⟨https://rest_endpoint.com⟩'
);

사용 가능한 테이블을 보려면 다음을 실행해요.

SHOW ALL TABLES;

OAuth2 인증이 있는 REST 카탈로그는 ATTACH 문만으로도 부착할 수 있어요. ATTACH 및 CREATE SECRET 옵션의 전체 목록은 Iceberg 옵션 페이지를 참고해요.

Amazon S3 Tables

iceberg 확장은 Amazon S3 Tables에 저장된 Iceberg 테이블 읽기를 지원해요.

Secrets Manager로 다음 secret을 생성하면 ~/.aws 디렉토리의 기본 프로필을 기반으로 AWS 자격 증명과 구성을 DuckDB가 자동으로 감지하게 할 수 있어요.

CREATE SECRET (
    TYPE s3,
    PROVIDER credential_chain
);

또는 값을 수동으로 설정할 수도 있어요.

CREATE SECRET (
    TYPE s3,
    KEY_ID '⟨key_id⟩',
    SECRET '⟨secret⟩',
    REGION '⟨region⟩'
);

자격 증명 옵션의 전체 범위(가정된 역할, SSO, 웹 ID 등)는 aws 확장을 참고해요.

그런 다음 AWS Management Console에서 확인 가능한 S3 Tables ARN과 ENDPOINT_TYPE s3_tables 옵션을 사용해 카탈로그에 연결해요.

ATTACH '⟨s3_tables_arn⟩' AS my_s3_tables_catalog (
   TYPE iceberg,
   ENDPOINT_TYPE s3_tables
);

경고 ENDPOINT_TYPE s3_tables는 항상 s3tables.⟨region⟩.amazonaws.com/iceberg 형태의 엔드포인트를 생성해요. 이는 일반적인 amazonaws.com 접미사를 사용하지 않는 리전에서는 올바르지 않아요. 특히 amazonaws.com.cn을 사용하는 AWS 중국 리전(cn-north-1, cn-northwest-1)이 그렇죠. 이런 리전에서는 ENDPOINT_TYPE 대신 명시적 ENDPOINT(리전에 맞는 올바른 호스트)와 AUTHORIZATION_TYPE 'sigv4'를 함께 전달해 카탈로그를 부착해요.

부착이 잘 됐는지 확인하려면 모든 테이블을 나열해요.

SHOW ALL TABLES;

테이블은 다음과 같이 쿼리할 수 있어요.

SELECT count(*)
FROM my_s3_tables_catalog.⟨namespace_name⟩.⟨table_name⟩;

AWS Glue (Amazon SageMaker Lakehouse)

iceberg 확장은 Amazon SageMaker Lakehouse (a.k.a. AWS Glue) 카탈로그를 통해 Iceberg 테이블 읽기를 지원해요.

Secrets Manager로 S3 secret을 생성해요.

CREATE SECRET (
    TYPE s3,
    PROVIDER credential_chain,
    CHAIN sts,
    ASSUME_ROLE_ARN 'arn:aws:iam::⟨account_id⟩:role/⟨role⟩',
    REGION 'us-east-2'
);

이 예제에서는 STS 토큰을 사용하지만, 다른 인증 방법도 지원돼요.

그런 다음 카탈로그에 연결해요.

ATTACH '⟨account_id⟩' AS glue_catalog (
    TYPE ICEBERG,
    ENDPOINT 'glue.⟨REGION⟩.amazonaws.com/iceberg',
    AUTHORIZATION_TYPE 'sigv4'
);

또는 이렇게도 가능해요.

ATTACH '⟨account_id⟩' AS glue_catalog (
    TYPE ICEBERG,
    ENDPOINT_TYPE 'glue'
);

경고 Amazon S3 Tables와 마찬가지로 ENDPOINT_TYPE glue는 항상 glue.⟨region⟩.amazonaws.com/iceberg 형태의 엔드포인트를 생성해요. 이는 일반적인 amazonaws.com 접미사를 사용하지 않는 리전(특히 amazonaws.com.cn을 사용하는 AWS 중국 리전 cn-north-1, cn-northwest-1)에서는 올바르지 않아요. 이런 리전에서는 ENDPOINT_TYPE 대신 명시적 ENDPOINT(올바른 호스트)와 AUTHORIZATION_TYPE 'sigv4'를 함께 사용해 부착해요.

웨어하우스 식별자(ATTACH의 첫 번째 인자)는 다음 형태를 받아들여요.

웨어하우스	의미
:	호출자 계정의 기본 카탈로그.
⟨account_id⟩	12자리 AWS 계정 ID.
⟨account_id⟩:⟨catalog⟩	주어진 계정의 명명된 카탈로그.
⟨catalog⟩/⟨sub_catalog⟩	중첩(페더레이션) 카탈로그.
⟨account_id⟩:⟨catalog⟩/⟨sub_catalog⟩	주어진 계정의 중첩 카탈로그.

부착이 잘 됐는지 확인하려면 모든 테이블을 나열해요.

SHOW ALL TABLES;

테이블은 다음과 같이 쿼리할 수 있어요.

SELECT count(*)
FROM glue_catalog.⟨namespace_name⟩.⟨table_name⟩;

S3 Tables 페더레이션 카탈로그가 있다면 표준 CREATE TABLE 문법으로 테이블을 만들 수 있어요.

CREATE TABLE glue_catalog.⟨namespace_name⟩.⟨table_name⟩ (a INTEGER, b VARCHAR);

카탈로그가 S3 Tables로 페더레이션되지 않았다면 location 테이블 속성을 전달해야 할 수 있어요. WITH 절로 이렇게 할 수 있어요.

CREATE TABLE glue_catalog.⟨namespace_name⟩.⟨table_name⟩ (a INTEGER, b VARCHAR)
WITH (
    'location' = 's3://path/to/location'
);

WITH 절에 대한 자세한 내용은 테이블 만들기에서 확인할 수 있어요.

Cloudflare R2 데이터 카탈로그

R2 Cloudflare 관리형 카탈로그에 부착하려면 아래 부착 단계를 따라가요.

CREATE SECRET r2_secret (
    TYPE ICEBERG,
    TOKEN '⟨r2_token⟩'
);

시작하기의 API 토큰 만들기 단계를 따라 토큰을 만들 수 있어요. 그런 다음 다음 명령으로 카탈로그를 부착해요.

ATTACH '⟨warehouse⟩' AS my_r2_catalog (
    TYPE ICEBERG,
    ENDPOINT '⟨catalog-uri⟩'
);

warehouse와 catalog-uri 변수는 R2 Object Storage 카탈로그(R2 Object Store, Catalog name, Settings)의 설정에서 사용할 수 있어요.

R2 데이터 카탈로그에 부착한 후 스키마를 만들어요. USE 명령으로 기본값으로 설정할 수 있어요.

CREATE SCHEMA my_r2_catalog.my_schema;
USE my_r2_catalog.my_schema;

Apache Polaris

Polaris 카탈로그에 부착하려면 다음 명령을 사용해요.

CREATE SECRET polaris_secret (
    TYPE ICEBERG,
    CLIENT_ID '⟨admin⟩',
    CLIENT_SECRET '⟨password⟩',
);

ATTACH 'quickstart_catalog' AS polaris_catalog (
    TYPE ICEBERG,
    ENDPOINT '⟨polaris_rest_catalog_endpoint⟩',
    ACCESS_DELEGATION_MODE 'vended_credentials'
);

Lakekeeper

Lakekeeper 카탈로그에 부착하려면 다음 명령이 동작해요.

CREATE SECRET lakekeeper_secret (
    TYPE ICEBERG,
    CLIENT_ID '⟨admin⟩',
    CLIENT_SECRET '⟨password⟩',
    OAUTH2_SCOPE '⟨scope⟩',
    OAUTH2_SERVER_URI '⟨lakekeeper_oauth_url⟩'
);

ATTACH '⟨warehouse⟩' AS lakekeeper_catalog (
    TYPE ICEBERG,
    ENDPOINT '⟨lakekeeper_irc_url⟩',
    SECRET '⟨lakekeeper_secret⟩'
);

SeaweedFS

SeaweedFS 테이블 버킷은 Iceberg 배포의 두 절반을 모두 제공해요. 내장 Iceberg REST 카탈로그는 테이블 메타데이터를 제공하고, 테이블 버킷은 같은 SeaweedFS S3 게이트웨이 뒤에서 테이블 데이터를 Parquet 파일로 저장해요. 카탈로그의 OAuth2 자격 증명을 Iceberg secret에, S3 자격 증명을 S3 secret에 저장해 DuckDB가 같은 게이트웨이에서 Parquet 파일을 읽을 수 있게 해요.

CREATE SECRET seaweedfs_secret (
    TYPE ICEBERG,
    CLIENT_ID '⟨access_key⟩',
    CLIENT_SECRET '⟨secret_key⟩',
    OAUTH2_SERVER_URI 'http://⟨seaweedfs_host⟩:8181/v1/oauth/tokens'
);

CREATE SECRET seaweedfs_storage (
    TYPE s3,
    KEY_ID '⟨access_key⟩',
    SECRET '⟨secret_key⟩',
    ENDPOINT '⟨seaweedfs_host⟩:8333',
    URL_STYLE 'path',
    USE_SSL false
);

ATTACH '⟨table_bucket_name⟩' AS seaweedfs_catalog (
    TYPE ICEBERG,
    ENDPOINT 'http://⟨seaweedfs_host⟩:8181',
    SECRET seaweedfs_secret
);

읽기와 쓰기는 기본 ATTACH 옵션으로 동작해요. CREATE SCHEMA, CREATE TABLE, INSERT, DROP TABLE을 포함해요.

CREATE SCHEMA seaweedfs_catalog.sales;
CREATE TABLE seaweedfs_catalog.sales.orders (id BIGINT, region VARCHAR, amount DOUBLE);
INSERT INTO seaweedfs_catalog.sales.orders VALUES (1, 'NA', 12.5), (2, 'EU', 40.0), (3, 'APAC', 99.9);

SELECT region, sum(amount) AS total
FROM seaweedfs_catalog.sales.orders
GROUP BY region
ORDER BY total DESC;

DROP TABLE seaweedfs_catalog.sales.orders;

Google Cloud BigLake

Google Cloud BigLake 카탈로그에 부착하려면 추가 HTTP 헤더를 사용해 과금 목적의 GCP 프로젝트를 지정할 수 있어요.

먼저 Google Cloud 액세스 토큰을 가져와요.

gcloud auth application-default print-access-token

그런 다음 토큰과 추가 헤더로 secret을 만들어요.

CREATE SECRET biglake_secret (
    TYPE ICEBERG,
    TOKEN '⟨your_access_token⟩',
    EXTRA_HTTP_HEADERS MAP {
        'x-goog-user-project': '⟨your_gcp_project_id⟩'
    }
);

BigLake 카탈로그에 부착해요.

ATTACH '⟨gs://your-biglake-bucket⟩' AS biglake_catalog (
    TYPE ICEBERG,
    ENDPOINT 'https://biglake.googleapis.com/iceberg/v1/restcatalog',
    SECRET biglake_secret
);

BigLake 공개 데이터셋을 사용한 예제:

CREATE SECRET biglake_public_secret (
    TYPE ICEBERG,
    TOKEN '⟨your_access_token⟩',
    EXTRA_HTTP_HEADERS MAP {
        'x-goog-user-project': '⟨your_gcp_project_id⟩'
    }
);

ATTACH 'gs://biglake-public-nyc-taxi-iceberg' AS biglake_public (
    TYPE ICEBERG,
    ENDPOINT 'https://biglake.googleapis.com/iceberg/v1/restcatalog',
    SECRET biglake_public_secret
);

-- Query the data
SELECT count(*) FROM biglake_public.public_data.nyc_taxicab;

참고: Google Cloud 액세스 토큰은 1시간 후 만료돼요. 장기 실행 세션에서는 토큰을 주기적으로 갱신해야 해요.

REST 스펙 지원이 제한된 카탈로그

일부 카탈로그는 Iceberg REST 카탈로그 스펙의 일부만 구현해요. 아래 호환성 옵션을 사용해 이 카탈로그에 맞게 DuckDB의 동작을 조정해요.

카탈로그 동작	설정할 옵션
스테이징 CREATE TABLE 미지원	STAGE_CREATE_TABLES false
다중 테이블 트랜잭션/커밋 엔드포인트 거부	DISABLE_MULTI_TABLE_COMMIT true
CREATE TABLE 시 메타데이터를 완전히 초기화하고 후속 메타데이터 업데이트 거부	SKIP_CREATE_TABLE_METADATA_UPDATES true
DROP TABLE 시 DuckDB가 저장소 파일을 제거하도록 허용하지 않음	REMOVE_FILES_ON_DELETE false

예를 들어 스테이징 생성을 지원하지 않고, 트랜잭션/커밋 엔드포인트를 거부하며, 자체 메타데이터와 저장소 정리를 관리하는 Unity Catalog Horizon 엔드포인트를 부착하려면:

ATTACH '⟨warehouse⟩' AS horizon_catalog (
    TYPE iceberg,
    ENDPOINT '⟨catalog_endpoint⟩',
    STAGE_CREATE_TABLES false,
    DISABLE_MULTI_TABLE_COMMIT true,
    SKIP_CREATE_TABLE_METADATA_UPDATES true,
    REMOVE_FILES_ON_DELETE false
);

제한 사항

DuckDB는 S3, S3 Tables 및 Google Cloud Storage (GCS)를 백엔드로 하는 Iceberg REST 카탈로그를 지원해요. 다른 저장소 백엔드에 대한 지원은 아직 사용할 수 없어요.

더 알아보기 (Learn more)

• Amazon S3 Tables 문서에서 S3 Tables 연결을 확인해요.
• Iceberg에 쓰기 문서에서 카탈로그에 쓰는 방법을 살펴볼 수 있어요.