Iceberg 증분 Python API
Iceberg 입력이나 출력을 증분으로 사용하려면 v2 증분 의미를 활성화하고, 처리할 변경 유형에 맞는 읽기 모드와 런타임 핸들을 선택합니다.
데코레이터
| 인수 | 계약 |
|---|---|
v2_semantics | 반드시 True여야 합니다. Iceberg 입력과 출력은 v2 증분 의미만 지원합니다. |
require_incremental | 기본값은 False입니다. True이면 증분 해석 실패 시 전체 비증분으로 전환하지 않고 실패합니다. |
semantic_version | 기존 출력이 더 이상 유효하지 않게 되는 로직 변경에 맞춰 올립니다. 변경하면 다음 실행을 비증분으로 만듭니다. |
snapshot_inputs | 전체 재작성이 기존 결과를 무효화하지 않는 참조 입력 이름을 지정합니다. 해당 입력은 항상 전체를 읽습니다. |
데코레이터 뒤에 .with_table_incremental_options(table_read_mode=...)를 연결하여 모드를 고릅니다. 이 메서드는 transforms-tables 0.1390.0 이상이 필요합니다.
| 모드 | 처리 범위 |
|---|---|
append_only | 기본값입니다. Append와 Replace 스냅샷을 증분 처리합니다. 구간에 Overwrite 또는 Delete가 있으면 비증분 전환 또는 require_incremental에 따른 실패가 발생합니다. |
changelog | Append, Replace, Overwrite와 Delete의 변경 로그를 처리합니다. .changelog() 호출에 필요하며 Spark 변환에서만 사용할 수 있습니다. |
실제 delete file이 있는 merge-on-read 스냅샷의 제한은 저장 전략을 함께 적용합니다.
런타임 핸들
단일 노드는 IncrementalIcebergInput과 IncrementalIcebergOutput, Spark는 IncrementalTableTransformInput과 TableTransformOutput을 사용합니다.
증분 실행에서 입력의 일반 읽기는 기본적으로 추가된 행을 반환합니다. 비증분 실행에서는 전체 입력을 처리해야 하며, Foundry 출력 API도 그 실행 모드에 맞춰 동작합니다.
| 연산 라이브러리 | 일반 증분 읽기 |
|---|---|
| Polars | source.polars() |
| DuckDB | source.arrow()를 SQL 연결에 등록 |
| pandas | source.pandas() |
| PySpark | source.dataframe() |
Spark에서 식별자 기반 변경 로그는 source.changelog(["id"])처럼 요청합니다. 일반 추가 행 읽기와 별도의 변경 로그 인터페이스입니다.
추가 전용 변환 예제
입력에 문자열 status 열이 있는 가상 경로 예제입니다. 실제 테이블 경로로 바꾸어 사용합니다.
import polars as pl
from transforms.api import incremental, transform
from transforms.tables import IncrementalIcebergInput, IncrementalIcebergOutput, TableInput, TableOutput
@incremental(v2_semantics=True).with_table_incremental_options(table_read_mode="append_only")
@transform.using(
source=TableInput("/Examples/iceberg/append-source"),
output=TableOutput("/Examples/iceberg/active-append"),
)
def append_active(source: IncrementalIcebergInput, output: IncrementalIcebergOutput):
active = source.polars().filter(pl.col("status") == "active")
output.write_table(active)
append_only를 생략해도 기본 모드는 같습니다. 첫 실행과 비증분 전환의 전체 처리, 네이티브 append의 분기 및 Changelog 경로는 증분 코드 예제에 있습니다. 출력이 필터링된 상태를 유지해야 할 때는 CDC의 삭제 전파를 확인합니다.