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 query has five parts:

Part	Required	Purpose
`query`	yes	Keyword followed by the query name
params	no	Typed parameters in parentheses
`match`	yes	Patterns that bind variables to graph data
`return`	yes	Properties and expressions to output
`order`	no	Sort keys with `asc` or `desc`
`limit`	no	Maximum number of rows to 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: String, Bool, I32, I64, U32, U64, F32, F64, Date, DateTime.

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:

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

Running queries

CLI

Run a named query from a .gq file:

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

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

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

[
  { "name": "Bob", "age": 32 },
  { "name": "Carol", "age": 28 }
]

HTTP API

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

curl -X POST http://localhost:4242/query \
    -H "Content-Type: application/json" \
    -d '{
        "file": "queries.gq",
        "name": "friends_of",
        "params": { "name": "Alice" }
    }'