duckgql

797 downloads this week 55 stars Extension descriptor

GQL graph queries, mutations, and algorithms over DuckDB and DuckLake tables

Compatibility Matrix

This table covers all DuckDB releases that have not reached end-of-life, including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

Installing and Loading

INSTALL duckgql FROM community;
LOAD duckgql;

Example

COPY (
  SELECT * FROM (VALUES
    ('p1', 'Ada', 'Person'),
    ('p2', 'Grace', 'Person')
  ) nodes(":ID(People)", "name:string", ":LABEL")
) TO 'duckgql_nodes.csv' (FORMAT CSV, HEADER);

COPY (
  SELECT * FROM (VALUES
    ('p1', 'p2', 'KNOWS')
  ) edges(":START_ID(People)", ":END_ID(People)", ":TYPE")
) TO 'duckgql_edges.csv' (FORMAT CSV, HEADER);

CREATE GRAPH social ANY;

COPY GRAPH social FROM (
  VERTICES 'duckgql_nodes.csv',
  EDGES 'duckgql_edges.csv'
) FORMAT GRAPH;

SESSION SET GRAPH social;

MATCH (person:Person)-[:KNOWS]->(friend:Person)
RETURN person.name, friend.name;

About duckgql

DuckGQL is an experimental C++17 extension that adds a growing subset of ISO/IEC 39075:2024 GQL to DuckDB. It combines graph pattern queries and mutations with DuckDB's native relational storage and execution engine, plus an explicit CSR layer for graph algorithms.

What works in v0.3.1

This version targets DuckDB 2.0.0.

• Managed property graphs backed by typed DuckDB vertex and edge tables.
• Zero-copy graph projections over existing DuckDB and DuckLake tables, including multiple heterogeneous vertex and edge mappings. Live graphs registered with ACCESS_MODE 'READ_WRITE' support GQL INSERT, SET, REMOVE, and DELETE against their mapped source tables.
• Live DuckLake projections that follow committed snapshots, or pinned projections for reproducible analysis.
• Mapping-scoped integer source keys, optional edge keys, and DuckGQL-managed dense element IDs, without application-maintained numeric ID ranges.
• Inline typed graph schemas that persist in the catalog and immediately materialize constrained vertex and edge tables without COPY GRAPH.
• Graph-header CSV, compressed CSV, and Parquet bulk import with optional endpoint and identity validation.
• Directed MATCH, OPTIONAL MATCH, filtering, projection, aggregation, ordering, paging, fixed multi-hop patterns, and a bounded variable-length path subset, composed quantified patterns, shortest-path search, and search-based reachability.
• Standalone node and directed-path INSERT, fixed directed MATCH-and-INSERT, multiple directed insertion paths, node and edge INSERT RETURN values, property and label mutation, and edge/node deletion.
• Query parameters and native DuckDB ART indexes for selective vertex-property equality lookups.
• Compact, buffer-managed CSR snapshots with incremental insert deltas and optional persistence in the database file for reuse after reopening.
• Explicit CSR-backed BFS, DFS, unweighted and weighted SSSP, PageRank, weak and strong components, Louvain community detection, degree, closeness, local clustering coefficient, and triangle counting.
• Experimental cost-based graph planning with plan diagnostics, directional fanout and endpoint statistics, and costing across connected patterns. Seed-degree estimates and same-type degree bias improve expansion costing. Enable it with SET gql_optimizer = 'cost'; legacy planning is the default.
• Snapshot-scoped DuckLake identity caching and selective projected property access, with source-version pinning and prepared-query rebinding.

Storage and execution model

Managed vertices and edges remain authoritative ordinary DuckDB tables rather than entity-attribute-value rows. For referenced graphs, the mapped DuckDB or DuckLake source tables remain authoritative and DuckGQL persists the typed graph mapping and derived caches. Nodes retain their complete label set and each edge has exactly one immutable type. DuckGQL lowers graph queries to native DuckDB relational plans, allowing DuckDB to execute scans, joins, aggregation, ordering, and recursive CTEs. The graph optimizer can choose table scans, native property indexes, node-label postings, and selective CSR expansion. CSR snapshots are database-instance scoped, version checked, and derived rather than authoritative. Inserts are read through a delta alongside the snapshot; updates and deletes invalidate affected snapshots. gql_build_csr saves snapshots in the database file by default. After reopening, saved pages load on demand through DuckDB's buffer manager, including for read-only databases. Use persist := false for memory-only snapshots.

Project status

DuckGQL v0.3.1 is not yet a complete or conforming ISO GQL implementation. Grammar recognition does not imply semantic or transactional conformance. The machine-readable conformance manifest records partial and planned feature families. Important restrictions include autocommit-only graph lifecycle and CSR operations, a single vertex and edge input per bulk load, and incomplete general path searches, query composition, procedures, and the complete GQL value/type system.

See the documentation, inspect the conformance manifest, or try the browser playground.

Added Functions

Overloaded Functions

This extension does not add any function overloads.

Added Types

This extension does not add any types.

Added Settings