검증 리포트
DuckDB 고급 활용 핸드북의 구조·링크·공식 근거·버전 기준 검증 결과
검증 기준일
2026-05-14 KST
검증 범위
| 항목 | 기준 |
|---|---|
| 문서 구조 | meta.json 선언과 실제 MDX 파일 일치 여부 |
| 공식 근거 | DuckDB docs, DuckDB blog, release calendar 중심 |
| 버전 기준 | current 1.5, Python client 1.5.2, 1.4 LTS 병행 표기 |
| 대상 적합성 | 초급 튜토리얼이 아니라 시니어 DBA/데이터 엔지니어의 분석 운영 기준인지 |
| 앱 검증 | handbook registry, DuckDB 전용 checker, lint/typecheck/build |
근거 매핑
| 핸드북 장 | 주요 공식 근거 |
|---|---|
| 포지셔닝과 적합한 워크로드 | Why DuckDB, Concurrency, Securing DuckDB |
| 버전·설치·런타임 기준 | 1.5.0 announcement, 1.4 LTS announcement, Release Calendar, Python API |
| 연결·스토리지 모델 | Concurrency, Crashes, EXPORT/IMPORT |
| 실행 가능한 예제 번들 | CLI, CSV Import, JSON Overview, EXPLAIN ANALYZE |
| CSV·JSON 수집 | CSV Import, Auto Detection, JSON Overview |
| Parquet 레이크 모델링 | Parquet Overview, Parquet Tips, File Formats performance |
| 다중 파일·스키마 진화 | Multiple Files, Combining Schemas, Parquet Metadata |
| 파티션 쓰기와 오브젝트 스토리지 | S3 API Support, Secrets Manager, Hive Partitioning, Partitioned Writes |
| Lakehouse 포맷 | Iceberg, Delta, DuckLake, Core Extensions |
| Friendly SQL과 매크로 | Friendly SQL, CREATE MACRO, PIVOT |
| 시계열·분석 SQL | AsOf Join, Window, QUALIFY, Join Operations |
| 중첩·반정형 데이터 | JSON Overview, STRUCT, Nested Functions, 1.5.0 announcement |
| Python·Arrow·Polars·BI | Python API, SQL on Pandas, SQL on Arrow, Polars |
| dbt·MotherDuck·Ibis 생태계 | dbt-duckdb README, DuckDB dbt blog, MotherDuck extension, Ibis |
| Materialization·Index·통계 | CREATE TABLE, ANALYZE, Indexing guide |
| 성능 프로파일링 | EXPLAIN, EXPLAIN ANALYZE, Profiling |
| 벤치마크·프로파일링 실습 | EXPLAIN ANALYZE, Tuning Workloads, Parquet Tips |
| 메모리·spill·실패 모드 | Tuning Workloads, OOM, Limits |
| 동시성·보안·운영 | Concurrency, Securing DuckDB, Securing Extensions, Secrets Manager |
| 보안 Hardening 체크리스트 | Securing DuckDB, Extension Distribution, Secrets Manager |
설계 검증
| 항목 | 결과 | 메모 |
|---|---|---|
| current/LTS 구분 | 반영 | 1.5 current와 1.4 LTS를 버전 기준선에 분리 |
| 분석 엔진 포지셔닝 | 반영 | OLTP 서버 대체로 쓰지 않는 경계 포함 |
| 파일 레이크 활용 | 반영 | CSV/JSON/Parquet/S3/partition/lakehouse 포함 |
| 성능 기준 | 반영 | row group, zonemap, materialization, profiling 포함 |
| 메모리 실패 대응 | 반영 | OOM, temp directory, blocking operator 대응 포함 |
| 보안 기준 | 반영 | untrusted SQL, extension security, secrets warning 포함 |
| Python/BI 연동 | 반영 | Pandas/Polars/Arrow, thread-local cursor, BI read-only 기준 포함 |
| 실행 가능한 예제 | 반영 | CSV/JSON 샘플, CLI SQL 3종, /tmp 출력 기준 포함 |
| 생태계 확장 | 반영 | dbt-duckdb, MotherDuck, Ibis 선택 기준 포함 |
| 보안 hardening | 반영 | 로컬 노트북, CI/배치, 내부 분석 서비스별 기준 포함 |
검증 한계
- 실제 S3 bucket, Iceberg/Delta/DuckLake catalog, BI tool을 연결해 end-to-end 실행하지 않았습니다.
- DuckDB extension은 릴리스 사이에도 업데이트될 수 있으므로 본문은 기준일의 공식 문서 해석입니다.
- 성능 수치는 하드웨어, 파일 레이아웃, object storage latency, OS cache에 따라 달라집니다.
- 예제 SQL smoke test는 로컬 DuckDB CLI(1.4 LTS 이상)에서도 통과하도록 metadata 컬럼을 보수적으로 선택했습니다.
실행 검증 기록
| 날짜 | 명령 | 결과 |
|---|---|---|
| 2026-05-14 | yarn workspace handbook check:books-registry | 통과 |
| 2026-05-14 | yarn workspace handbook check:duckdb-advanced | 통과 |
| 2026-05-14 | yarn workspace handbook lint | 통과 |
| 2026-05-14 | yarn workspace handbook typecheck | 통과 |
| 2026-05-14 | yarn workspace handbook build | 통과 |
| 2026-05-14 | duckdb /tmp/duckdb-advanced-examples.duckdb < 01-ingest-and-profile.sql | 통과 |
| 2026-05-14 | duckdb /tmp/duckdb-advanced-examples.duckdb < 02-parquet-layout-benchmark.sql | 통과 |
| 2026-05-14 | duckdb /tmp/duckdb-advanced-examples.duckdb < 03-security-session-template.sql | 통과 |