Skip to manual
gluon

GOL language

Query

A Query is a tested, read-only query against a live source that returns rows of an ontology type, served as a tool.

Model author or developer

Where it goes

Contoso keeps contracts-by-supplier in queries/contracts-by-supplier.yaml. The loader reads every YAML file under the package root, so folders are a convention you can change. Name it in lowercase kebab-case. The name must be unique among the package's Query resources.

Limits

The validator checks a Query's placeholders, inputs and selected columns. Running it needs a source connection, which is being built.

Fields

The keys under spec. Nested shapes follow QuerySpec in the GOL JSON Schema.

FieldPresenceShape
sourceRequiredsourceRef
inputsOptionalpropertyMap
returnsRequiredobject
sqlRequiredstring
freshnessOptionalfreshness
exposeOptionalexpose
testsOptionaltestRefs
invalidationOptionalobject

Syntax and rules

The examples are fragments. Put them in a package next to the resources they reference. A ... stands for a CEL expression you write yourself.

9.8 Query

A tested, parameterised, read-only query against a live source, returning rows of an ontology type. A flat resource with a kebab name (query:<name>), exposed as the tool tool:<source>/<name> with effect: Read by construction. Decided 2026-10-10 (Waseem): its own kind, not a Function variant; Function impl: sql stays declared and refused at runtime.

GOL · YAML
kind: Query
metadata: { name: contracts-by-supplier, title: Live contracts of one supplier }
spec:
  source: "source:erp-live" # required
  inputs: # the same shape as Function inputs
    supplierId: { type: uuid, required: true }
    asOf: { type: date, required: false }
  sql: |
    select CONTRACT_NO, TOTAL_VALUE, CURR from PROC.CONTRACTS where SUPPLIER_ID = :supplierId::uuid
  returns: { type: procurement.Contract, many: true } # type required; rows project through its mapping for the source
  freshness: live # or an ISO duration of at most one year (GLN-E010): the memory window
  expose: { chat: true, mcp: { tool: contracts_by_supplier } }
  invalidation: { event: procurement.ContractRenewed } # optional: memory of this query is dropped when the event passes
  tests: ["test:renewal-assistant"]

Inputs bind as placeholders (:name), never by string formatting. An input is checked against its type before the call and sent as a parameter; a uuid input must be a UUID and is sent as text, so where the column is uuid the SQL casts it (:supplierId::uuid), and a column that keeps UUIDs as text compares as written (decided 2026-10-10). Every placeholder needs an input of that name (GLN-E462), and every input is used or declared optional with required: false or a default (GLN-E463). A plain column in the top-level select list that the return type's sources[] mapping for this source does not map is GLN-E461 (a best-effort reading of the select list, with string literals and comments ignored: expressions and * are not checked; the runtime guard and the row projection are the enforcement). When the type maps nothing from the source, the columns are not checked and the Query gets GLN-W464; a struct return type (an aggregate) has no mapping to check columns against, so its SQL is parsed instead, in each of the three dialects, and every table it reads must be one a type maps from that source (sources[].table, a LinkType's join table or the Source's scope.table, CTE names and subqueries read as the engine reads them), or the Query is GLN-E465 (decided 2026-11-09, Waseem); the same check refuses it at run time. A new Query, or a changed sql or returns, is GLN-W653.

Check your package

Shell
gluon validate examples/contoso
gluon test examples/contoso

validate reports each problem with a GLN code and its place in the file. test runs the package's Test resources. See the language guide and the diagnostics.