로컬 Jupyter에서 Iceberg 테이블 만들기

로컬 Jupyter 노트북에서 PyIceberg를 사용하면 Foundry 카탈로그의 테이블을 만들고 데이터를 추가한 뒤 다시 읽을 수 있습니다. 카탈로그에 인증할 권한과 카탈로그 및 저장소 양쪽의 네트워크 접근이 필요합니다.

PyIceberg와 PyArrow를 준비하고, 마지막 Pandas 읽기를 사용할 경우 pandas도 준비합니다. 클라이언트에는 원래 클라우드 저장소 키를 넣지 않고 카탈로그의 단기 인증 정보 위임을 사용합니다.

이 예제는 Foundry의 REST 카탈로그 경로를 사용합니다. 로컬 SqlCatalog 같은 다른 카탈로그의 지원과 구분해야 합니다. 특히 v3에서는 테이블 생성 요청을 보낼 수 있다는 사실만으로 클라이언트의 데이터 파일 쓰기까지 지원된다고 판단하지 않습니다. 사용하는 PyIceberg 버전이 대상의 형식 버전과 CSE 읽기 및 쓰기를 지원하는지 확인합니다.

이름 공간과 Compass 경로

점으로 구분한 Namespace.Project.Dir.Table 식별자는 Compass의 Namespace/Project/Dir/Table 경로에 대응합니다. 개별 이름 자체에 점이 들어가면 PyIceberg의 튜플 식별자를 사용하여 수준을 구분할 수 있습니다.

테이블을 만들 프로젝트 및 이름 공간이 존재하고, 해당 위치에 테이블을 생성할 권한이 있어야 합니다. 기존 테이블을 바꾸는 요청과 새 이름으로 생성하는 요청을 구분합니다.

Parquet에서 생성하고 추가하기

다음 함수에는 실제 Foundry 기본 URL, 로컬 Parquet 경로, 이름 공간의 각 수준과 새 테이블 이름을 전달합니다. 예를 들어 이름 공간 수준은 ("Namespace", "Project", "Folder")처럼 지정합니다. 이 값들은 실제 Compass 위치에 맞춥니다.

from getpass import getpass
import pyarrow.parquet as pq
from pyiceberg.catalog import load_rest


def create_from_local_parquet(
    foundry_url: str,
    parquet_path: str,
    namespace_parts: tuple,
    table_name: str,
):
    catalog = load_rest("foundry", {
        "uri": foundry_url.rstrip("/") + "/iceberg",
        "token": getpass("Foundry 토큰: "),
    })
    data = pq.read_table(parquet_path)
    identifier = tuple(namespace_parts) + (table_name,)
    table = catalog.create_table(identifier, schema=data.schema)
    tables_after_creation = catalog.list_tables(tuple(namespace_parts))
    table.append(data)
    dataframe = table.scan().to_pandas()
    return tables_after_creation, dataframe

create_table 직후에는 스키마가 있는 빈 테이블이 생기므로 목록에서 확인할 수 있습니다. append가 실제 데이터를 추가합니다. 목록 조회에는 테이블 이름을 제외한 이름 공간을 사용합니다.

이 코드는 로컬 Parquet를 Arrow 메모리에 읽고, 마지막에 테이블 데이터를 Pandas 메모리로 읽습니다. 시험 데이터의 크기를 고려합니다. 실행하면 실제 Foundry 테이블과 데이터가 생성되며, 생성 후 append 전에 실패하면 빈 테이블이 남을 수 있습니다. 외부 클라이언트의 여러 호출을 Foundry 빌드의 작업 단위 트랜잭션으로 취급하지 않습니다.

운영 연결에는 사용자 토큰 대신 OAuth2 인증을 사용하는 것이 권장됩니다. 같은 카탈로그 인터페이스를 사용하므로 인증 구성만 해당 클라이언트 방식에 맞게 준비합니다.