Search Shortcut cmd + k | ctrl + k
duckgql
Downloads 4this week
GitHub stars 24
Extension repository on GitHub
Extension descriptor (YAML)

Adds ISO GQL graph querying and graph algorithms to DuckDB

Maintainer(s): rahul-iyer

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.1.0

  • Managed property graphs backed by typed DuckDB vertex and edge tables.
  • 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.
  • Standalone node and directed-path INSERT, fixed directed MATCH-and-INSERT, property and label mutation, and edge/node deletion.
  • Native DuckDB ART indexes for selective vertex-property equality lookups.
  • Explicit CSR-backed BFS, DFS, unweighted SSSP, PageRank, weak and strong components, degree, closeness, local clustering coefficient, and triangle counting.

Storage and execution model

Vertices and edges remain authoritative ordinary DuckDB tables rather than entity-attribute-value rows. 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 fixed-hop CSR expansion. CSR snapshots are derived explicitly and are not a second authoritative graph store.

Project status

DuckGQL v0.1.0 is not yet a complete or conforming ISO GQL implementation. Grammar recognition does not imply semantic or transactional conformance. The machine-readable conformance manifest currently classifies 23 feature families as partial and 13 as planned. Important restrictions include autocommit-only graph lifecycle and CSR operations, connection-local CSR snapshots, 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

function_name function_type description comment examples
bfs table NULL NULL  
closeness table NULL NULL  
degree table NULL NULL  
dfs table NULL NULL  
gql_algorithm_call table NULL NULL  
gql_algorithm_result table NULL NULL  
gql_build_csr table NULL NULL  
gql_clear_properties_source table NULL NULL  
gql_create_property_index table NULL NULL  
gql_csr_edge_stats table NULL NULL  
gql_csr_expand table NULL NULL  
gql_csr_path_expand table NULL NULL  
gql_csr_stats table NULL NULL  
gql_csr_vertices table NULL NULL  
gql_drop_property_index table NULL NULL  
gql_edge_fetch table NULL NULL  
gql_graphs table NULL NULL  
gql_insert_ids table NULL NULL  
gql_insert_target table NULL NULL  
gql_match_insert_ids table NULL NULL  
gql_match_recursive table NULL NULL  
gql_match_relational table NULL NULL  
gql_merge_id table NULL NULL  
gql_merge_target table NULL NULL  
gql_mutation_control table NULL NULL  
gql_mutation_graph table NULL NULL  
gql_mutation_target table NULL NULL  
gql_neighbors table NULL NULL  
gql_property_indexes table NULL NULL  
gql_vertex_fetch table NULL NULL  
lcc table NULL NULL  
pagerank table NULL NULL  
scc table NULL NULL  
sssp table NULL NULL  
triangle_count table NULL NULL  
wcc table NULL NULL  

Overloaded Functions

This extension does not add any function overloads.

Added Types

This extension does not add any types.

Added Settings

This extension does not add any settings.