TL;DR

  • Boring Catalog는 전용 카탈로그 서비스 없이 로컬 디스크나 S3 등에서 단일 JSON 파일로 Apache Iceberg 카탈로그 상태를 관리하는 경량 구현체임.
  • 네임스페이스와 테이블 정보를 JSON 파일에 저장하고, S3에서는 조건부 쓰기로 동시 수정을 방지함.
  • ice 명령줄 인터페이스(CLI)와 DuckDB를 통해 테이블 및 메타데이터를 탐색하고, 테이블을 커밋하거나 변경 이력을 확인할 수 있음.
  • Python API로 네임스페이스와 테이블을 관리하고, pyarrow 데이터를 Iceberg 테이블에 추가할 수 있음.
  • 카탈로그 JSON 파일 위치와 웨어하우스를 각각 설정할 수 있으며, 로드맵에는 MERGE·파티션 사양 관련 CLI 개선과 REST API 제공이 포함됨.

Boring Catalog

  • Boring Catalog는 S3, 로컬 디스크 또는 fsspec 호환 저장소에 있는 단일 JSON 파일을 사용하는 경량 파일 기반 Iceberg 카탈로그 구현체임.
  • boringdata.io는 데이터 스택 템플릿을 제공하는 사이트임.

Boring Catalog를 사용하는 이유

  • 전용 카탈로그 서비스를 호스팅하거나 유지 관리할 필요가 없음.
  • 사용과 이해가 쉬우며 Iceberg를 시작하기에 적합함.
  • DuckDB CLI를 통해 Iceberg 테이블과 메타데이터를 쉽게 탐색할 수 있음.

작동 방식

  • 모든 Iceberg 카탈로그 상태를 단일 JSON 파일에 저장함.
  • 네임스페이스와 테이블을 해당 파일에서 추적함.
  • 카탈로그를 S3에 저장하는 경우 조건부 쓰기를 사용해 동시 수정을 방지함.
  • 프로젝트 디렉터리의 .ice/index 파일에 카탈로그 설정을 저장함.
  • catalog_uri: 카탈로그 JSON 파일 경로
  • catalog_name: 카탈로그의 논리적 이름
  • properties: 웨어하우스 위치 등의 추가 속성

설치

  • pip install boringcatalog 명령으로 설치함.

빠른 시작

카탈로그 초기화

  • ice init 명령으로 카탈로그를 초기화함.
  • 초기화하면 다음 두 파일이 생성됨.
  • warehouse/catalog/catalog_boring.json: 카탈로그 파일
  • .ice/index: 카탈로그 위치를 가리키는 파일로, Iceberg용 Git 인덱스 파일과 유사함.
  • Iceberg 데이터와 카탈로그 파일의 원격 위치도 지정할 수 있으며, 예시는 ice init -p warehouse=s3://mybucket/mywarehouse임.
  • 카탈로그 파일이나 웨어하우스에 s3:// 경로를 사용하는 경우 CLI 환경이 AWS에 인증되어 있어야 함.
  • AWS 프로필 설정 예시는 export AWS_PROFILE=your-provider임.
  • CLI가 S3 리소스에 접근하려면 유효한 AWS 자격 증명이 구성되어 있어야 함.

테이블 커밋

DuckDB로 Iceberg 탐색

  • ice duck 명령을 실행하면 모든 테이블과 네임스페이스를 가리키는 대화형 DuckDB 세션이 열림.
  • 예시 쿼리는 다음과 같음.
  • show;: 모든 테이블 표시
  • select * from catalog.namespaces;: 네임스페이스 목록 조회
  • select * from catalog.tables;: 테이블 목록 조회
  • select * from <namespace>.<table>;: Iceberg 테이블 조회

Python 사용

  • from boringcatalog import BoringCatalog로 BoringCatalog를 가져오며, 기본 생성자는 현재 작업 디렉터리의 .ice/index를 자동으로 감지함.
  • BoringCatalog(name="mycat", uri="path/to/catalog.json")처럼 카탈로그 이름과 URI를 지정할 수도 있음.
  • create_namespace("my_namespace"), create_table("my_namespace", "my_table"), load_table("my_namespace.my_table")로 네임스페이스와 테이블을 다룸.
  • pyarrow.parquet로 /tmp/yellow_tripdata_2023-01.parquet를 읽은 뒤, catalog.load_table(("ice_default", "my_table"))로 테이블을 불러와 데이터를 추가함.

사용자 지정 초기화와 카탈로그 위치

  • 카탈로그 메타데이터(JSON 파일)와 Iceberg 데이터(웨어하우스)의 저장 위치를 각각 설정할 수 있음.
  • warehouse 속성은 Iceberg 테이블 데이터가 저장될 위치를 지정함.
  • --catalog 옵션은 카탈로그 JSON 파일의 정확한 경로를 지정함.
  • 두 옵션을 함께 사용하면 카탈로그 파일은 지정한 경로에 생성되고, 테이블 데이터는 웨어하우스에 저장됨.

예시

  • ice init: 카탈로그 파일은 warehouse/catalog/catalog_boring.json, 웨어하우스는 warehouse/이며, 로컬에서 간단히 사용하는 구성임.
  • ice init -p warehouse=...: 카탈로그 파일은 <warehouse>/catalog/catalog_boring.json, 웨어하우스는 <warehouse>/이며, 사용자 지정 웨어하우스 구성임.
  • ice init --catalog ...: 카탈로그 파일은 <custom>.json이며, 웨어하우스는 테이블 생성 시 지정하는 구성임.
  • ice init --catalog ... -p warehouse=...: 카탈로그 파일은 <custom>.json, 웨어하우스는 <warehouse>/이며, 두 위치를 모두 지정하는 구성임.
  • ice init --catalog ... --catalog-name ...: 카탈로그 파일은 <custom>.json이며, 웨어하우스는 테이블 생성 시 지정하는 사용자 지정 이름 및 파일 구성임.

예외 사례와 수동 편집

  • 카탈로그 이름은 기본적으로 boring이며, --catalog-name으로 사용자 지정할 수 있음. 사용자 지정 경로를 지정하지 않으면 이 이름이 카탈로그 JSON과 파일 이름에 사용됨.
  • 같은 디렉터리에서 ice init을 여러 번 실행하면 .ice/index 파일이 새 설정으로 덮어써짐. 프로젝트가 다른 카탈로그를 가리키도록 바꿀 때 유용하지만 기존 데이터를 마이그레이션하거나 병합하지는 않음.
  • 고급 사용자는 .ice/index를 직접 편집해 다른 카탈로그 파일을 지정하거나 카탈로그 이름을 변경할 수 있음.
  • 수동 편집 시 catalog_uri와 catalog_name 필드가 실제 카탈로그 JSON 파일과 일치해야 함. warehouse 속성을 설정해도 catalog_uri를 갱신하지 않으면 Boring Catalog는 인덱스 파일의 catalog_uri를 계속 사용함.

로드맵

  • MERGE 작업과 파티션 사양 등을 지원하도록 CLI 개선
  • 테이블 스키마와 파티션 사양 등의 정보를 제공하도록 CLI 개선
  • AWS, Snowflake 등과 통합하기 위한 REST API 공개