queries.md

Query Language (.gq)

A .gq file contains named, typed queries. Read queries match graph patterns and return columns; mutation queries use the same declaration form and are covered in Mutations. A file may instead hold exactly one statement, never beside a query declaration: a branch statement (branch create, delete, merge, list, diff, or merge-base; see Branches, Commits, and History), a show statement (see session settings), or an explain statement, which answers the plan a read query would run under instead of its rows (see Explain). Any of them may open with session settings lines.

query engineers($title: String) @description("People with a title") {
  match {
    $p: Person { title: $title }
    $p worksAt $c
  }
  return { $p.name, $c.name as company }
  order { company asc, $p.name asc }
  limit 50
}

Run an ad-hoc query with:

omnigraph query engineers --query queries.gq \
  --params '{"title":"Engineer"}' --target ./graph.omni

Declarations and parameters

query <name>($required: String, $optional: I32?) { ... }

Parameter types use the schema scalar types. Every non-nullable declared parameter must be supplied; omission fails before query execution. A trailing ? accepts null or an omitted value. @description("...") and @instruction("...") attach metadata for clients that expose stored queries as tools. An integer parameter carries the whole range of its declared type, so a U64 parameter takes every value from 0 to 18446744073709551615.

Match patterns

A match binds nodes and follows typed relationships. For edge alternatives, wildcard, bounded hops, direction and edge identity, see Traversal and match patterns. Omitted bounds always mean exactly {1,1}; multiple hops require an explicit finite range.

Boolean expressions and nulls

