Type Alias Query

Resource retrieval query.

Defines the shape and content of a Resource object to be retrieved. Properties are mapped to Model values specifying what to retrieve:

• Literal — Plain literal
• Query — Nested resource
• { readonly [range: TagRange]: string } — Single-valued Dictionary; TagRange key selects language tags to retrieve; string is a placeholder
• { readonly [range: TagRange]: [string] } — Multi-valued Dictionary; TagRange key selects language tags to retrieve; array marks multi-valued
• readonly [Query] — Nested resource collection; singleton Query element provides filtering, ordering, and paginating criteria for members
• [] — Nothing (ignored during processing)

Queries may also define computed properties, whose value is computed from an Expression; in this case, the projection defines the expected type of the computed value.

Scalar values in projections serve as type placeholders; their actual value is immaterial, but their type must match the (possibly computed) property definition.

This model enables efficient single-call retrieval of exactly the data needed, without over or under-fetching.

Important: The query is rejected with an error if it references undefined properties or if it provides projections or constraints of mismatched types for defined properties.

Filtering and Ordering Constraints

Queries support constraints for filtering, ordering, and paginating resource collections. Filtering and ordering constraints select the collection subset to retrieve; each constraint is applied to the value computed by an Expression from a candidate member resource. Pagination constraints are applied to the filtered and ordered result set.

The following constraints are supported:

• less than — "<expression": Literal

  Includes resources where at least one expression value is less than the literal.

• less than or equal — "<=expression": Literal

  Includes resources where at least one expression value is less than or equal to the literal.

• greater than — ">expression": Literal

  Includes resources where at least one expression value is greater than the literal.

• greater than or equal — ">=expression": Literal

  Includes resources where at least one expression value is greater than or equal to the literal.

• stemmed word search — "~expression": string

  Includes resources where at least one expression value contains all word stems from the search string, in the given order.

• disjunctive matching — "?expression": Options

  Includes resources where at least one expression value equals at least one of the specified Options; applies to both single and multi-valued properties; null matches resources where the property is undefined.

• conjunctive matching — "!expression": Options

  Includes resources whose expression values include all specified Options; applies to multi-valued properties.

• focus ordering — "*expression": Options

  Orders results prioritizing resources whose expression value appears in the specified Options; matching resources appear before non-matching ones; overrides regular sorting criteria.

• sort ordering — "^expression": number

  Orders results by expression value; the sign of the priority gives ordering direction (positive for ascending, negative for descending); the absolute value gives 1-based ordering precedence (1 is highest priority); zero is ignored; "asc"/"ascending" and "desc"/"descending" are shorthands for ±1.

• offset — "@": number

  Skips the first number resources from the filtered and ordered result set; zero is ignored.

• limit — "#": number

  Returns at most number resources from the result set after applying offset; zero is ignored.