Skip to content

query.mdx

Latest commit

 

History

History
269 lines (176 loc) · 6.95 KB

query.mdx

File metadata and controls

269 lines (176 loc) · 6.95 KB
Raw
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".

**Source:** `packages/spec/src/data/query.zod.ts`

TypeScript Usage

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 (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'> ✅

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