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.
| Field | Presence | Shape |
|---|---|---|
source | Required | sourceRef |
inputs | Optional | propertyMap |
returns | Required | object |
sql | Required | string |
freshness | Optional | freshness |
expose | Optional | expose |
tests | Optional | testRefs |
invalidation | Optional | object |
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.
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
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.