검증 리포트
DuckDB 고급 활용 핸드북의 구조·링크·공식 근거·버전 기준 검증 결과
2026-10-26 전수 재검증
기준은 DuckDB 2.0.0 LTS입니다. 공식 2.0 문서 목록, migration, 개별 기능 문서와 전체 25개 MDX·예제·전용 checker를 대조했습니다. 아래 표는 이번 조사 범위이며 과거 검증 기록과 구분합니다.
| 문서 | 확인·개선 내용 |
|---|---|
| index | 기준일과 2.0 기능별 읽기 경로 |
| positioning-and-fit | embedded와 Quack 배포의 적용 범위 |
| version-installation-runtime | parser 의미 변화, C API, Intel Mac, rollback 조건 |
| connection-storage-model | WAL 보존과 publish 경계, CONNECT |
| hands-on-examples | SQL 5개와 결과 검증기, -bail |
| csv-json-ingestion | NULL key와 중복 초과 행 수 분리 |
| parquet-lake-modeling | 다중 파일 row group 병렬성과 저장 포맷 경계 |
| multi-file-schema-evolution | 논리 타입 비교, 선택 컬럼 누락, manifest 재사용 |
| partitioned-writes-object-storage | S3 query parameter 이전, publish 원자성 |
| lakehouse-formats | DuckLake 1.1, Delta, Iceberg 옵션 |
| friendly-sql-macros | 변수, 변경 CTE, 중첩 schema |
| temporal-analytical-sql | NEAREST JOIN, seed와 thread 고정 |
| nested-semi-structured-data | VARIANT, JSON mutation, NULL 원소 길이 |
| python-arrow-polars-bi | 점이 든 열 이름, MAP 추론, 새 메서드와 열 충돌 |
| ecosystem-dbt-motherduck-ibis | 엔진과 adapter 승인 분리, 선택 dependency 분리 |
| materialization-indexing-statistics | 트리거·제약, ART dynamic filter |
| performance-profiling | async pool/read-ahead, EXPLAIN (SQL) |
| benchmark-profiling-lab | 버전간 결과 비교와 cold cache 조건 |
| memory-spill-failure-modes | I/O 예산, OOM 재실행 범위 축소 |
| concurrency-security-operations | custom repository와 복구 산출물 보존 |
| security-hardening-checklists | 자체 서명, repository 허용 3단계 |
| templates | manifest와 I/O 설정 기록 |
| references / updates / verification | 공식 근거, 변경 로그, 실행 결과와 한계 |
로컬 실행 결과
| 검증 | 결과 |
|---|---|
verify-examples.py / DuckDB 2.0.0 | SQL 5개 실행 및 예상 결과·오류 검증 통과 |
| CLI 2.0.0 (공식 arm64 배포) | SQL 5개 -bail -csv 실행, 오류 시 종료 코드와 후속 SQL 중단 확인 |
| 트리거·변경 CTE | 감사 행, queue 이동, rollback 원복 통과 |
| schema contract | 정상/선택 컬럼 없음 허용, required 누락·타입 오류 검출 |
| 추가 2.0 기능 | appender·SECURE VIEW·Parquet schema map·PARTITION_PATH/ORDER_BY 로컬 실행 통과 |
| 데이터 의미 | NULL key·LIST 길이·seed 표본·VARIANT Parquet 왕복 통과 |
| Python | Pandas 3.1.0 / PyArrow 26.0.0 / Polars 2.1.0에서 DataFrame·Arrow table/reader·Polars 반환 통과 |
| Python 2.0 API | col/lit·점 포함 열·MAP·materialize 결과 보존·오류 후 rollback 통과 |
| 파일 호환 | 1.5.6 생성 → 2.0 쓰기 → 1.5.6 읽기 통과 |
| 신규 포맷 | 2.0 기본 파일의 1.5.6 읽기 거부 확인 |
| 호환 포맷 | 2.0에서 v1.5.6 호환 파일 생성 후 1.5.6 읽기 통과 |
실행 명령은 예제 번들에 있습니다. 기본 PATH의 CLI 1.2.2는 유지하고, Python 3.13/DuckDB 2.0.0 환경과 임시 경로에 받은 공식 2.0.0 CLI에서 각각 확인했습니다. S3·원격 Quack·Iceberg/Delta/DuckLake catalog·MotherDuck·dbt/Ibis 통합과 성능 배수는 실행 검증하지 않았습니다. 해당 기능은 공식 문서 대조 결과이며 운영 환경의 별도 검증이 필요합니다.
저장소 검사
- MDX 25개 파싱·구조 검사, DuckDB 전용 checker, books registry, content SEO 통과.
- 참고 URL 114개 HTTP 200 확인. 이전 404 링크 2개는 현행 주소로 교체.
pnpm typecheck통과. 관련 문서 색인은 공식 생성 스크립트로 갱신.- 수정한 checker의 Oxlint·Prettier 통과.
- Next.js 컴파일·페이지 생성 통과. 사이트맵은 KST/UTC 날짜 경계에서 일시 실패했으며 UTC 2026-10-26 이후 같은 산출물의 1,116개 URL·페이지 검사 통과. 날짜 형식과 검사 로직은 유지.
pnpm lint는 변경하지 않은app/api/search/route.ts,scripts/lib/check-command-catalog.mjs,command-catalog.test.mjs,command-sources.test.mjs의 기존 오류 15개로 실패. DuckDB 문서 오류와 구분.
2026-10-23 재검증
| 항목 | 확인 범위 |
|---|---|
| 릴리스 | 2.0.0 LTS 실제 출시, 1.5 지원 연장, 1.4 종료일 |
| 호환성 | 신규 파일/기존 파일 storage version, Python 3.11+, SQL 동작 변경 |
| 실행 모델 | embedded 직접 접근과 Quack 서버 경로 구분 |
| 실습 | SQL 파일 4개를 DuckDB 2.0.0에서 실행; 정규식·0 나누기·타입·MERGE 결과 확인 |
| Python | 코드 블록 6개 구문 검사; Pandas·Arrow table/reader·Polars 반환과 오류 후 rollback 실행 확인 |
| 저장 설정 | 새 파일의 v1.5.6 호환 설정 적용 확인; 구버전 reader 교차 실행은 미검증 |
공식 migration과 release calendar를 대조했습니다. 원격 Quack·S3·외부 BI 통합은 실행 검증 범위에 포함하지 않습니다.
이전 검증 기록
검증 기준일
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 | 통과 |