Dataset: 데이터셋 뷰의 표와 파일
foundry.transforms.Dataset은 Foundry 데이터셋 뷰의 기반 파일을 나타냅니다. 이 클래스의 이름 공간은 foundry.transforms입니다. 생성자를 직접 호출하기보다 정적 팩터리 Dataset.get(alias)를 사용하는 것이 권장됩니다.
foundry.transforms.Dataset(alias)
Dataset.get(alias)
get은 문자열 alias를 받아 새로운 Dataset 인스턴스를 반환합니다. 별칭은 실행 환경에 연결한 데이터셋을 가리킵니다.
속성
| 속성 | 형식 | 의미 |
|---|---|---|
alias | str | 데이터셋 별칭 |
schema | FoundryFieldSchema | 데이터셋의 Foundry 필드 스키마 |
write_table_path | str | write_table에서 사용할 데이터셋 파일의 로컬 디스크 경로 |
lazy_write_table_path | str | 출력 트랜잭션에 연결할 버킷의 객체 저장소 경로 |
read_table
read_table(columns=None, row_limit=None, format="dataframe", mode="current",
force_dataset_download=False, schema=None)
| 인자 | 형식 | 기본값과 의미 |
|---|---|---|
columns | list[str] | 읽을 열 일부. 기본값 None |
row_limit | int | 읽을 최대 행 수. 기본값 None |
format | str | 반환 형식. 기본값 dataframe |
mode | str | current, previous, added 중 하나. 기본값 current |
force_dataset_download | bool | 로컬에 있어도 다시 다운로드할지 여부. 기본값 False |
schema | FoundryFieldSchema | 빈 증분 출력을 읽을 때 적용할 스키마. 기본값 None |
| format | 반환값 |
|---|---|
arrow | pyarrow.Table |
pandas | pandas.DataFrame |
dataframe | pandas의 별칭, 기본값 |
polars | polars.DataFrame |
lazy-polars | polars.LazyFrame |
path | 원시 데이터셋 파일을 가리키는 경로 문자열 |
columns, row_limit 또는 where 필터를 지정하면 format은 arrow, dataframe, pandas, polars 중 하나여야 하며 mode는 current여야 합니다. 이 조건이 있는 읽기에 lazy-polars나 path를 조합하지 않습니다.
where, select와 limit
where는 Column.get으로 만든 행 필터를 저장하고 Dataset을 반환하여 호출을 연결할 수 있게 합니다. 실제 필터는 read_table을 호출할 때 적용합니다.
Column의 지원 연산은 ==, !=, >, >=, <, <=, .isnull(), .isin(values), .between(lower, upper)입니다. &, |, ~로 각각 AND, OR, NOT을 조합합니다.
my_dataset 별칭에 age 열이 있는 가상 예시입니다.
from foundry.transforms import Column, Dataset
dataset = Dataset.get("my_dataset")
filtered = dataset.where(Column.get("age") > 18)
result = filtered.read_table(format="pandas")
| 메서드 | 인자 | 반환과 동작 |
|---|---|---|
where(operand_filter) | Column.get 기반 필터 | 필터가 적용될 Dataset |
select(*column_names) | 문자열 열 이름들 | 열 선택을 적용한 Dataset |
limit(row_limit) | int | 최대 읽기 행 수를 설정한 Dataset |
select나 limit으로 선택 조건을 설정한 경우에도 위 read_table의 형식 및 current 모드 조건을 따릅니다.
write_table
write_table(df, column_descriptions=None)
표 데이터를 업로드하고 스키마를 추론하며 열 설명 메타데이터를 갱신합니다. 반환값은 None입니다.
지원 입력은 pandas.DataFrame, pyarrow.Table, polars.DataFrame, DuckDB PyRelation과 원시 데이터셋 경로입니다. 경로는 문자열 또는 pathlib.Path로 전달하며 write_table_path에 맞는 데이터셋 경로를 사용합니다. 읽기 형식에 LazyFrame이 있다고 해서 이 메서드의 모든 입력 형식과 같다고 해석하지 않습니다.
column_descriptions는 열 이름에서 문자열 설명으로의 맵입니다. DataFrame 열과 교집합에 해당하는 설명을 반영하며 각 설명은 800자 이하여야 합니다.
원시 Parquet 업로드 후 put_metadata
put_metadata(column_descriptions=None)
원시 Parquet 파일을 올린 데이터셋을 마무리합니다. 업로드한 Parquet에서 Foundry 스키마를 추론하고 열 설명을 갱신하며 None을 반환합니다. 하나 이상의 Parquet 파일 업로드가 성공한 뒤 호출해야 하며, 그 전에 호출하면 오류가 발생합니다.
column_descriptions는 데이터셋 열과 교집합에 해당하는 이름을 사용하고 각 설명은 800자 이하여야 합니다.
set_write_mode
set_write_mode(mode)
쓰기 모드를 바꾸고 None을 반환합니다. 데이터를 쓴 뒤에는 모드를 변경할 수 없습니다.
| mode | 동작 |
|---|---|
replace | 기록한 데이터가 데이터셋을 대체 |
modify | 데이터를 추가하며 기존 파일도 덮어쓸 수 있음 |
append | 데이터를 추가하되 기존 파일을 덮어쓰지 않음 |
파일 목록과 업로드
| 메서드 | 인자와 기본값 | 반환 |
|---|---|---|
files(mode="current", show_hidden_files=False) | mode는 current, previous, added. 숨김 파일 표시 기본값 False | FileCollection |
upload_file(path, logical_path=None) | path는 업로드할 로컬 파일 경로. logical_path는 데이터셋 안의 대상 경로 | 업로드한 데이터셋 파일 이름 문자열 |
upload_directory(local_dir_path) | 로컬 디렉터리 안의 모든 파일을 재귀적으로 업로드 | 로컬 파일 경로에서 데이터셋 파일 경로로의 dict[str, str] |
upload_file에서 logical_path를 생략하면 로컬 파일과 같은 이름으로 데이터셋 루트에 업로드합니다. files의 FileCollection과 FileSystem.files의 PySpark DataFrame 반환은 서로 다른 인터페이스입니다.
abort
abort는 이 데이터셋에 대한 모든 작업을 중단하고 중단된 Dataset을 반환합니다. 호출하기 전에 쓴 데이터뿐 아니라 호출한 뒤 쓰는 데이터도 무시합니다. 작업 실행 자체와 모든 출력 트랜잭션을 중단하는 맥락의 abort_job과는 대상 범위를 구분합니다.