IncrementalLightweightOutput: 증분 경량 출력
transforms.api.IncrementalLightweightOutput은 증분 ContainerTransform의 사용자 코드에 주입되는 출력 객체입니다. IncrementalTransformOutput의 일부 API와 기반 foundry.transforms.Dataset에 대한 접근을 제공합니다.
transforms.api.IncrementalLightweightOutput(alias, rid, branch=None)
속성
| 속성 | 의미 |
|---|---|
alias | 데이터셋 별칭 |
branch | 데이터셋 브랜치 |
rid | 데이터셋의 고유 리소스 식별자 |
transaction_rid | 출력 데이터셋의 트랜잭션 RID 문자열 |
path_for_write_table | write_table에서 사용할 데이터셋 파일 경로 |
path_for_object_store_write_table | 출력 트랜잭션에 연결할 가상 객체 저장소 경로 |
가상 객체 저장소 경로는 클라우드 버킷에 직접 연결하는 경로가 아닙니다. 쿼리 엔진의 비동기 최적화 I/O를 위한 로컬 S3 프록시를 가리킵니다.
모드와 빈 출력 읽기
| 메서드 | 반환과 기본값 |
|---|---|
arrow(mode="current", schema=None) | PyArrow Table |
dataframe(mode="current", schema=None) | pandas.DataFrame |
pandas(mode="current", schema=None) | pandas.DataFrame |
polars(lazy=False, mode="current", schema=None) | Polars DataFrame, lazy=True이면 LazyFrame |
path(mode="current") | 기반 파일을 다운로드한 경로 |
filesystem() | FoundryDataSidecarFileSystem |
mode를 받는 메서드는 current, previous, added를 지원하며 기본값은 current입니다. path의 mode 인자는 incremental 데코레이터와 v2_semantics=True가 함께 있을 때만 적용할 수 있습니다. filesystem에는 mode 인자가 정의되어 있지 않습니다.
schema는 FoundryFieldSchema이며 데이터셋이 비어 있을 때만 빈 Table, DataFrame 또는 LazyFrame을 구성하는 데 사용합니다. Spark 출력의 StructType과 구분합니다. 출력과 같은 열 스키마를 가진 실제 데이터셋이 실행 환경에 연결되어 있다면 Dataset.schema에서 해당 객체를 얻을 수 있습니다.
다음 함수의 output은 compute에 주입된 실제 IncrementalLightweightOutput이며 schema_dataset_alias는 출력과 같은 스키마를 가진 데이터셋의 별칭입니다.
from foundry.transforms import Dataset
def read_previous_arrow(output, schema_dataset_alias: str):
expected_schema = Dataset.get(schema_dataset_alias).schema
return output.arrow(mode="previous", schema=expected_schema)
참조 데이터셋과 출력의 실제 스키마가 같아야 합니다. 출력에서 열을 추가하거나 바꾼다면 그 실제 출력 스키마에 맞는 FoundryFieldSchema가 필요합니다. 기존 데이터가 있는 출력을 임의로 형 변환하는 schema 인자로 해석하지 않습니다.
쓰기 메서드
write_dataframe(df, column_description=None, column_descriptions=None)
write_pandas(df, column_description=None, column_descriptions=None)
write_table(df, column_description=None, column_descriptions=None)
호환성을 위해 단수 column_description과 복수 column_descriptions를 모두 받습니다. 설명 맵을 전달할 때는 둘 중 하나만 사용합니다. 단수 이름은 사용 중단 권고 상태이므로 새 코드에는 column_descriptions를 사용합니다.
write_dataframe은 pandas.DataFrame, pyarrow.Table, polars.DataFrame, polars.LazyFrame, duckdb.DuckDBPyRelation 또는 pathlib.Path 데이터를 기록하고 None을 반환합니다. write_pandas는 pandas.DataFrame을 기록합니다.
write_table은 같은 데이터 유형을 받아 데이터 업로드, 스키마 추론 및 등록, 열 설명 갱신을 수행하고 None을 반환합니다. 기존 스키마가 있으면 추론한 스키마로 덮어씁니다. df에 None을 주면 이 트랜잭션에 이미 쓴 데이터에서 스키마만 추론합니다. 새 데이터를 업로드하지 않고 메타데이터만 마무리할 때는 put_metadata도 사용할 수 있습니다.
column_descriptions는 열 이름에서 설명 문자열로의 맵입니다. DataFrame의 열과 교집합에 해당하는 설명만 반영하며 각 설명은 800자 이하여야 합니다.
put_metadata(column_descriptions=None)
원시 Parquet 파일을 업로드한 출력을 마무리합니다. 업로드한 Parquet에서 Foundry 스키마를 추론하여 등록하고 기존 스키마가 있으면 덮어쓰며 열 설명을 갱신합니다. 적어도 하나의 Parquet 파일 업로드가 성공한 뒤 호출해야 합니다. 성공한 업로드 전에 호출하면 오류가 발생합니다.
설명 맵은 데이터셋 열과 교집합을 사용하고 각 설명은 800자 이하여야 합니다.
read_unstaged_dataset_as_polars_lazy()
로컬 데이터셋 버전을 Polars LazyFrame으로 읽습니다. 데이터셋의 expectation 계산에 사용하며, 검사 실패가 빌드를 중단할 수 있으므로 커밋 전에 수행해야 합니다.
set_mode(mode)
replace는 기록한 데이터로 데이터셋을 대체합니다. modify는 데이터를 추가하고 기존 파일을 덮어쓸 수 있습니다. append는 데이터를 추가하되 기존 파일을 덮어쓰지 않습니다. 데이터를 쓴 뒤에는 쓰기 모드를 변경할 수 없습니다.
설명 이름의 호환 형태와 경량 출력의 전체 API 범위는 LightweightOutput에서도 확인할 수 있습니다.