@metreeca/qest - v0.10.0
    Preparing search index...

    Type Alias Selection

    Collection retrieval constraints.

    Specifies filtering, sorting, and pagination criteria for collection retrieval. Constraint keys use the "{operator}{expression}" syntax, where the Operator determines the constraint type and the Expression identifies the target property or computed value. Pagination uses the literal "@" and "#" keys.

    Selection is attached to a collection as the optional second element of a Query tuple: [Placeholder, Selection], [Union, Selection], or [Projection, Selection]. A Locales placeholder is not a Query element, so it takes no second-slot Selection; a localised property is constrained through the collection's Selection by matching (?/!).

    Important

    Filtering and ordering expressions are resolved independently of any sibling Projection bindings: an aggregate constraint may reference an aggregate that is not projected, and a projected aggregate binding need not appear in any constraint. When an aggregate expression is present in the Selection or the sibling Projection, each constraint's role depends on whether it references an aggregate: non-aggregate filters restrict the input set before grouping; a non-aggregate ordering expression sorts the groups by one of the grouping keys; aggregate filters select groups after aggregation; aggregate ordering expressions sort the groups by their post-aggregation values. Grouping is fixed by the projection alone and is never inferred from a sort key: a non-aggregate ordering expression must reference an existing grouping key, and processors must reject one that matches none.

    type Selection = {
        "@"?: number;
        "#"?: number;
        readonly [lt: `<${string}`]: Literal;
        readonly [gt: `>${string}`]: Literal;
        readonly [lte: `<=${string}`]: Literal;
        readonly [gte: `>=${string}`]: Literal;
        readonly [like: `~${string}`]: string;
        readonly [any: `?${string}`]: Options;
        readonly [all: `!${string}`]: Options;
        readonly [focus: `+${string}`]: Options;
        readonly [order: `^${string}`]: Order;
    }

    Indexable

    • readonly [lt: `<${string}`]: Literal

      Less-than filter.

      Includes resources where at least one expression value is strictly less than the Literal under the value-ordering rules.

      Applicable only where the target Expression resolves to a Literal (boolean, number, string); Reference, nested resources, and Dictionary values are not comparable. The bound and the resolved value must share the same type; cross-type comparison is unpredictable and a validating processor MUST reject it.

    • readonly [gt: `>${string}`]: Literal

      Greater-than filter.

      Includes resources where at least one expression value is strictly greater than the Literal under the value-ordering rules.

      Applicable only where the target Expression resolves to a Literal (boolean, number, string); Reference, nested resources, and Dictionary values are not comparable. The bound and the resolved value must share the same type; cross-type comparison is unpredictable and a validating processor MUST reject it.

    • readonly [lte: `<=${string}`]: Literal

      Less-than-or-equal filter.

      Includes resources where at least one expression value is less than or equal to the Literal under the value-ordering rules.

      Applicable only where the target Expression resolves to a Literal (boolean, number, string); Reference, nested resources, and Dictionary values are not comparable. The bound and the resolved value must share the same type; cross-type comparison is unpredictable and a validating processor MUST reject it.

    • readonly [gte: `>=${string}`]: Literal

      Greater-than-or-equal filter.

      Includes resources where at least one expression value is greater than or equal to the Literal under the value-ordering rules.

      Applicable only where the target Expression resolves to a Literal (boolean, number, string); Reference, nested resources, and Dictionary values are not comparable. The bound and the resolved value must share the same type; cross-type comparison is unpredictable and a validating processor MUST reject it.

    • readonly [like: `~${string}`]: string

      Text search filter.

      Includes resources where at least one of the target's values contains every whitespace-separated token of the search string as a case-insensitive substring; token order is not significant.

      Applicable only to string-valued targets; non-string literals (boolean, number), Reference, and nested resources are not searchable. A multi-valued string property matches existentially: the resource matches when at least one of its values contains every token.

      Warning

      Matching is diacritics-sensitive: diacritics normalisation is not uniformly supported across storage backends and would require extensive application-level pre-processing at storage time. For detailed matching rules and cross-backend semantics, see text search.

    • readonly [any: `?${string}`]: Options

      Disjunctive matching filter.

      Includes resources where at least one expression value equals one of the values specified by the Options set; null matches undefined. An empty option set is an absent constraint, matching all resources.

      Applicable to Literal and Reference properties (value or IRI equality) and to localised properties through the Dictionary option form; a nested resource is matched by its Reference, not its embedded state. The option must match the type of the target Expression's resolved value; a type-inconsistent option is unpredictable and a processor MUST reject it.

    • readonly [all: `!${string}`]: Options

      Conjunctive matching filter.

      Includes resources whose expression values contain every value in the Options set (set containment: the property's value set includes all options). Primarily for multi-valued properties; a single-valued property can satisfy only a single-element option set. An empty option set is an absent constraint, matching all resources. A null option requires an absent value: [null] alone selects unset properties, while null combined with present values is unsatisfiable and matches nothing (not an error); a processor may short-circuit it to an empty result without evaluating the constraint.

      Applicable to Literal and Reference properties (value or IRI equality) and to localised properties through the Dictionary option form; a nested resource is matched by its Reference, not its embedded state. The option must match the type of the target Expression's resolved value; a type-inconsistent option is unpredictable and a processor MUST reject it.

    • readonly [focus: `+${string}`]: Options

      Sort focus.

      Companion to sort order (^): resources whose expression value is one of the values in the Options set rank before the rest, with the regular ^ sort applied within each group; focus takes precedence over ^.

      Membership is tested by equality, so an option must match the target value's type; a type-inconsistent option is unpredictable and a processor MUST reject it. A null option prioritises resources whose value is absent; an empty Options set imposes no focus.

      Warning

      Like ^, focus requires a single-valued Literal target (boolean, number, string): a Reference or nested resource is not orderable, and a multi-valued target supplies no single ordering key.

    • readonly [order: `^${string}`]: Order

      Sort order.

      Orders results by expression value according to the value-ordering rules. The Order value gives the sort direction and its precedence among multiple sort keys.

      Warning

      ^ requires a single-valued Literal sort key (boolean, number, string). A Reference or nested-resource target is not sortable. A multi-valued literal property is likewise invalid directly: reduce it explicitly with a min/max aggregate, evaluated under grouped semantics.

    Index

    Properties

    Properties

    "@"?: number

    Pagination offset.

    Skips the first number resources from the filtered and ordered result set; zero is ignored (no offset). The value is a non-negative integer; a negative or non-integer value is invalid and processors MUST reject it. To make paging stable, processors append a deterministic tiebreaker after any ^ criteria (the resource identity, or the projected fields under grouped semantics), so the result order is total and page boundaries are stable across requests for unchanged data (concurrent modification between page fetches is not covered).

    "#"?: number

    Pagination limit.

    Returns at most number resources from the result set after applying offset; zero is ignored, imposing no limit (all remaining resources are returned, not an empty result). The value is a non-negative integer; a negative or non-integer value is invalid and a processor MUST reject it.