Iceberg 테이블 속성과 기본값

Iceberg 메타데이터의 table properties는 키와 값의 맵입니다. 생성 시 초기값을 정하고 이후 ALTER TABLE ... SET TBLPROPERTIES로 변경할 수 있습니다. Foundry 카탈로그가 관리하는 속성 중 일부는 사용자가 바꿀 수 없습니다.

write.metadata.*는 메타데이터 파일 관리 설정이며, 데이터 스냅샷의 보존을 정하는 history.expire.*와 구분합니다. 이전 메타데이터 버전 수를 데이터 스냅샷 보존 개수로 해석하지 않습니다.

Foundry 속성

Iceberg 속성의 Foundry 기본값

Foundry가 정한 값은 공개 Iceberg 기본값보다 우선합니다. 별도로 설정하지 않은 다른 속성은 Iceberg 명세의 기본값을 사용합니다. Foundry 기본값은 바뀔 수 있으므로 수정 가능한 속성 중 일정한 값이 필요하면 명시적으로 지정합니다. 수정 금지 항목을 이 방법으로 덮어쓸 수는 없습니다.

설정 시점

변환에서 출력 테이블을 먼저 쓴 다음 속성을 설정합니다. 테이블이 존재하기 전에 설정하면 실패할 수 있고, write_dataframe의 replace가 나중에 실행되면 지정한 속성이 기본값으로 바뀔 수 있습니다.

다음 예제는 merge-on-read 관련 속성과 최대 스냅샷 나이를 설정합니다. history.expire.max-snapshot-age-ms = 0은 기본값이 아닙니다. 보호되지 않은 과거 스냅샷이 빠르게 만료 대상이 될 수 있으므로 실제 보존 및 유지보수 정책에 맞게 선택합니다.

Polars 및 PyIceberg 테이블 인터페이스

import polars as pl
from transforms.api import transform
from transforms.tables import IcebergOutput, TableOutput


@transform.using(output=TableOutput("/Examples/iceberg/table-properties"))
def set_polars_table_properties(output: IcebergOutput) -> None:
    output.write_table(pl.DataFrame({"phrase": ["Hello", "World"]}))
    table = output.table()
    with table.transaction() as transaction:
        transaction.set_properties(**{
            "write.delete.mode": "merge-on-read",
            "write.update.mode": "merge-on-read",
            "write.merge.mode": "merge-on-read",
            "history.expire.max-snapshot-age-ms": "0",
        })

PySpark

from transforms.api import TransformContext, transform
from transforms.tables import TableOutput, TableTransformOutput


@transform(output=TableOutput("/Examples/iceberg/spark-table-properties"))
def set_spark_table_properties(ctx: TransformContext, output: TableTransformOutput):
    frame = ctx.spark_session.createDataFrame([["Hello"], ["World"]], schema=["phrase"])
    output.write_dataframe(frame)
    ctx.spark_session.sql(f"""
        ALTER TABLE {output.identifier}
        SET TBLPROPERTIES (
            'write.delete.mode' = 'merge-on-read',
            'write.update.mode' = 'merge-on-read',
            'write.merge.mode' = 'merge-on-read',
            'history.expire.max-snapshot-age-ms' = '0'
        )
    """)

출력 경로와 예시 데이터는 가상 값입니다. 같은 속성 변경을 Maintenance의 Custom SQL에서 실행할 수도 있습니다. 해당 작성 권한과 브랜치 보호를 충족해야 합니다.