Relational API

Relational API는 쿼리를 점진적으로 구성하는 데 사용할 수 있는 대안 API예요. API는 DuckDBPyRelation 노드 중심으로 이뤄져 있어요. relation은 SQL 쿼리의 기호적 표현으로 볼 수 있어요.

출처: 문서

본문

지연 평가 (Lazy Evaluation)

relation은 실행을 트리거하는 메서드가 호출될 때까지 어떤 데이터도 보유하지 않고 아무것도 실행하지 않아요.

예를 들어 10억 행을 로드하는 relation을 만든다고 해볼게요:

import duckdb

duckdb_conn = duckdb.connect()

rel = duckdb_conn.sql("from range(1_000_000_000)")

실행 순간에 rel은 어떤 데이터도 보유하지 않고 데이터베이스에서 데이터를 검색하지 않아요.

rel.show()를 호출하거나 그냥 터미널에서 rel을 인쇄하면 처음 10K 행이 가져와져요. 10K 행보다 많으면 출력 창에 >9999 행이 표시돼요 (relation의 행 수를 알 수 없기 때문).

출력 메서드를 호출하면 데이터가 검색되어 지정된 형식으로 저장돼요:

rel.to_table("example_rel")

# 100% ▕████████████████████████████████████████████████████████████▏

Relation 생성 (Relation Creation)

이 섹션은 relation이 어떻게 생성되는지에 대한 세부사항을 포함해요. 메서드들은 지연 평가돼요.

이름	설명
`from_arrow`	Arrow 객체에서 relation 객체 생성
`from_csv_auto`	'name'의 CSV 파일에서 relation 객체 생성
`from_df`	df의 DataFrame에서 relation 객체 생성
`from_parquet`	Parquet 파일들에서 relation 객체 생성
`from_query`	SQL 쿼리 실행. SELECT 구문이면 주어진 SQL 쿼리에서 relation 객체 생성, 그렇지 않으면 쿼리를 그대로 실행
`query`	SQL 쿼리 실행. SELECT 구문이면 주어진 SQL 쿼리에서 relation 객체 생성, 그렇지 않으면 쿼리를 그대로 실행
`read_csv`	'name'의 CSV 파일에서 relation 객체 생성
`read_json`	'name'의 JSON 파일에서 relation 객체 생성
`read_parquet`	Parquet 파일들에서 relation 객체 생성
`sql`	SQL 쿼리 실행. SELECT 구문이면 주어진 SQL 쿼리에서 relation 객체 생성, 그렇지 않으면 쿼리를 그대로 실행
`table`	'tbl_name'이라는 이름의 테이블에서 relation 객체 생성
`table_function`	주어진 인자로 'function_name'이라는 이름의 테이블 함수에서 relation 객체 생성
`values`	주어진 값들에서 relation 객체 생성
`view`	'view_name'이라는 이름의 뷰에서 relation 객체 생성

`from_arrow`

서명: from_arrow(arrow_object) -> DuckDBPyRelation
설명: Arrow 객체에서 relation 객체 생성
파라미터: arrow_object: Arrow 객체
예시: rel = duckdb_conn.from_arrow(arrow_table) — Arrow 테이블에서 relation 생성

`from_parquet`

서명: from_parquet(file_name, binary_as_string=False, file_number=-1, row_group_number=-1) -> DuckDBPyRelation
설명: Parquet 파일들에서 relation 객체 생성
파라미터: file_name: Parquet 파일 경로, binary_as_string: BINARY 컬럼을 VARCHAR로 파싱, file_number: 파싱할 파일 수(-1이면 전부), row_group_number: 파싱할 row group 수
예시: rel = duckdb_conn.from_parquet('data.parquet') — Parquet 파일에서 relation 생성

`sql`

서명: sql(query, params=None, multiple_parameter_sets=False) -> DuckDBPyRelation
설명: SQL 쿼리를 실행한다. SELECT 구문이면 주어진 SQL 쿼리에서 relation 객체를 생성하고, 그렇지 않으면 쿼리를 그대로 실행한다.
예시: rel = duckdb_conn.sql('SELECT * FROM range(5)') — 쿼리에서 relation 생성

`table`

서명: table(table_name) -> DuckDBPyRelation
설명: 'tbl_name'이라는 이름의 테이블에서 relation 객체 생성
예시: rel = duckdb_conn.table('table_1') — 'table_1' 테이블에서 relation 생성

`values`

서명: values(values) -> DuckDBPyRelation
설명: 주어진 값들에서 relation 객체 생성
예시: rel = duckdb_conn.values([1, 2, 3]) — 값들에서 relation 생성

Relation 정의 세부사항

이 섹션은 relation을 검사하는 방법에 대한 세부사항을 포함해요.

