How rahul-iyer/duckdb-gql works
DuckGQL is a DuckDB extension implementing a growing subset of GQL. Users submit GQL through DuckDB; the extension parses and binds it, optimizes graph access, and lowers queries into DuckDB-native relational execution. Graph lifecycle and bulk import populate managed graph tables, while read-only projections can reference DuckDB or DuckLake tables. Mutations update graph data, and CSR-backed procedures run graph algorithms over snapshots. The README documents these capabilities; some internal wiring is inferred from module roles and documented behavior because source excerpts are partial.
Main entry points: gql_storage.cpp Graph storage · gql_relational.cpp DuckDB relational plan · gql_extension.cpp Extension registration · gql_parser.cpp GQL parser
Components 17
GQL query processing
- Extension registration
src/gql_extension.cpp - GQL parser
src/gql_parser.cpp - AST transformer
src/gql_transformer.cpp - GQL AST
src/include/gql_ast.hpp - Semantic binder
src/gql_binder.cpp - Bound logical IR
src/include/gql_ir.hpp - Access optimizer
src/gql_optimizer.cpp - Relational lowering
src/gql_lowerer.cpp
Graph data and mutations
- Graph catalog
src/gql_catalog.cpp - Graph storage
src/gql_storage.cpp - Graph bulk import
src/gql_import.cpp - Graph mutations
src/gql_mutation.cpp
Execution and algorithms
- DuckDB relational plan
src/gql_relational.cpp - CSR snapshots
src/gql_csr.cpp - Graph algorithms
src/gql_algorithms.cpp
Other components
- SQL user
- DuckDB engine
Connections 22
- SQL user → DuckDB engine: submits SQL
- DuckDB engine → Extension registration: dispatches GQL
- Extension registration → GQL parser: registers parser
- GQL parser → AST transformer: transforms syntax
- AST transformer → GQL AST: builds AST
- GQL parser → Semantic binder: plans statement
- Semantic binder → GQL AST: binds AST
- Semantic binder → Bound logical IR: builds bound IR
- Access optimizer → Bound logical IR: rewrites plan
- Relational lowering → Bound logical IR: lowers plan
- Relational lowering → Access optimizer: optimizes access
- DuckDB relational plan → DuckDB engine: produces native plan
- DuckDB relational plan → Graph storage: reads graph tables
- DuckDB relational plan → CSR snapshots: uses graph expansions
- Extension registration → Graph storage: registers graph functions
- Graph storage → Graph catalog: persists graph metadata
- Graph bulk import → Graph storage: loads graph data
- Graph bulk import → DuckDB engine: reads CSV or Parquet
- Graph mutations → Graph storage: updates graph tables
- Graph algorithms → CSR snapshots: traverses snapshots
- CSR snapshots → Graph storage: projects graph tables
- Graph algorithms → DuckDB engine: registers procedures