GQL Specification Reference

GQL Specification Reference Share link

Geode implements the ISO/IEC 39075:2024 Graph Query Language (GQL) 100% compliance. This reference documents the specification and links to Geode’s current conformance profile and implementation notes.

Standard Overview Share link

ISO/IEC 39075:2024 Share link

The Graph Query Language (GQL) is an international standard for querying property graph databases. It provides:

• Declarative graph pattern matching
• Standard data types and operators
• Transaction semantics
• Error handling with standardized codes
• Extensibility for implementations

Document Structure Share link

The GQL standard comprises multiple parts:

Conformance Profile Share link

Geode Conformance Level Share link

Geode publishes a conformance profile for ISO/IEC 39075:2024 compliance. The profile documents implementation-defined behavior and focuses on deterministic ordering, pagination, and diagnostics.

Profile highlights (non-exhaustive):

• MATCH / OPTIONAL MATCH with bounded path expansions
• WHERE, RETURN, ORDER BY
• LIMIT / OFFSET (unordered pagination rejected per US001)
• Set operations: UNION, INTERSECT, EXCEPT
• Data modification statements (CREATE, INSERT, UPDATE, DELETE, MERGE)
• Schema and type system behaviors (labels, property types, constraints, indexes)
• Transactions, functions, and standardized error codes

See the conformance profile for authoritative scope, diagnostics, and implementation-defined behaviors.

Syntax Reference Share link

Query Structure Share link

<gql-query> ::=
    [ <graph-specification> ]
    <query-expression>

<query-expression> ::=
    <simple-query>
  | <composite-query>

<simple-query> ::=
    <match-statement>
  | <call-statement>
  | <return-statement>

<composite-query> ::=
    <simple-query> <set-operator> <simple-query>

Pattern Syntax Share link

<pattern> ::=
    <node-pattern>
  | <path-pattern>

<node-pattern> ::=
    '(' [ <variable> ] [ <label-expression> ] [ <property-specification> ] ')'

<label-expression> ::=
    ':' <label-name> [ <label-expression> ]

<property-specification> ::=
    '{' <property-list> '}'

<property-list> ::=
    <property-setting> [ ',' <property-setting> ]*

<property-setting> ::=
    <property-name> ':' <expression>

Relationship Pattern Share link

<relationship-pattern> ::=
    <left-arrow>? '-' [ <relationship-detail> ] '-' <right-arrow>?

<relationship-detail> ::=
    '[' [ <variable> ] [ <type-expression> ] [ <length-specification> ] [ <property-specification> ] ']'

<type-expression> ::=
    ':' <relationship-type>
  | ':' <relationship-type> '|' <type-expression>

<length-specification> ::=
    '*' [ <range> ]

<range> ::=
    <integer> [ '..' [ <integer> ] ]
  | '..' <integer>

Data Types (ISO Mapping) Share link

Core Types Share link

Extended Types Share link

Implementation-Defined Types Share link

Geode extends the standard with additional types:

Operators (ISO Mapping) Share link

Comparison Operators Share link

Logical Operators Share link

Arithmetic Operators Share link

String Operators Share link

Collection Operators Share link

Functions (ISO Mapping) Share link

Aggregate Functions Share link

Scalar Functions Share link

Path Functions Share link

Type Functions Share link

Error Handling Share link

ISO Status Codes Share link

Geode implements standard GQL status codes:

Error Response Format Share link

{
  "type": "ERROR",
  "code": "42000",
  "sqlstate": "42000",
  "message": "Syntax error at position 15",
  "detail": "Unexpected token 'METCH', did you mean 'MATCH'?",
  "position": {
    "line": 1,
    "column": 15
  }
}

Transaction Semantics Share link

Isolation Levels Share link

ACID Guarantees Share link

Implementation-Defined Behavior Share link

The ISO standard allows implementations to define certain behaviors:

Collation and Ordering Share link

-- Geode's default collation is Unicode binary
MATCH (p:Person)
RETURN p.name
ORDER BY p.name;  -- Unicode code point order

-- Case-insensitive comparison
WHERE lower(p.name) = lower($search)

NULL Ordering Share link

-- NULLs sort last by default (configurable)
ORDER BY p.age ASC NULLS LAST
ORDER BY p.age DESC NULLS FIRST

Identifier Length Share link

Numeric Precision Share link

Conformance Testing Share link

Running Conformance Tests Share link

cd geode
make test-gql-conformance

Test Categories Share link

1. Lexer Tests: Token recognition
2. Parser Tests: Syntax validation
3. Semantic Tests: Type checking, resolution
4. Execution Tests: Correct results
5. Error Tests: Proper error handling

Test Results Summary Share link

Conformance tests are tracked against the published ISO/IEC 39075:2024 profile. For current status, diagnostics, and implementation-defined behaviors, see the conformance profile and the CI evidence linked there.

Extensions Beyond Standard Share link

Geode provides extensions not in the ISO standard:

Full-text Search Share link

-- BM25 full-text search (Geode extension)
MATCH (d:Document)
WHERE fulltext_match(d.content, 'graph database')
RETURN d.title, bm25_score(d.content, 'graph database') AS score
ORDER BY score DESC;

Vector Similarity Share link

-- Vector similarity search (Geode extension)
MATCH (d:Document)
RETURN d.title, vector_distance_cosine(d.embedding, $query_vector) AS distance
ORDER BY distance
LIMIT 10;

Geographic Functions Share link

-- Geographic queries (Geode extension)
MATCH (s:Store)
WHERE geo_distance(s.location, $user_location) < 5000
RETURN s.name, geo_distance(s.location, $user_location) AS meters;

Query Hints Share link

-- Index hints (Geode extension)
MATCH (p:Person)
USING INDEX p:Person(email)
WHERE p.email = $email
RETURN p;

Reserved Words Share link

GQL reserved words that cannot be used as unquoted identifiers:

ALL, AND, ANY, AS, ASC, ASCENDING, BY, CALL, CASE, COMMIT, CONSTRAINT,
CONTAINS, COUNT, CREATE, DELETE, DESC, DESCENDING, DETACH, DISTINCT,
DROP, ELSE, END, ENDS, EXISTS, FALSE, FOR, FROM, GRAPH, GROUP, HAVING,
IN, INDEX, IS, LIMIT, MATCH, MERGE, NOT, NULL, ON, OPTIONAL, OR, ORDER,
REMOVE, RETURN, ROLLBACK, SESSION, SET, SKIP, START, STARTS, THEN, TO,
TRUE, UNION, UNIQUE, UNWIND, USE, USING, WHEN, WHERE, WITH, XOR, YIELD

Escaping reserved words:

-- Use backticks for reserved words as identifiers
MATCH (n:`ORDER`)
RETURN n.`LIMIT`;

Related Documentation Share link

• GQL Guide - Query language tutorial
• Conformance Profile - Detailed conformance
• Functions Reference - All functions
• Operators Reference - All operators
• Data Types Reference - Type system

Last Updated: January 28, 2026 Geode Version: v0.1.3+ ISO Standard: ISO/IEC 39075:2024 Conformance Profile: ISO/IEC 39075:2024 compliance (see conformance profile)