SurrealDB supports ISO/IEC 39075 GQL (often called OpenGQL) for read-only graph pattern matching over your existing tables and RELATE edges. The surface syntax is closer to Cypher-style MATCH … RETURN than to SurrealQL SELECT, but it runs on the same storage model: node labels map to tables, edge types map to relation tables, and properties map to record fields.
Warning
When to use GQL
You already think in graph patterns such as
(a)-[:knows]->(b),SHORTEST, andALL SHORTEST, and have yet to learn how to query such paths in SurrealQL.You are migrating a database from Neo4j to SurrealDB and want to test to ensure that existing Cypher queries map to the same output.
You want a stable graph query surface aligned with the ISO GQL standard.
For general-purpose CRUD, schema changes, and full SurrealQL expressiveness, keep using SurrealQL and the /sql endpoint.
Wire surfaces
| Surface | How to call |
|---|---|
| HTTP | POST /gql — raw GQL query in the request body |
| WebSocket RPC | { "method": "gql", "params": ["<query>", { "var": value }] } — use for typed $variables |
| MCP | gql tool (when the server exposes MCP) |
Session headers match /sql: Surreal-NS, Surreal-DB, and authentication. Responses use the same JSON envelope as /sql (status, result, time).
Data model mapping
| GQL | SurrealDB |
|---|---|
(:person) | Rows in table person |
-[k:knows]-> | Rows in relation table knows (in / out record IDs) |
n.name | Field name on the bound record |
$min | Parameter — bind via RPC params object (typed JSON values) |
GQL is not lowered to SurrealQL text — it compiles to an internal match plan and runs on the streaming engine. The sample queries page shows SurrealQL that returns the same shape where a close equivalent exists; some patterns (optional match blocks, path selectors) are much more concise in GQL.
Notable syntax differences from openCypher
--starts a line comment, not an undirected edge.Inequality is
<>, not!=.Label conjunction uses
&(:person&employee), not:person:employee.Variable-length quantifiers are postfix on the edge:
-[e:knows]->{1,3}(b), not*1..3inside the brackets.No
INlist membership operator in this subset.
The upstream OpenGQL design notes and supported read-only subset are documented in the SurrealDB source tree under doc/opengql/ (REFERENCE.md, LOWERING.md).
Next steps
GQL via HTTP — enable OpenGQL, load data, and call
POST /gqlwith cURLPOST /gqlHTTP reference — headers, response envelope, and parametersSample GQL and SurrealQL queries — side-by-side examples on the seed graph