Cypher & SQL-PGQ Graph Queries

Relata DB 3.0
In 3.0 the Neo4j HTTP and Bolt listeners are retired. Cypher is accepted as a subset on POST /v1/query with the x-query-dialect: cypher header and translated to SQL, and SQL/PGQ-style graph syntax goes through the same route. See What is new in 3.0 and the route restructure.

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

Cypher (Neo4j-style subset)

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)Not on /v1/query, which is read-only; write through the ingest routes

The Bolt listener and the Neo4j HTTP endpoints are retired in 3.0: the Neo4j drivers and cypher-shell cannot connect. Send Cypher to POST /v1/query with the x-query-dialect: cypher header, from an SDK or plain HTTP.

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