Iceberg REST 카탈로그

Iceberg REST 카탈로그 (Iceberg REST Catalogs)

이 페이지는 Iceberg REST 카탈로그에 연결하는 방법을 다뤄요: 인증, 전체 ATTACH 옵션, 특정 카탈로그에 대한 설정 지침이에요. 카탈로그를 attach하고 쿼리하는 기본은 Catalog Managed Tables에서, 쓰기 연산은 Writing to Iceberg에서 확인할 수 있어요.

출처: 문서

본문

Amazon이 관리하는 Iceberg REST 카탈로그에 attach한다면 Amazon S3 Tables 또는 Amazon SageMaker Lakehouse에 attach하는 지침을 확인해 주세요.

다른 모든 Iceberg REST 카탈로그는 아래 지침을 따라주세요. 특정 카탈로그에 대한 질문은 Examples 섹션을 확인해 주세요.

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

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 카탈로그를 attach할 수 있어요.

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;

ATTACH 옵션 (ATTACH Options)

OAuth2 인증이 있는 REST 카탈로그는 ATTACH 문만으로도 attach할 수 있어요. REST 카탈로그의 전체 ATTACH 옵션 목록은 아래를 참고해요.

Parameter Type Default Description
ENDPOINT_TYPE VARCHAR NULL S3 Tables 또는 Glue 카탈로그 attach에 사용. 허용 값은 GLUE와 S3_TABLES. ENDPOINT 또는 AUTHORIZATION_TYPE과 함께 사용 불가.
ENDPOINT VARCHAR NULL REST 카탈로그와 통신할 URL 엔드포인트. ENDPOINT_TYPE과 함께 사용 불가.
SECRET VARCHAR NULL REST 카탈로그와 통신하는 데 사용되는 secret 이름.
CLIENT_ID VARCHAR NULL secret에 사용되는 CLIENT_ID.
CLIENT_SECRET VARCHAR NULL secret에 사용되는 CLIENT_SECRET.
DEFAULT_REGION VARCHAR NULL 스토리지 계층과 통신할 때 사용할 기본 리전.
DEFAULT_SCHEMA VARCHAR NULL attach된 카탈로그에 사용할 기본 스키마(네임스페이스).
OAUTH2_SERVER_URI VARCHAR NULL Bearer 토큰을 얻기 위한 OAuth2 서버 URL.
AUTHORIZATION_TYPE VARCHAR OAUTH2 인증 방식. SigV4 인증이 필요한 카탈로그에는 SigV4를, 인증이 필요 없는 카탈로그에는 none을 전달. ENDPOINT_TYPE과 함께 사용 불가.
ACCESS_DELEGATION_MODE VARCHAR vended_credentials 접근 위임 모드. 허용 값은 vended_credentials와 none.
EXTRA_HTTP_HEADERS MAP NULL REST 카탈로그 요청과 함께 보낼 추가 HTTP 헤더.
SUPPORT_NESTED_NAMESPACES BOOLEAN false 중첩 네임스페이스를 지원하는 카탈로그에는 true로 설정.
STAGE_CREATE_TABLES BOOLEAN true DuckDB가 staged CREATE TABLE을 사용하는지 제어. staged 테이블 생성을 지원하지 않는 카탈로그에는 비활성화.
DISABLE_MULTI_TABLE_COMMIT BOOLEAN false 다중 테이블 트랜잭션/커밋 엔드포인트를 비활성화. 이 엔드포인트를 거부하는 카탈로그에는 활성화.
SKIP_CREATE_TABLE_METADATA_UPDATES BOOLEAN false non-staged CREATE TABLE 후 후속 메타데이터 업데이트를 건너뜀. 테이블 생성 중에 메타데이터를 완전히 초기화하고 후속 업데이트를 거부하는 카탈로그에는 활성화.
REMOVE_FILES_ON_DELETE BOOLEAN true 테이블이 drop될 때 DuckDB가 스토리지 파일을 제거하는지 제어.
PURGE_REQUESTED BOOLEAN false 테이블을 drop할 때 PurgeRequested 파라미터를 전송.
ENCODE_ENTIRE_PREFIX BOOLEAN false 카탈로그와 통신할 때 전체 경로 접두사를 URL 인코딩.
MAX_TABLE_STALENESS INTERVAL NULL Iceberg REST 카탈로그에 불필요한 요청을 방지. 10 minutes, 30 seconds, 1 year 같은 사람이 읽을 수 있는 interval 문자열을 허용.

ENDPOINT_TYPE(s3_tables 또는 glue)으로 AWS 카탈로그를 attach할 때, DuckDB는 AWS에 적합한 기본값을 적용해요: 명시적으로 설정하지 않는 한 stage_create_tables와 remove_files_on_delete는 false가 되고 purge_requested는 true가 돼요.

다음 옵션은 CREATE SECRET 문에만 전달할 수 있으며 AUTHORIZATION_TYPE이 OAUTH2여야 해요.

Parameter Type Default Description
OAUTH2_GRANT_TYPE VARCHAR NULL OAuth 토큰을 요청할 때의 Grant Type.
OAUTH2_SCOPE VARCHAR NULL 반환된 OAuth 액세스 토큰에 요청된 스코프.

attach된 카탈로그로 작업하기 (Working with an Attached Catalog)

카탈로그가 attach되면 그 테이블에 대해 전체 읽기/쓰기 연산 집합을 실행할 수 있어요.

  • 읽기와 메타데이터: SELECT, AT 절을 사용한 시간 여행(time travel), iceberg_metadata, iceberg_snapshots, 통계 함수. Functions and Settings Reference를 참고해요.
  • 쓰기: CREATE/DROP SCHEMA와 TABLE, 파티셔닝, INSERT, UPDATE, DELETE, MERGE INTO, ALTER TABLE, 테이블 속성, COPY FROM DATABASE. Writing to Iceberg를 참고해요.

메타데이터 함수는 완전히 한정된 테이블 이름을 받아요. 예:

SELECT * FROM iceberg_snapshots(my_catalog.default.t);

특정 카탈로그 예시 (Specific Catalog Examples)

DuckDB는 다양한 Iceberg REST 카탈로그에 attach할 수 있어요. AWS 관리 카탈로그는 AWS 자격 증명과 SigV4 인증이 필요하므로 전용 설정 페이지가 있어요.

나머지 카탈로그는 이 페이지에서 직접 설정해요.

Cloudflare R2 카탈로그 (Cloudflare R2 Catalog)

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

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

getting started의 API 토큰 생성 단계를 따라 토큰을 만들 수 있어요. 그런 다음 다음 명령으로 카탈로그를 attach해요.

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

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

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

CREATE SCHEMA my_r2_catalog.my_schema;
USE my_r2_catalog.my_schema;

Polaris

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

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 카탈로그에 attach하려면 다음 명령이 동작해요.

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 카탈로그에 attach하려면 추가 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해요.

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 스펙 지원이 제한된 카탈로그 (Catalogs with Limited REST Spec Support)

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

Catalog behavior Option to set
staged 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

예를 들어 staged create를 지원하지 않고, 트랜잭션/커밋 엔드포인트를 거부하며, 자체 메타데이터와 스토리지 정리를 관리하는 Unity Catalog Horizon 엔드포인트에 attach하려면:

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
);

제한사항 (Limitations)

DuckDB는 S3, S3 Tables, Google Cloud Storage (GCS)를 백엔드로 하는 Iceberg REST 카탈로그를 지원해요. 다른 스토리지 백엔드에 대한 지원은 아직 제공되지 않아요.

더 알아보기 (Learn more)