Filters combine with and, or, not and parentheses. or binds loosest, then and, then not, then comparison, so not $p.email is null reads as not ($p.email is null). Comparisons do not chain: $a < $b < $c is a parse error. not { stays the pattern negation. Operands of and, or and not must be Bool (T41), as in ($d.stage = "open" or $d.stage = "paused") and not $d.amount < $cut.

A comparison (contains and starts_with included) with a null operand is null, and not null is null. A filter or mutation where keeps only rows whose expression is true, so not ($p.age > 30) skips rows whose age is null.

Numeric comparisons choose their types before execution. A literal may use a property's type when its value is exactly representable in that type; otherwise both operands use a common numeric type. Parameters use their declared type, regardless of the supplied value. An F32 property storing 0.1 therefore differs from the F64 literal 0.1, while 0.5 compares exactly. These rules also apply to list membership and mutation predicates, whether a filter runs in a scan or in memory. Mixed signed and U64 values compare without losing integer precision.

x y x and y x or y
true null null true
false null false null
null null null null
true false false true

x is null and x is not null are always Bool and are the only null tests: GQ has no null literal, so $p.x = null is a parse error. not ($p.age > 30) or $p.age is null selects every row the comparison did not. A parameter bound to null makes every comparison on it null. is null refuses a Blob.

and, or, not, is, null and in are reserved words: none is a bare operand or a return alias. $p.and after a dot and and: 1 in an assignment or binding match stay legal; nothing and android are ordinary identifiers. A traversal names its edge bare or as a string, the one spelling for an edge a reserved word names: $i "in" $b follows the edge In; $i in $b tests membership.

A mutation where takes the same expressions over the target type's properties, @id, @src, @dst, literals, parameters and now(), never a binding variable, aggregate or search call: delete Knows where @src = "a" and @dst = "b". Assignment values and binding matches take constants evaluated once per invocation, such as adult: true or $flag; a property or system field there is T45. See Mutations.

Correlated blocks

not { ... }, exists { ... }, count { ... } op value and sum(expr) { ... } op value (also min, max, avg) match a pattern once per outer row. Each block must read a variable bound outside it. The row is kept when the aggregate comparison is true: not means count = 0, and exists means count > 0. The right side is a literal, now() or typed parameter; numeric bounds follow the comparison rules for the aggregate's result type. Its argument is a scalar expression in the block's scope: numeric for sum and avg; numeric, String, Bool, Date or DateTime for min and max, as in return. With no matches, sum, min, max and avg satisfy no comparison; count is 0.

Integer block sum accumulates exactly in 128 bits, refuses overflow of that range, and rounds the total once to F64 before comparison. For example, 9007199254740993 and -9007199254740992 sum to 1, while a single value 9007199254740993 rounds to 9007199254740992 and does not satisfy sum(...) { ... } > 9007199254740992.

As in return, avg converts each non-null input to F64 before summing and dividing by the count. For those same two values, the average is 0, because the first value rounds before accumulation. min and max retain the column's declared type, including the full U64 range; comparing a U64 extremum with an I64 parameter preserves both integer ranges. Row count and column count use I64 and refuse a count beyond its range; column count skips null values.

The block narrows the rows before order and limit, so a paged listing filtered by a relationship count is exact. A binding the block's traversal connects to the outer row is reached through it, or the block runs once from a node it binds by key if that is cheaper (strategy in explain); a binding correlated only through a filter, or read by a text search, is scanned. A single-hop, filter-free count { ... } over a directed, unbound edge is answered from the graph index's degree. A bare aggregate in match, count($d) > 2 without a block, is refused: it names no row to group by.

query prolific($least: I64) {
    match {
        $a: Author
        count {
            $p: Post { published: true }
            $a authored $p
        } >= $least
    }
    return { $a.name }
    order { $a.name }
    limit 20
}

Strings and lists

NULL never matches these predicates. % and _ are ordinary characters, not wildcards. The predicates remain correct without an index; do not assume a free-text String index accelerates exact prefix or substring filters. Use full-text search for tokenization, fuzzy matching, and relevance ranking.

System fields

A node's identity and an edge's endpoints are system fields, read through @-prefixed meta-fields that no user property can shadow: $p.@id is the identity of any binding, $e.@src and $e.@dst the endpoints of a bound edge. They work in filters, projections, and orderings ($p.@id = $who, return { $p.@id }, order { $p.@id asc }) and answer on every graph, whatever the stored column is called. In a mutation predicate, which carries no binding, the bare form serves: delete Person where @id = $who, delete Knows where @src = $who. A bare id ($p.id, where id = ...) always names a user property called id; where none is declared it is the unknown-property error, which names the meta-field. Edge inserts keep addressing endpoints as from and to. $e.@type returns the bound edge's canonical schema type name as a non-null String, including on ordinary named traversals; it is synthesized query metadata and cannot be written. @src and @dst preserve stored orientation, including when the query traverses in reverse. In type position the same prefix names an engine-owned, read-only type: $o: @Operator binds the rows of the engine catalogue.

Return, order, and limit

return { $person.name, count($company) as companies }
order { companies desc, $person.name asc }
limit 20

Return expressions include variables, properties, literals, now(), and the aggregates count, sum, avg, min, and max. Each gives one column named by its alias or expression ($p.name gives p.name); duplicates are refused (T25).

Integer sum accumulates exactly in 128 bits and rounds once to F64; avg uses a floating-point accumulator. min and max accept numeric, String, Bool, Date, or DateTime columns and keep their type (false before true, dates chronologically). With no matches, an aggregate-only return gives one row (count 0, the rest null); a return that also projects a group value gives no rows.

A bare node returns one object with @id and every property except Blob and Vector: $p produces column p; project a property for one field. count($p) counts rows and count(distinct $p) distinct nodes; count(distinct $p.city) counts distinct non-null values, so a node reached by several paths counts once. Other aggregates require a property (T8) and refuse distinct (T57).

A comparison or Boolean expression requires an alias (T43), such as $p.age > 30 as adult; its result is Bool, or Bool? with a nullable operand, and is null is always Bool. In an aggregated return its operands are aggregates, literals, now() and parameters, evaluated per group after aggregation: count($p) > 0 as any is Bool? because count is I64?. A group value beside an aggregate is refused (T58), any other Boolean item too (T9).

return distinct { $p.name } keeps one row per complete projected tuple. Repeated traversal matches and equal values on different entities collapse; nulls compare equal. Every projection is a key, including comparisons, and bare nodes deduplicate by identity. Deduplication follows match and precedes ordering and limiting, so the limit counts distinct rows. Aggregates with distinct are refused (T56). Except for a leading search function, DISTINCT order keys must be projected values or aliases, including property keys (T42). Remaining projected columns break ties ascending; no identity tiebreak is added.

For ordinary returns, explicit order is total: entity ids break ties only when they can change the visible order, and no id is read when every projection is a key. Ascending puts nulls first, descending last. nearest(...) requires a limit. On ungrouped, non-DISTINCT rows, property and system-field order keys need not be projected; other keys, except the leading search function, must be return aliases or expressions written in return (T42), like count($d) after return { count($d) as deals }.

For ordinary returns, nearest(...) orders by ascending distance and bm25 and rrf by descending score, including through traversals, ranking the binding named whichever binding match declares first (details; rrf arms on two connected bindings: T59). The search function must lead; subsequent keys precede the identity tiebreak. Projected scores must repeat that leading function (T33); the Search guide defines their names and types. Rank expressions under aggregates (T32) and search predicates in return (T35) are refused.

For aggregate or DISTINCT returns, the leading search function selects the input population; it does not order the output. Subsequent keys order output rows, followed by every group or DISTINCT key ascending. Without subsequent keys, output is unordered. Aggregates cannot project scores (T9). DISTINCT uses the selected nearest population without retry overfetch, so duplicates can leave fewer rows than the limit. BM25 reads every matching entity before the final limit.

Blobs

Blob properties are not ordinary read-query values. They cannot be projected, filtered, ordered, or passed to an aggregate. Read one logical Blob cell with the CLI or HTTP Blob endpoint described in Blobs. Blob parameters remain valid for mutation assignment.

Branches and historical reads

Reads default to main. Select another branch or an immutable commit with --branch or --snapshot:

omnigraph query engineers --query queries.gq --branch review \
  --params '{"title":"Engineer"}' --target ./graph.omni

When the snapshot has an effective graph head, omnigraph query --json includes its graph_commit_id, pinned with the returned rows. Use that same-snapshot id with a later mutation's --if-commit option when implementing read-modify-write. On a newly created, unmodified branch, it is the head inherited from the source branch and is valid for the branch's first conditional mutation. See Branches, Commits, and History.

JSON result spelling

JSON rows follow Arrow's JSON conventions: OmniGraph writes them with the arrow-json writer from the result batches and keeps no per-type spelling of its own. The spellings a consumer sees:

Send a 64-bit integer above 2^53 as a decimal string, so a client that parses JSON through a double keeps every digit. On input, a JSON number for an F64 parses to the nearest F64 value, the one a GQ literal with the same digits names, so an F64 value read from rows loads back unchanged. A Date string is a calendar day, "2024-01-01"; a string that carries a time of day, such as "2024-01-01T02:00:00+05:00", is refused as a load value, a param, or a date(...) literal, and an instant belongs in a DateTime property. A DateTime holds milliseconds: a string with a non-zero digit past the third fractional digit, such as "2024-01-01T00:00:00.123456Z", is refused as a load value, a param, or a datetime(...) literal; trailing zeros, as in .123000, are accepted.

A Date or DateTime count outside the range the writer can format is refused on load. A read that meets one fails with status 500; the error names the column, the result row, and the count, and an update of that row repairs it.

Session settings

Use set, reset, and show to configure query execution. See Session settings for syntax, scopes, defaults, and CLI/HTTP usage.

Linting

Validate queries without running them; a refusal reports a stable code, its position or stage, the expectation and one fix (Diagnostics):

omnigraph lint --query queries.gq --schema schema.pg --json