English

duckgql

Downloads

275

GitHub stars

42

Extension repository on GitHub

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

  • Managed property graphs backed by typed DuckDB vertex and edge tables.
  • 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.
  • Standalone node and directed-path INSERT, fixed directed MATCH-and-INSERT, single-node INSERT RETURN, 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, Louvain community detection, 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.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 currently classifies 24 feature families as partial and 12 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_result 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
louvain 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.