이름	설명
`alias`	현재 별칭의 이름 얻기
`columns`	relation의 컬럼 이름 목록 반환
`describe`	relation의 각 컬럼에 기본 통계(예: min, max)와 NULL 존재 여부 제공
`description`	결과의 설명 반환
`dtypes`	relation의 컬럼 타입 목록 반환
`explain`	`explain(self: _duckdb.DuckDBPyRelation, type: _duckdb.ExplainType = 'standard') -> str`
`query`	relation 객체를 참조하는 virtual_table_name 뷰에서 sql_query에 주어진 SQL 쿼리 실행
`set_alias`	relation 객체를 새 별칭으로 이름 변경
`shape`	relation의 행 수, 컬럼 수의 튜플
`show`	데이터 요약 표시
`sql_query`	relation과 동등한 SQL 쿼리 얻기
`type`	relation의 타입 얻기
`types`	relation의 컬럼 타입 목록 반환

변환 (Transformation)

이 섹션은 쿼리를 이어 붙이는 데 사용할 수 있는 메서드를 포함해요. 메서드들은 지연 평가돼요.

이름	설명
`aggregate`	relation에서 선택적 그룹 group_expr로 집계 aggr_expr 계산
`apply`	relation에서 선택적 그룹으로 단일 컬럼 또는 컬럼 목록의 함수 계산
`cross`	두 관계 객체의 교차/데카르트 곱 생성
`except_`	이 relation 객체와 other_rel의 다른 relation 객체의 차집합 생성
`filter`	filter_expr의 필터로 relation 객체 필터링
`insert`	주어진 값을 relation에 삽입
`insert_into`	relation 객체를 table_name이라는 기존 테이블에 삽입
`intersect`	이 relation 객체와 other_rel의 다른 relation 객체의 교집합 생성
`join`	join_condition의 조인 조건 표현식으로 이 relation 객체를 other_rel의 다른 relation 객체와 조인. 지원되는 타입: 'inner', 'left', 'right', 'outer', 'semi', 'anti'
`limit`	offset에서 시작해 이 relation 객체에서 처음 n행만 검색
`map`	relation에 전달된 함수 호출
`order`	order_expr로 relation 객체 재정렬
`project`	project_expr의 프로젝션으로 relation 객체 프로젝션
`select`	project_expr의 프로젝션으로 relation 객체 프로젝션
`sort`	제공된 표현식으로 relation 객체 재정렬
`union`	이 relation 객체와 other_rel의 다른 relation 객체의 합집합 생성
`update`	제공된 표현식으로 주어진 relation 업데이트

예를 들어 filter와 project로 쿼리를 이어 붙일 수 있어요:

rel = duckdb_conn.table('flights').filter('origin = \'SEA\'').project('dest, arrivaldelay')

join으로 두 relation을 조인할 수 있어요:

rel1 = duckdb_conn.table('flights').select('origin, dest')
rel2 = duckdb_conn.table('flights2').select('origin, dest')
rel = rel1.join(rel2, 'origin = dest', 'inner')

함수 (Functions)

이 섹션은 relation에 적용해 (스칼라) 결과를 얻을 수 있는 함수를 포함해요. 함수들은 지연 평가돼요.

