---
title: Query
description: Query protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Sort Node

Represents "Order By".

<Callout type="info">
**Source:** `packages/spec/src/data/query.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { AggregationFunction, AggregationNode, DateGranularity, FieldNode, FullTextSearch, GroupByNode, JoinNode, JoinStrategy, JoinType, Query, SortNode, WindowFunction, WindowFunctionNode, WindowSpec } from '@objectstack/spec/data';
import type { AggregationFunction, AggregationNode, DateGranularity, FieldNode, FullTextSearch, GroupByNode, JoinNode, JoinStrategy, JoinType, Query, SortNode, WindowFunction, WindowFunctionNode, WindowSpec } from '@objectstack/spec/data';

// Validate data
const result = AggregationFunction.parse(data);
```

---

## AggregationFunction

### Allowed Values

* `count`
* `sum`
* `avg`
* `min`
* `max`
* `count_distinct`
* `array_agg`
* `string_agg`


---

## AggregationNode

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **function** | `Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>` | ✅ | Aggregation function |
| **field** | `string` | optional | Field to aggregate (optional for COUNT(*)) |
| **alias** | `string` | ✅ | Result column alias |
| **distinct** | `boolean` | optional | Apply DISTINCT before aggregation |
| **filter** | `[__schema0](./__schema0)` | optional | Filter/Condition to apply to the aggregation (FILTER WHERE clause) |


---

## DateGranularity

### Allowed Values

* `day`
* `week`
* `month`
* `quarter`
* `year`


---

## FieldNode

### Union Options

This schema accepts one of the following structures:

#### Option 1

Type: `string`

---

#### Option 2

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ |  |
| **fields** | `[#](./#)[]` | optional |  |
| **alias** | `string` | optional |  |

---


---

## 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` | ✅ | Enable fuzzy matching (tolerates typos) |
| **operator** | `Enum<'and' \| 'or'>` | ✅ | Logical operator between terms |
| **boost** | `Record<string, number>` | optional | Field-specific relevance boosting (field name -> boost factor) |
| **minScore** | `number` | optional | Minimum relevance score threshold |
| **language** | `string` | optional | Language for text analysis (e.g., "en", "zh", "es") |
| **highlight** | `boolean` | ✅ | Enable search result highlighting |


---

## 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 |

---


---

## JoinNode

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `Enum<'inner' \| 'left' \| 'right' \| 'full'>` | ✅ | Join type |
| **strategy** | `Enum<'auto' \| 'database' \| 'hash' \| 'loop'>` | optional | Execution strategy hint |
| **object** | `string` | ✅ | Object/table to join |
| **alias** | `string` | optional | Table alias |
| **on** | `[__schema0](./__schema0)` | ✅ | Join condition |
| **subquery** | `[__schema1](./__schema1)` | optional | Subquery instead of object |


---

## JoinStrategy

### Allowed Values

* `auto`
* `database`
* `hash`
* `loop`


---

## JoinType

### Allowed Values

* `inner`
* `left`
* `right`
* `full`


---

## Query

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **object** | `string` | ✅ | Object name (e.g. account) |
| **fields** | `[__schema0](./__schema0)[]` | optional | Fields to retrieve |
| **where** | `[__schema1](./__schema1)` | optional | Filtering criteria (WHERE) |
| **search** | `Object` | optional | Full-text search configuration ($search parameter) |
| **orderBy** | `Object[]` | 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** | `Record<string, any>` | optional | Cursor for keyset pagination |
| **joins** | `Object[]` | optional | Explicit Table Joins |
| **aggregations** | `Object[]` | optional | Aggregation functions |
| **groupBy** | `string \| Object[]` | optional | GROUP BY targets (strings or `{field, dateGranularity?}` objects for date bucketing) |
| **having** | `[__schema1](./__schema1)` | optional | HAVING clause for aggregation filtering |
| **windowFunctions** | `Object[]` | optional | Window functions with OVER clause |
| **distinct** | `boolean` | optional | SELECT DISTINCT flag |
| **expand** | `Record<string, [#](./#)>` | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select, filter, sort, and further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3. |


---

## SortNode

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ |  |
| **order** | `Enum<'asc' \| 'desc'>` | ✅ |  |


---

## WindowFunction

### Allowed Values

* `row_number`
* `rank`
* `dense_rank`
* `percent_rank`
* `lag`
* `lead`
* `first_value`
* `last_value`
* `sum`
* `avg`
* `count`
* `min`
* `max`


---

## WindowFunctionNode

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **function** | `Enum<'row_number' \| 'rank' \| 'dense_rank' \| 'percent_rank' \| 'lag' \| 'lead' \| 'first_value' \| 'last_value' \| 'sum' \| 'avg' \| 'count' \| 'min' \| 'max'>` | ✅ | Window function name |
| **field** | `string` | optional | Field to operate on (for aggregate window functions) |
| **alias** | `string` | ✅ | Result column alias |
| **over** | `Object` | ✅ | Window specification (OVER clause) |


---

## WindowSpec

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **partitionBy** | `string[]` | optional | PARTITION BY fields |
| **orderBy** | `Object[]` | optional | ORDER BY specification |
| **frame** | `Object` | optional | Window frame specification |


---

