# 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](/content/docs/queries-search/mutations.md). 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](/content/docs/branching.md)), a `show` statement (see [session settings](#session-settings)), or an `explain` statement, which answers the plan a read query would run under instead of its rows (see [Explain](/content/docs/queries-search/explain.md)). Any of them may open with [session settings](#session-settings) lines.

```graphql
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:

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

## Declarations and parameters

```text
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](/content/docs/queries-search/traversal.md). 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](/content/docs/queries-search/mutations.md).

### 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](#boolean-expressions-and-nulls) 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](/content/docs/queries-search/explain.md)); 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.

```graphql
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

* `$x.tags contains "rust"` tests membership when `tags` is a list.
* `$x.number in $numbers` tests membership in a list parameter or literal
  (`$x.number in ["A-1", "A-2"]`): `$numbers contains $x.number` with the
  list, of the value's type (`T7`), on the right. On a matched binding's
  property it filters that binding's scan. An empty list has no member: `in`
  keeps no row, `not (... in [])` keeps the rows whose value is not null.
* `$x.title contains "graph"` tests exact, case-sensitive substring containment
  when `title` is a String.
* `$x.title starts_with "Omni"` tests an exact, case-sensitive prefix.

`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](/content/docs/queries-search/search.md) 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](/content/docs/queries-search/catalogue.md).

## Return, order, and limit

```graphql
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](/content/docs/queries-search/search.md#ranking-a-traversal-reached-binding/index.html); `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](/content/docs/queries-search/search.md)
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](/content/docs/schema/blobs.md). 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`:

```bash
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](/content/docs/branching.md).

## 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:

* A null cell's key is omitted from its row, and from a struct cell; a null
  element inside a list value stays `null`.
* `Date` is `"2024-01-01"`; `DateTime` is `"2024-01-01T12:34:56.789"` in UTC
  with no `Z`, and no fractional part when it is zero.
* Integers of every width are bare numbers; JavaScript's `JSON.parse` rounds
  values beyond 2^53.
* `F32` prints at 32-bit width (`0.99`) and `F64` at 64-bit width; integral
  floats carry `.0`; magnitudes from 1e10 up or below 1e-5 take exponent form
  (`1.0e20`, `1.0e-7`); a non-finite computed value is `null`.
* `Vector(N)` and list properties are JSON arrays.

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](/content/docs/queries-search/settings.md) 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](/content/docs/queries-search/diagnostics.md)):

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