실행 가능한 예제 번들
작은 CSV·JSON 샘플과 DuckDB SQL 스크립트로 수집, Parquet 변환, profiling을 직접 실행합니다.
핵심 요약
- 예제 번들은 apps/handbook/examples/duckdb-advanced/에 있고, orders.csv·events.json 샘플과 5개 SQL 스크립트로 수집·Parquet 변환·profiling을 직접 실행합니다.
- duckdb CLI에 스크립트를 리다이렉트해 실행하며, 01은 /tmp/duckdb-advanced-orders.parquet를, 02는 row group 설정을 달리해 -rg.parquet를 다시 씁니다.
- 의도적으로 작은 데이터를 써서 성능 수치보다 read_csv_auto → COPY → EXPLAIN ANALYZE 흐름을 손에 익히는 것이 목적입니다.
- Python은 필수가 아니며 requirements.txt는 선택이고, DuckDB CLI로 실행하고 Python 검증기로 결과·예상 오류를 확인할 수 있습니다.
- 팀 적용 기준은 개인정보 없는 10-100 row 샘플, /tmp 출력 경로, 30초 이내 실행, 구조 checker와 실제 실행 검증입니다.
2.0 전환 확인
실습 기준은 DuckDB 2.0.0입니다. 04-v2-migration-probes.sql은 lambda·정규식·0 나누기·NULL·MERGE·factorial·리터럴 타입을 확인합니다. 05-v2-features.sql은 변경 CTE·중첩 schema·트리거·NEAREST JOIN·JSON 수정을 실행합니다.
# 같은 examples/duckdb-advanced 디렉터리에서 실행
# -csv로 출력 계약을 고정해 agent mode의 자동 출력 전환을 피한다.
duckdb -bail -csv < 04-v2-migration-probes.sql2.0 CLI의 -agent는 축약 표·잘림 표시·오류/진행 출력에 유용합니다. 기계가 읽는 결과물은 -csv 또는 -json을 명시하고 종료 코드도 확인합니다. 축약된 표를 전체 결과로 저장하거나 agent mode를 SQL 권한 격리로 취급하지 않습니다.
본문 예시는 읽기용으로 충분하지만, 팀 문서로 쓰려면 실제로 돌아가는 최소 예제가 필요합니다.
이 장의 예제 번들은 apps/handbook/examples/duckdb-advanced/에 함께 넣어 두었습니다. 샘플 데이터는 작고, 출력은 /tmp 아래에 생깁니다.
파일 구성
| 파일 | 목적 |
|---|---|
apps/handbook/examples/duckdb-advanced/data/orders.csv | CSV 수집, 타입 추론, 집계 실습 |
apps/handbook/examples/duckdb-advanced/data/events.json | JSON 추출, nested payload 실습 |
apps/handbook/examples/duckdb-advanced/01-ingest-and-profile.sql | CSV/JSON 읽기, table 생성, Parquet 출력, EXPLAIN ANALYZE |
apps/handbook/examples/duckdb-advanced/02-parquet-layout-benchmark.sql | row group, 정렬, metadata, 같은 쿼리 비교 |
apps/handbook/examples/duckdb-advanced/03-security-session-template.sql | 보안·리소스 세션 기준선 확인 |
apps/handbook/examples/duckdb-advanced/04-v2-migration-probes.sql | 2.0 SQL 의미 변화 |
apps/handbook/examples/duckdb-advanced/05-v2-features.sql | 신규 SQL 기능, fresh in-memory DB 사용 |
apps/handbook/examples/duckdb-advanced/verify-examples.py | 예상 결과·실패·rollback·schema·manifest 검증 |
apps/handbook/examples/duckdb-advanced/requirements.txt | Python/Arrow/Polars 실습용 선택 dependency |
CLI 실행
cd apps/handbook/examples/duckdb-advanced
duckdb -bail -csv /tmp/duckdb-advanced-examples.duckdb < 01-ingest-and-profile.sql
duckdb -bail -csv /tmp/duckdb-advanced-examples.duckdb < 02-parquet-layout-benchmark.sql
duckdb -bail -csv /tmp/duckdb-advanced-examples.duckdb < 03-security-session-template.sql첫 스크립트는 /tmp/duckdb-advanced-orders.parquet를 생성합니다. 두 번째 스크립트는 같은 입력을 정렬/row group 설정을 달리해
/tmp/duckdb-advanced-orders-rg.parquet로 다시 씁니다.
예제 흐름
SQL 패턴
예제는 일부러 작은 데이터로 짰습니다. 성능 수치를 뽑으려는 게 아니라 다음 흐름을 손에 익히려는 것입니다.
CREATE OR REPLACE TABLE orders AS
SELECT *
FROM read_csv_auto('data/orders.csv', header = true);
COPY orders
TO '/tmp/duckdb-advanced-orders.parquet'
(FORMAT parquet, COMPRESSION zstd);
EXPLAIN ANALYZE
SELECT region, plan, sum(amount) AS revenue
FROM orders
GROUP BY ALL
ORDER BY ALL;Python 확장 실습
Python 환경이 있다면 선택적으로 아래 dependency를 설치해 notebook에서 같은 DuckDB file을 열 수 있습니다.
# 저장소 루트에서 Python 3.11+로 실행
python3 -m venv /tmp/duckdb-advanced-venv
source /tmp/duckdb-advanced-venv/bin/activate
python -m pip install -r apps/handbook/examples/duckdb-advanced/requirements.txt운영 문서에서는 Python이 필수가 아닙니다. DuckDB CLI만으로도 수집·변환·profiling 루프를 검증할 수 있게 두는 것이 핵심입니다.
팀 적용 기준
| 항목 | 기준 |
|---|---|
| 샘플 데이터 | 개인정보 없는 10-100 row 수준 |
| 출력 경로 | repo 내부가 아니라 /tmp 또는 별도 scratch |
| 실행 시간 | 로컬 노트북에서 30초 이내 |
| 검증 | 구조 checker + verify-examples.py의 결과 검증 |
| 문서화 | 실제 운영 데이터 경로와 혼동되지 않게 sample prefix 사용 |
결과와 실패를 함께 검증하기
저장소 루트에서 다음을 실행합니다. Python 실행 환경을 관리하는 uv가 필요하며, 최초 실행에는 Python/패키지 다운로드가 발생할 수 있습니다.
uv run --python 3.13 --with duckdb==2.0.0 python apps/handbook/examples/duckdb-advanced/verify-examples.py검증기는 job별 임시 경로로 출력 위치를 치환해 SQL 5개를 실행합니다. 기본 0 나누기·구형 lambda·중복 MERGE·NULL 타입 삽입은 실패해야 통과합니다. 트리거 rollback, 올바른/누락/타입 오류 schema, manifest 재사용, VARIANT Parquet 왕복, seed 고정 표본도 검사합니다. CLI의 -bail은 첫 SQL 오류에서 중단해 앞선 실패를 뒤쪽 성공이 가리는 것을 막습니다.
SQL 01–02의 고정 /tmp 파일명은 수동 실습용입니다. 병렬 CI는 검증기의 임시 디렉터리를 쓰거나 출력 경로를 job별로 바꿉니다. 외부 S3·catalog·BI·Quack 서버는 이 로컬 검사의 범위가 아닙니다.