Cypher & SQL-PGQ Graph Queries

RelataDB supports three graph query languages over the same underlying CSR adjacency engine.

Cypher (Neo4j-compatible)

Any SQL query starting with MATCH is auto-detected and translated to SQL before execution. No separate endpoint is needed.

MATCH (n:Person {id: 'p1'}) RETURN n.name, n.email

Multi-hop traversal:

MATCH (a:Person)-[:KNOWS]->(b:Person)
WHERE a.id = 'p1'
RETURN b.name

Supported Cypher clauses

ClauseStatus
MATCH / OPTIONAL MATCH✅
WHERE✅
RETURN✅
RETURN DISTINCT / ORDER BY / SKIP / LIMIT✅ (labelled-node MATCH)
UNION / UNION ALL✅
CALL traverse.* / CALL gds.*✅
CREATE / MERGE (writes)✅ via governed write door

Connect via the Bolt protocol on port 7687 (default) using the official Neo4j Python/Java/Go drivers or cypher-shell.

SQL/PGQ

SQL/PGQ graph patterns inside standard SQL SELECT:

SELECT p1.name, p2.name
FROM MATCH (p1:Person) -[e:KNOWS]-> (p2:Person) ON graph_schema
WHERE p1.id = 'p1'

Graph SQL operators

RelataDB provides 10+ graph operators as SQL table-valued functions:

-- Shortest path
SELECT * FROM SHORTEST_PATH('Person', 'p1', 'p2', 'KNOWS')
 
-- Traverse with depth limit
SELECT * FROM TRAVERSE('Person', 'p1', 'KNOWS', 3)
 
-- Degree centrality
SELECT id, DEGREE(id, 'out') AS out_degree FROM Person
 
-- Connected components
SELECT * FROM WEAKLY_CONNECTED('Person', 'KNOWS')
 
-- PageRank
SELECT id, pagerank FROM PAGERANK('Person', 'KNOWS')

GQL (ISO/IEC 39075)

The ISO GQL surface is reachable on POST /query with the x-query-dialect: gql header (#3265). GQL is header-selected only — without the header, a MATCH body is auto-detected as Cypher, so the two grammars are never silently confused.

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -H "x-query-dialect: gql" \
     -d '{"purpose":"analytics","sql":"MATCH (n:Person) WHERE n.age > 35 RETURN n.name ORDER BY n.age DESC LIMIT 5"}' \
     http://localhost:9090/query

Supported subset: single-node and edge MATCH, WHERE/FILTER, OPTIONAL MATCH, RETURN with DISTINCT/ORDER BY/LIMIT/SKIP, UNION [ALL], and CALL procedures. Deferred constructs (writes, quantified paths, path modes, SHORTEST/ANY/ALL prefixes) return a typed error — GQL-status 42G04 (syntax, HTTP 400) or 0A501 (feature not supported, HTTP 501) — never a silent mis-translation.

All SDKs expose the dialect: client.query(stmt, dialect="gql") (Python), relata.query(stmt, { dialect: "gql" }) (TypeScript), client.Query(ctx, stmt, relata.WithDialect("gql")) (Go).

See also