Chapter 13Ordering and Pagination

This chapter formalizes how GQL turns unordered bags of bindings into ordered result sequences and how it supports pagination over such sequences. We treat ORDER BY as an ordering operation parameterized by direction, nulls policy, and collation, and LIMIT/OFFSET as slicing operators that produce ordered binding tables.

Concrete syntax for ordering and pagination. In linear query and data-modifying statements, ordering and paging are collected in the order by and page statement that follows the primitive result body (cf. Chapter 12). The following simplified BNF summarizes the relevant concrete syntax; it is aligned with the corresponding productions in ISO/IEC 39075 but omits catalog- and feature-related details:

BNF

order-by-and-page-stmt ::=
    order-by-clause
    [ offset-clause ]
    [ limit-clause ]
  | offset-clause [ limit-clause ]
  | limit-clause
order-by-clause ::= "ORDER" "BY" sort-spec-list
sort-spec-list ::= sort-spec { "," sort-spec }
sort-spec      ::= value-expr [ "ASC" | "DESC" ]
                   [ null-ordering ]
null-ordering  ::= "NULLS" ( "FIRST" | "LAST" )
offset-clause  ::= ( "OFFSET" | "SKIP" ) non-negative-int
limit-clause   ::= "LIMIT" [ "EXACT" | "APPROX" | "APPROXIMATE" ]
                   non-negative-int
value-expr ::= ...

When present, ORDER BY orders on one or more value-expr sort keys (each with optional direction and nulls policy). It may be followed by OFFSET (or its standard synonym SKIP) and LIMIT; an OFFSET with optional LIMIT, or a LIMIT alone, is also permitted without ORDER BY. The semantics of these operators, including peer ordering and approximation options, are given in the sections below.

13.1 ORDER BY and Ordered Tables

Sort specification list and defaults. An ORDER BY clause applies a sort specification list to the current working table. Each sort specification consists of a sort key (an aggregating value expression), an optional ordering direction (ASC/DESC), and an optional nulls policy (NULLS FIRST/NULLS LAST). If the direction is omitted, ascending order is implied. If the nulls policy is omitted, an implementation-defined default is implied that must not depend on context outside the sort list. The result is an ordered binding table. Ordering by a due date and by an aggregate result is illustrated in Section 4.4.

Comparison semantics, nulls, and peers. Let $P, Q$ be records and $K_{1}, \dots, K_{n}$ the sort keys. The relative position of $P$ and $Q$ is determined lexicographically by comparing $K_{i} (P)$ and $K_{i} (Q)$ using $<$ for ascending or $>$ for descending, with special treatment of $null$ per the chosen nulls policy. If both compared values are $null$ , they are considered equal. If one side is $null$ , the comparison outcome is fixed by NULLS FIRST/NULLS LAST. If neither side is $null$ and the comparison yields $U$ , the relative ordering is implementation-dependent. Records that are not distinct with respect to all sort specifications are peers; the ordering among peers is implementation-dependent.

