ObjectStackQuery
Query protocol schemas
Sort Node
Represents "Order By" — one { field, order } pair. Unknown keys are
REJECTED (#4721); spell the direction order, never direction.
Source: packages/spec/src/data/query.zod.ts
TypeScript Usage
import { AggregationFunction, AggregationNodeSchema, DateGranularity, FieldNodeSchema, FullTextSearchSchema, GroupByNodeSchema, QuerySchema, SortNodeSchema } from '@objectstack/spec/data';
import type { AggregationFunction, AggregationNode, FieldNode, FullTextSearch, GroupByNode, SortNode } from '@objectstack/spec/data';
// Validate data
const result = AggregationFunction.parse(data);AggregationFunction
Allowed Values
countsumavgminmaxcount_distinct
AggregationNode
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| function | Enum<'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct'> | ✅ | Aggregation function |
| field | string | optional | Field to aggregate (optional for COUNT(*)) |
| alias | string | ✅ | Result column alias |
| distinct | never | optional | [REMOVED] query.aggregations[].distinct was removed in @objectstack/spec 17 (#6815, ADR-0049) — exactly ONE of the six faces that read an aggregation honoured it. The objectql in-memory fallback deduplicated the values before applying the function, while driver-sql, driver-turso, driver-mongodb, driver-memory and the service-analytics SQL builder all ignored it — so { function: 'sum', field: 'amount', distinct: true } answered a DEDUPLICATED sum when the engine fell back in memory and an ordinary sum on every SQL datasource: one query, two numbers, chosen by which backend happened to serve it. Both answers are plausible, so nothing surfaced the divergence. Delete the key. For a deduplicated COUNT the live spelling is the count_distinct aggregation function, which every SQL face compiles to COUNT(DISTINCT field) (#6409) and the in-memory fallback computes identically. SUM(DISTINCT …) / AVG(DISTINCT …) get no replacement: no backend ever computed them here, and a per-row measure that needs deduplicating is a modelling problem to fix in the data, not a flag on the read. |
| filter | any | optional | [EXPERIMENTAL — not enforced] Per-aggregation filter (SQL FILTER (WHERE …)). Neither the SQL builders nor the in-memory fallback applies it (#4286); filter the whole query with where instead. |
DateGranularity
Allowed Values
dayweekmonthquarteryear
FieldNode
Type: string
FullTextSearch
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| query | string | ✅ | Search query text |
| fields | string[] | optional | Fields to search in (if not specified, searches all text fields) |
| fuzzy | boolean | ✅ | [EXPERIMENTAL — not enforced] Fuzzy matching (tolerate typos). The ADR-0061 expansion reads only query + fields; no executor receives this flag (#4286). |
| operator | Enum<'and' | 'or'> | ✅ | [EXPERIMENTAL — not enforced] Logical operator between terms. The ADR-0061 expansion applies its own term semantics; no executor receives this flag (#4286). |
| boost | Record<string, number> | optional | [EXPERIMENTAL — not enforced] Field-specific relevance boosting (field name -> boost factor). No executor scores results (#4286). |
| minScore | number | optional | [EXPERIMENTAL — not enforced] Minimum relevance score threshold. No executor scores results (#4286). |
| language | string | optional | [EXPERIMENTAL — not enforced] Language for text analysis (e.g., "en", "zh", "es"). No executor selects an analyzer (#4286). |
| highlight | boolean | ✅ | [EXPERIMENTAL — not enforced] Search result highlighting. No executor emits highlights (#4286). |
GroupByNode
Union Options
This schema accepts one of the following structures:
Option 1
Type: string
Option 2
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| field | string | ✅ | Field to group by |
| dateGranularity | Enum<'day' | 'week' | 'month' | 'quarter' | 'year'> | optional | Bucket date values into uniform periods (day/week/month/quarter/year) |
| alias | string | optional | Alias for the projected group value |
Query
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| object | string | ✅ | Object name (e.g. account) |
| fields | string[] | optional | Fields to retrieve — names of the queried object's OWN columns. A dotted path (owner.name) is not a projection: no driver resolves one, and the ingress refuses it with 400 INVALID_FIELD (#7532). Related data is read with expand, whose nested QueryAST both filters (where) and selects (fields) the related record's columns. The projection must RETAIN the foreign-key column: fields: ['title'] with expand: 'project_id' resolves nothing, because the relation is carried by that key — add 'project_id' and it works. Where the value is wanted on the queried object itself, denormalise it onto that object (a stored field, written when the source changes), the same remedy the sort axis prescribes (#6924). |
| where | any | optional | Filtering criteria (WHERE) |
| search | string | { query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' | 'or'>; … } | optional | Full-text search — the query text (canonical, ADR-0061 D1), or a structured FullTextSearch configuration |
| searchFields | string[] | optional | Narrow the search to these fields (server-intersected with the allowed searchable set — can only narrow, never widen; ADR-0061 D1) |
| orderBy | { field: string; order: Enum<'asc' | 'desc'> }[] | optional | Sorting instructions (ORDER BY) |
| limit | number | optional | Max records to return (LIMIT) |
| offset | number | optional | Records to skip (OFFSET) |
| top | number | optional | Alias for limit (OData compatibility) |
| cursor | never | optional | [REMOVED] query.cursor was removed in @objectstack/spec 17 (#4286, ADR-0049) — no driver ever implemented keyset pagination, so the cursor was accepted and ignored and every page came back identical (a caller looping "until hasMore is false" never terminates). Delete the key; QueryBuilder.cursor() was removed with it. Express the keyset as an ordinary where predicate on your sort key — where: { created_at: { $gt: last.created_at } } with the matching orderBy — which every driver executes with canonicalised comparands. A first-class cursor, if ever built, will be a response-minted opaque token, not this caller-built record. |
| joins | never | optional | [REMOVED] query.joins was removed in @objectstack/spec 17 (#4286, ADR-0049) — no engine or driver ever read it: a query carrying joins behaved exactly as if the key were absent, while its name squatted on the reserved REST parameter set. Delete the key. Related records are read through expand — expand: { owner_id: { object: 'user', fields: ['name'] } } — which the engine resolves via batch $in queries, and whose nested query selects the related record's own columns. Keep the foreign key in your own projection (fields: ['title', 'owner_id']): the relation is carried by that column, so projecting it away leaves expansion nothing to resolve. A dotted fields path is NOT a replacement — no driver ever resolved one and the ingress refuses it (400 INVALID_FIELD, #7532). |
| aggregations | { function: Enum<'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct'>; field?: string; alias: string; filter?: any }[] | optional | Aggregation functions |
| groupBy | (string | { field: string; dateGranularity?: Enum<'day' | 'week' | 'month' | 'quarter' | 'year'>; alias?: string })[] | optional | GROUP BY targets (strings or {field, dateGranularity?} objects for date bucketing) |
| having | any | optional | HAVING — filter over the AGGREGATED rows (aggregation aliases + groupBy projections); applied engine-side after aggregation |
| windowFunctions | never | optional | [REMOVED] query.windowFunctions was removed in @objectstack/spec 17 (#4286, ADR-0049) — find() never applied it: no engine or driver read the key on the query path, so every OVER clause it declared was silently dropped. Delete the key. Window functions are a SQL-driver capability behind SqlDriver.findWithWindowFunctions(object, query) (embedder-level; not on the IDataDriver contract or the REST surface); request-level analytics are aggregations + groupBy. |
| distinct | never | optional | [REMOVED] query.distinct was removed in @objectstack/spec 17 (#4286, ADR-0049 / ADR-0078) — no driver ever rendered SELECT DISTINCT; the flag's only observable effect was MIS-WIRED: the REST list path treated a distinct query as not countable and silently degraded total/hasMore to a page-local estimate while still returning duplicate rows. Delete the key; QueryBuilder.distinct() was removed with it, and the count suppression is gone (total is truthful again). For unique values of one column use the SQL/memory drivers' distinct(object, field) door; for unique combinations, groupBy; for a deduplicated count, the count_distinct aggregation. |
| expand | Record<string, [Query](#query)> | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select (fields) and filter (where, AND-merged with the batch $in), plus further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3; per-parent limit/offset/orderBy are NOT applied on this path. |
SortNode
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| field | string | ✅ | |
| order | Enum<'asc' | 'desc'> | ✅ |