# rahul-iyer/duckdb-gql architecture

> Architecture diagram of the GitHub repository rahul-iyer/duckdb-gql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahul-iyer/duckdb-gql
- Repository: https://github.com/rahul-iyer/duckdb-gql
- Video tour (about a minute): https://gitdiagram.com/rahul-iyer/duckdb-gql/video

## Overview

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: [`src/gql_storage.cpp`](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_storage.cpp) (Graph storage), [`src/gql_relational.cpp`](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_relational.cpp) (DuckDB relational plan), [`src/gql_extension.cpp`](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_extension.cpp) (Extension registration), [`src/gql_parser.cpp`](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_parser.cpp) (GQL parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["GQL query processing"]
  node_extension["Extension registration<br/>[gql_extension.cpp]"]
  node_parser["GQL parser<br/>[gql_parser.cpp]"]
  node_transformer["AST transformer"]
  node_ast["GQL AST<br/>[gql_ast.hpp]"]
  node_binder["Semantic binder<br/>[gql_binder.cpp]"]
  node_ir["Bound logical IR<br/>[gql_ir.hpp]"]
  node_optimizer["Access optimizer<br/>[gql_optimizer.cpp]"]
  node_lowerer["Relational lowering<br/>[gql_lowerer.cpp]"]
end

subgraph group_graphs["Graph data and mutations"]
  node_catalog["Graph catalog<br/>[gql_catalog.cpp]"]
  node_storage[("Graph storage<br/>[gql_storage.cpp]")]
  node_import["Graph bulk import<br/>[gql_import.cpp]"]
  node_mutation["Graph mutations<br/>[gql_mutation.cpp]"]
end

subgraph group_execution["Execution and algorithms"]
  node_relational["DuckDB relational plan<br/>[gql_relational.cpp]"]
  node_csr["CSR snapshots<br/>[gql_csr.cpp]"]
  node_algorithms["Graph algorithms<br/>[gql_algorithms.cpp]"]
end

node_user(("SQL user"))
node_duckdb["DuckDB engine"]

node_user -->|"submits SQL"| node_duckdb
node_duckdb -->|"dispatches GQL"| node_extension
node_extension -->|"registers parser"| node_parser
node_parser -->|"transforms syntax"| node_transformer
node_transformer -->|"builds AST"| node_ast
node_parser -->|"plans statement"| node_binder
node_binder -->|"binds AST"| node_ast
node_binder -->|"builds bound IR"| node_ir
node_optimizer -->|"rewrites plan"| node_ir
node_lowerer -->|"lowers plan"| node_ir
node_lowerer -->|"optimizes access"| node_optimizer
node_relational -->|"produces native plan"| node_duckdb
node_relational -->|"reads graph tables"| node_storage
node_relational -->|"uses graph expansions"| node_csr
node_extension -->|"registers graph functions"| node_storage
node_storage -->|"persists graph metadata"| node_catalog
node_import -->|"loads graph data"| node_storage
node_import -->|"reads CSV or Parquet"| node_duckdb
node_mutation -->|"updates graph tables"| node_storage
node_algorithms -->|"traverses snapshots"| node_csr
node_csr -->|"projects graph tables"| node_storage
node_algorithms -->|"registers procedures"| node_duckdb

click node_extension "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_extension.cpp"
click node_parser "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_parser.cpp"
click node_transformer "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_transformer.cpp"
click node_ast "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/include/gql_ast.hpp"
click node_binder "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_binder.cpp"
click node_ir "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/include/gql_ir.hpp"
click node_optimizer "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_optimizer.cpp"
click node_lowerer "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_lowerer.cpp"
click node_relational "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_relational.cpp"
click node_catalog "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_catalog.cpp"
click node_storage "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_storage.cpp"
click node_import "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_import.cpp"
click node_mutation "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_mutation.cpp"
click node_csr "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_csr.cpp"
click node_algorithms "https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_algorithms.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_parser,node_transformer,node_ast,node_binder,node_ir,node_optimizer,node_lowerer,node_user toneBlue
class node_catalog,node_storage,node_import,node_mutation toneAmber
class node_relational,node_csr,node_algorithms toneMint
class node_duckdb toneIndigo
```

## Components

### GQL query processing

- [Extension registration](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_extension.cpp): `src/gql_extension.cpp`
- [GQL parser](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_parser.cpp): `src/gql_parser.cpp`
- [AST transformer](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_transformer.cpp): `src/gql_transformer.cpp`
- [GQL AST](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/include/gql_ast.hpp): `src/include/gql_ast.hpp`
- [Semantic binder](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_binder.cpp): `src/gql_binder.cpp`
- [Bound logical IR](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/include/gql_ir.hpp): `src/include/gql_ir.hpp`
- [Access optimizer](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_optimizer.cpp): `src/gql_optimizer.cpp`
- [Relational lowering](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_lowerer.cpp): `src/gql_lowerer.cpp`

### Graph data and mutations

- [Graph catalog](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_catalog.cpp): `src/gql_catalog.cpp`
- [Graph storage](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_storage.cpp): `src/gql_storage.cpp`
- [Graph bulk import](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_import.cpp): `src/gql_import.cpp`
- [Graph mutations](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_mutation.cpp): `src/gql_mutation.cpp`

### Execution and algorithms

- [DuckDB relational plan](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_relational.cpp): `src/gql_relational.cpp`
- [CSR snapshots](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_csr.cpp): `src/gql_csr.cpp`
- [Graph algorithms](https://github.com/rahul-iyer/duckdb-gql/blob/main/src/gql_algorithms.cpp): `src/gql_algorithms.cpp`

### Other components

- **SQL user**
- **DuckDB engine**

## Connections

- 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