Systems

The DuckDB engine is built from a set of internal subsystems under src/. Each one corresponds to one stage of the query lifecycle or a cross-cutting concern.

graph TD
    Main[main: DatabaseInstance, Connection, ClientContext, C API]
    Parser[parser: SQL → AST]
    Planner[planner: AST → bound logical plan]
    Optimizer[optimizer: rewrite + reorder]
    Execution[execution: physical operators]
    Parallel[parallel: pipelines + scheduler]
    Function[function: scalar/agg/table/window/pragma]
    Catalog[catalog: schemas/tables/funcs versioned]
    Transaction[transaction: MVCC, undo, WAL writes]
    Storage[storage: blocks, buffer mgr, WAL, checkpoints]
    Common[common: vector, types, file system, allocator]
    Logging[logging: structured logs]

    Main --> Parser
    Parser --> Planner --> Optimizer --> Execution --> Parallel
    Execution --> Function
    Planner --> Catalog
    Execution --> Catalog
    Execution --> Transaction
    Transaction --> Storage
    Catalog --> Storage
    Common -.-> Parser
    Common -.-> Planner
    Common -.-> Optimizer
    Common -.-> Execution
    Common -.-> Storage
    Logging -.-> Main

Pages

• parser — SQL string to SQLStatement AST. PEG grammar in src/parser/peg/.
• planner — name resolution, type inference, logical plan construction.
• optimizer — logical-plan rewrites, join ordering, filter/projection pushdown.
• execution — physical plan generator, operator implementations, expression executor.
• parallel — pipelines, meta-pipelines, events, task scheduler.
• function — scalar, aggregate, table, window, and pragma function machinery.
• catalog — schemas, tables, functions, types, dependency tracking.
• transaction — MVCC, undo buffers, snapshot isolation, WAL writers.
• storage — block manager, buffer manager, WAL, checkpoint, compression.
• main — the embedding surface: DatabaseInstance, Connection, ClientContext, C API.
• common — the shared library: vectors, types, file system, allocators, error data.

The logging/ directory is small and is documented inline in src/logging/. Tests for each subsystem live in test/sql/<area>/ and test/api/.

How to navigate

For a concrete query, follow the path in overview/architecture. For a particular SQL feature, search test names in test/sql/ to see how it is exercised, then trace from parser → planner → optimizer → execution. The glossary lists the type names you will see along the way.