Query Constraints

Query Constraints

Bases: `NormanBaseModel`

Container object defining query constraints for filtering, sorting, and paginating backend lookup operations.

A QueryConstraints instance can include one or more of:

A filter tree (logical expression)
A sort tree
Pagination instructions

Fields

filter (Optional[FilterClause]) Root filter clause describing complex logical filtering using nested clauses and nodes. If omitted, no filtering is applied.
sort (Optional[SortClause]) Sorting instructions, represented as a tree of sort nodes. None means no ordering is enforced.
page (Optional[PageClause]) Pagination configuration specifying limit and offset. If None, pagination defaults are determined by the API endpoint.

Filter Clause

Bases: `NormanBaseModel`

Represents a composite filter expression, allowing nested logical conditions (AND/OR) across multiple filter nodes or sub-clauses.

A FilterClause forms part of a tree structure enabling complex, arbitrarily nested filtering logic.

Fields

children (list[Union[FilterClause, FilterNode]]) A list of either:
FilterClause - sub-clause for grouping
FilterNode - leaf comparison expression
join_condition (UnaryRelation) Logical operator used to join child nodes:
UnaryRelation.AND
UnaryRelation.OR

Filter Node

Bases: `NormanBaseModel`

Leaf node representing a single comparison expression used in filtering.

A FilterNode specifies a column, operator, and value to compare against, optionally scoped to a particular table.

Fields

table (str) Table or entity name that the filter applies to.
column (str) Column name within the table. Defaults to "ID".
operator (BinaryRelation) Comparison operator such as:
- BinaryRelation.EQ
- BinaryRelation.NE
- BinaryRelation.GT
- BinaryRelation.GTE
- BinaryRelation.LT
- BinaryRelation.LTE
- BinaryRelation.IN
- BinaryRelation.NOT_IN
value (FilterTypeVar) Value to compare against. Fully parameterized as:
FilterTypeValue - single scalar value
- str
- int
- float
FilterTypeCollection - multi-value collection Used primarily with operators like IN or NOT_IN.
- list[FilterTypeValue]
- set[FilterTypeValue]
- tuple[FilterTypeValue]

Thus value may be either:

A single scalar (e.g., "A", 42, 3.14), or
A collection of scalars (e.g., ["A", "B"], {1, 2}, (3, 4, 5)).

Sort Clause

Bases: `NormanBaseModel`

Represents a structured sort definition consisting of one or more sort directives ordered by priority.

Fields

children (list[SortNode]) Ordered list of sort instructions.

table (str) Table or entity name used for sorting.
column (str) Column name to sort by. Defaults to "ID".
direction (SortDirection) Direction of sorting:
SortDirection.ASC
SortDirection.DESC

Sort Direction

Bases: `str`, `Enum`

Sort direction enum used to specify ascending or descending order.

Values

ASC - Sort in ascending order
DESC - Sort in descending order

Page Clause

Bases: `NormanBaseModel`

Pagination configuration specifying record range selection.

Fields

limit (Optional[int]) Maximum number of records to return. None means no explicit limit.
offset (Optional[int]) Starting position in the record set. Useful for page-based navigation.

2026

Query Constraints