실행 가능한 예제 번들
작은 CSV·JSON 샘플과 DuckDB SQL 스크립트로 수집, Parquet 변환, profiling을 직접 실행합니다.
핵심 요약
- 예제 번들은 apps/handbook/examples/duckdb-advanced/에 있고, orders.csv·events.json 샘플과 3개 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만으로 전체 루프를 검증할 수 있게 둡니다.
- 팀 적용 기준은 개인정보 없는 10-100 row 샘플, /tmp 출력 경로, 30초 이내 실행, checker의 파일 존재 확인입니다.
본문 예시는 읽기용으로 충분하지만, 팀 문서로 쓰려면 실제로 돌아가는 최소 예제가 필요합니다.
이 장의 예제 번들은 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/requirements.txt | Python/Arrow/Polars/Ibis 실습용 선택 dependency |
CLI 실행
cd apps/handbook/examples/duckdb-advanced
duckdb /tmp/duckdb-advanced-examples.duckdb < 01-ingest-and-profile.sql
duckdb /tmp/duckdb-advanced-examples.duckdb < 02-parquet-layout-benchmark.sql
duckdb /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을 열 수 있습니다.
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가 예제 파일 존재 여부를 확인 |
| 문서화 | 실제 운영 데이터 경로와 혼동되지 않게 sample prefix 사용 |