이름	설명
`any_value`	주어진 표현식에서 첫 번째 non-null 값 반환
`arg_max`	값 컬럼에 대한 최대값을 가진 행을 찾고 그 행의 인자 컬럼 값을 반환
`arg_min`	값 컬럼에 대한 최소값을 가진 행을 찾고 그 행의 인자 컬럼 값을 반환
`avg`	주어진 표현식의 평균 계산
`bit_and`	주어진 표현식에 존재하는 모든 비트의 비트 AND 계산
`bit_or`	주어진 표현식에 존재하는 모든 비트의 비트 OR 계산
`bit_xor`	주어진 표현식에 존재하는 모든 비트의 비트 XOR 계산
`bitstring_agg`	주어진 표현식의 각 고유 값에 비트가 설정된 bitstring 계산
`bool_and`	주어진 표현식에 존재하는 모든 값의 논리 AND 계산
`bool_or`	주어진 표현식에 존재하는 모든 값의 논리 OR 계산
`count`	주어진 표현식에 존재하는 요소 수 계산
`cume_dist`	파티션 내 누적 분포 계산
`dense_rank`	파티션 내 dense rank 계산
`distinct`	이 relation 객체에서 고유한 행 검색
`favg`	더 정확한 부동소수점 합산(Kahan Sum)으로 주어진 표현식의 평균 계산
`first`	주어진 표현식의 첫 번째 값 반환
`first_value`	그룹 또는 파티션 내 첫 번째 값 계산
`fsum`	더 정확한 부동소수점 합산(Kahan Sum)으로 주어진 표현식의 합 계산
`geomean`	주어진 표현식에 존재하는 모든 값에 대한 기하 평균 계산
`histogram`	주어진 표현식에 존재하는 모든 값에 대한 히스토그램 계산
`lag`	파티션 내 lag 계산
`last`	주어진 표현식의 마지막 값 반환
`last_value`	그룹 또는 파티션 내 마지막 값 계산
`lead`	파티션 내 lead 계산
`list`	주어진 표현식에 존재하는 모든 값을 포함하는 리스트 반환
`max`	주어진 표현식에 존재하는 최대값 반환
`mean`	주어진 표현식의 평균 계산
`median`	주어진 표현식에 존재하는 모든 값에 대한 중앙값 계산
`min`	주어진 표현식에 존재하는 최소값 반환
`mode`	주어진 표현식에 존재하는 모든 값에 대한 최빈값 계산
`n_tile`	파티션을 num_buckets로 최대한 균등하게 분할
`nth_value`	파티션 내 n번째 값 계산
`percent_rank`	파티션 내 상대 순위 계산
`product`	주어진 표현식에 존재하는 모든 값의 곱 반환
`quantile`	주어진 표현식에 대한 정확한 분위수 값 계산
`quantile_cont`	주어진 표현식에 대한 보간 분위수 값 계산
`quantile_disc`	주어진 표현식에 대한 정확한 분위수 값 계산
`rank`	파티션 내 순위 계산
`rank_dense`	파티션 내 dense rank 계산
`row_number`	파티션 내 행 번호 계산
`select_dtypes`	타입을 기반으로 필터링하여 relation에서 컬럼 선택
`select_types`	타입을 기반으로 필터링하여 relation에서 컬럼 선택
`std`	주어진 표현식의 표본 표준편차 계산
`stddev`	주어진 표현식의 표본 표준편차 계산
`stddev_pop`	주어진 표현식의 모집단 표준편차 계산
`stddev_samp`	주어진 표현식의 표본 표준편차 계산
`string_agg`	주어진 표현식에 존재하는 값을 구분자로 연결
`sum`	주어진 표현식에 존재하는 모든 값의 합 계산
`unique`	컬럼의 고유 값 반환
`value_counts`	주어진 표현식에 존재하는 요소 수 계산, 원래 표현식도 프로젝션
`var`	주어진 표현식의 표본 분산 계산
`var_pop`	주어진 표현식의 모집단 분산 계산
`var_samp`	주어진 표현식의 표본 분산 계산
`variance`	주어진 표현식의 표본 분산 계산

출력 (Output)

이 섹션은 SQL 실행을 트리거하고 데이터를 검색하는 함수를 포함해요.

이름	설명
`arrow`	to_arrow_reader()의 별칭. to_arrow_reader()를 권장해요.
`close`	결과 닫기
`create`	relation 객체의 내용으로 table_name이라는 새 테이블 생성
`create_view`	relation 객체를 참조하는 view_name이라는 뷰 생성
`df`	모든 행을 pandas DataFrame으로 실행·fetch
`execute`	relation을 결과 집합으로 변환
`fetch_arrow_reader`	모든 행을 산출하는 Arrow Record Batch Reader 실행·반환
`fetch_arrow_table`	모든 행을 Arrow Table로 실행·fetch
`fetch_df_chunk`	행 청크 실행·fetch
`fetch_record_batch`	모든 행을 산출하는 Arrow Record Batch Reader 실행·반환
`fetchall`	모든 행을 튜플 리스트로 실행·fetch
`fetchdf`	모든 행을 pandas DataFrame으로 실행·fetch
`fetchmany`	다음 행 집합을 튜플 리스트로 실행·fetch
`fetchnumpy`	모든 행을 각 컬럼을 하나의 numpy 배열에 매핑하는 Python dict로 실행·fetch
`fetchone`	단일 행을 튜플로 실행·fetch
`pl`	모든 행을 Polars DataFrame으로 실행·fetch
`tf`	결과를 TensorFlow 텐서 dict로 fetch
`to_arrow_reader`	모든 행을 산출하는 Arrow Record Batch Reader 실행·반환
`to_arrow_table`	모든 행을 Arrow Table로 실행·fetch
`to_csv`	relation 객체를 'file_name'의 CSV 파일로 작성
`to_df`	모든 행을 pandas DataFrame으로 실행·fetch
`to_parquet`	relation 객체를 'file_name'의 Parquet 파일로 작성
`to_table`	relation 객체의 내용으로 table_name이라는 새 테이블 생성
`to_view`	relation 객체를 참조하는 view_name이라는 뷰 생성
`torch`	결과를 PyTorch 텐서 dict로 fetch
`write_csv`	relation 객체를 'file_name'의 CSV 파일로 작성
`write_parquet`	relation 객체를 'file_name'의 Parquet 파일로 작성

예시 — relation을 DataFrame으로 가져오거나 Parquet으로 쓰기:

rel.to_df()                # DataFrame으로 실행·fetch
rel.to_parquet('out.parquet')  # Parquet 파일로 작성
rel.execute().fetchdf()    # 결과 집합으로 변환 후 DataFrame fetch

더 알아보기 (Learn more)

Python 클라이언트의 다른 기능에 대해서는 [Python client 개요]({% link docs/current/clients/python/overview.md %})와 [Python 함수 레퍼런스]({% link docs/current/clients/python/function_reference.md %})를 참고해요.