Queries

Learn how .gq query files are structured, named, parameterized, and run against your graph.

Omnigraph queries live in .gq files. Each file can contain multiple named queries, each with typed parameters, a match block for pattern matching, and a return block for shaping output.

Query anatomy

query friends_of($name: String) {
    match {
        $p: Person { name: $name }
        $p knows $f
    }
    return { $f.name, $f.age }
    order { $f.name asc }
    limit 20
}

Every read query has up to six parts:

Part	Required	Purpose
`query`	yes	Keyword followed by the query name
params	no	Typed parameters in parentheses
query annotations	no	`@description(...)` or `@instruction(...)` after the signature
`match`	yes	Patterns that bind variables to graph data
`return`	yes	Properties and expressions to output
`order`	no	Sort keys inside `order { ... }`
`limit`	no	Maximum number of rows to return

Mutation queries use the same query name(params) header but contain insert, update, or delete statements instead of match / return.

Parameters

Parameters are declared with a name and a type. They are referenced with $ inside the query body.

query by_age_range($min: I32, $max: I32) {
    match {
        $p: Person
        $p.age >= $min
        $p.age <= $max
    }
    return { $p.name, $p.age }
}

Supported parameter types include scalar types, lists of scalar types such as [String], and vectors such as Vector(1536).

Multiple queries per file

A single .gq file can contain several queries. Select which to run with --name:

query all_people() {
    match { $p: Person }
    return { $p.name }
}

query all_companies() {
    match { $c: Company }
    return { $c.name }
}

Annotations

Annotate queries with @description and @instruction to document intent or guide agent workflows:

query people_at($company: String) @description("Find people by company name") @instruction("Use this when the user asks about employees") {
    match {
        $c: Company { name: $company }
        $p worksAt $c
    }
    return { $p.name }
}

Running queries

CLI

Run a named query from a .gq file:

omnigraph read --uri ./repo.omni \
    --query queries.gq \
    --name friends_of \
    --params '{"name": "Alice"}'

Add --json for structured JSON output, or --branch to target a specific branch:

omnigraph read --uri ./repo.omni \
    --query queries.gq \
    --name by_age_range \
    --params '{"min": 25, "max": 40}' \
    --branch feature-x \
    --json

{
  "query_name": "by_age_range",
  "target": {
    "branch": "feature-x",
    "snapshot": null
  },
  "row_count": 2,
  "columns": ["name", "age"],
  "rows": [
    { "name": "Bob", "age": 32 },
    { "name": "Carol", "age": 28 }
  ]
}

HTTP API

When running Omnigraph in server mode, execute queries via POST /read:

curl -X POST http://localhost:8080/read \
    -H "Content-Type: application/json" \
    -d '{
        "query_source": "query friends_of($name: String) { match { $p: Person { name: $name } $p knows $f } return { $f.name, $f.age } }",
        "query_name": "friends_of",
        "params": { "name": "Alice" },
        "branch": "main"
    }'