Collation for character strings. Ordering of character strings uses a determined collation. The implementation defines exactly one default collation (UCS_BASIC, UNICODE per UTS#10 (The Unicode Consortium 2025), or an implementation-defined custom collation). This collation is used when comparing strings in ordering operations.

Type comparability of sort keys. Without the optional feature Universal comparison (GA04), the declared types of operands used in ordering operations (including sort keys) shall be comparable value types; otherwise, the program is non-conforming.

13.2 Determinism and Peer Ordering

An ORDER BY yields an ordered binding table, but the ordering of peers and of comparisons that evaluate to $U$ is implementation-dependent. Full cross-implementation determinism requires (i) sort-key tuples that distinguish all output records and yield known comparisons, (ii) the same null ordering, and (iii) the same determined collation. An explicit nulls policy is the portable way to establish (ii), and relying on different implementations’ default collations does not establish cross-implementation determinism. (Without ORDER BY, only bag semantics apply, see below.)

13.3 LIMIT/OFFSET (Slice)

LIMIT clause (EXACT vs. APPROXIMATE). LIMIT retains only a limited number of records from the current working table and produces an ordered binding table. If the input is unordered, the system first imposes an implementation-dependent order and then limits the records. A concrete ORDER BY–LIMIT composition appears in Section 4.4. LIMIT may be EXACT or APPROX/APPROXIMATE (optional feature GQ28). If the approximation keyword is omitted, then EXACT is implicit, except in the special case where a linear query statement that directly contains the LIMIT clause also directly contains a value expression whose declared type is a vector type; in that case it is implementation-defined whether EXACT or an approximation synonym is implicit. Let $V_{\lim}$ be the non-negative integer value computed for the LIMIT clause. For EXACT, the first $V_{\lim}$ records are returned. For APPROXIMATE, the implementation first chooses an actual result cardinality $V_{\lim}^{'} \leq V_{\lim}$ , and then selects $V_{\lim}^{'}$ records from the ordered input in an implementation-dependent manner. The selected records retain their relative input order, but they need not form a prefix of the input; in particular, they need not be the first $V_{\lim}^{'}$ records.

OFFSET clause. Let $V_{off}$ be the non-negative integer value computed for the OFFSET clause. It discards the first $V_{off}$ records and returns the remainder as an ordered binding table. If the input is unordered, an implementation-dependent order is imposed prior to discarding. The clause requires optional Feature GQ12.

Example (OFFSET on a determined order).

GQL

USE libraryGraph
MATCH (l:Loan)-[i:INCLUDES]->(b:Book)
RETURN b.title AS title, i.due_date AS due_date
ORDER BY due_date
OFFSET 1

The ordered input contains

Graph DB 101

first and

Graph Theory

second, so the result contains only the latter record.

Composition and evaluation order. When ORDER BY, OFFSET, and LIMIT appear together, evaluation proceeds in this order:

ORDER BY \to OFFSET \to LIMIT .

This composition is specified by the order by and page statement, which applies the sort first, then discards the initial $V_{off}$ rows, and finally retains at most $V_{\lim}$ rows, where $V_{off}$ and $V_{\lim}$ are the values specified by the OFFSET and LIMIT clauses, respectively.

Interaction with result formation. The ORDER BY and page statement is evaluated after its associated RETURN body. The standard’s syntax transformations can introduce hidden aliases needed to evaluate admissible sort keys and remove them from the final output. Without Feature GA07, Ordering by discarded binding variables, a sort key cannot directly reference a binding variable discarded by that projection, except through the alias cases admitted by the applicable RETURN or SELECT syntax rules.

13.4 Determinism Guarantees

Totality of GROUP BY. For any finite bag $B$ and finite expression vectors $g \to, h \to$ whose aggregators are defined on each group bag $B_{i}$ induced by $g \to$ (with expected null-handling),

GROUP BY g \to YIELD h \to (B)

is a finite bag.

Optionals do not invent non-null data. Let $A$ and $B$ be binding tables, and consider the left outer join $A ⊲_{𝜃} B$ defined in Section 9.2. For a binding table $T$ with record type $τ_{T}$ , write $hdr (T) = dom (τ_{T})$ . For any output record, every attribute whose name occurs only in the schema of $B$ (is in $hdr (B) ∖ hdr (A)$ ) is either material (copied from a matching record in $B$ , if such a match exists) or $null$ (if no match exists). No other values for these attributes are introduced.

Determinism of ORDER BY. Given the applicable fixed weak orders $≼$ from Section 8.3, their strict parts $≺$ , a collation, and a $null$ policy, and a sort-specification list $o \to$ , ${ORDER BY}_{o \to} (B)$ determines the order between non-peer records whose key comparisons are known. The relative order of peers, and of non-null key values whose comparison is $U$ , remains implementation-dependent; full determinism therefore additionally requires sort keys that distinguish every output record and yield known comparisons. Without ORDER BY, only bag semantics are defined.

Chapter 13 — Takeaways.

Purpose: Formalized how unordered query results were converted into ordered sequences and how pagination operated over those sequences.
Introduced: Ordering driven by sort keys with explicit null placement and collation; tie behavior and peer ordering; pagination as slicing with offset and limit.
Key distinctions: Ordered results versus unordered bag results; deterministic versus implementation-dependent pagination when peers or unknown comparisons remain.
Consequences: Explained when users could rely on repeatable page boundaries; clarified the semantics of null placement in ordering; integrated ordering and pagination into the overall clause pipeline.
Bridge: Transitioned from read-only semantics to data modification and graph updates.