Query API

1-based page number. Combined with limit it derives the SQL offset for you. Out-of-range pages return an empty items array with an honest meta block rather than an error.

Page size — how many rows to return. A sane upper bound is enforced server-side (max 200 rows per request): values above 200 are clamped to 200, and NaN or ≤0 values fall back to the default of 20, so a client can never ask for the entire table in one request.

Explicit row offset. When provided it takes precedence over page, which is useful for cursor-style or virtualised lists that think in absolute positions.

The conditions to apply. Pass an array of { field, operator, value } objects, or a JSON-encoded string of the same. A field the caller isn't allowed to read (a sensitive column, or one outside a field-restricted read claim) returns 403. A field that simply doesn't exist on the table is silently ignored ONLY when the caller has an unrestricted read claim (or auth is disabled); under a field-restricted read claim, any field not in the claim's allowedFields — nonexistent or not — is treated as unreadable and returns 403.

Example: [{ "field": "status", "operator": "eq", "value": "active" }]

eq/neq compare equality; gt/gte/lt/lte compare order; like/ilike match SQL patterns (ilike is case-insensitive); in/notIn test set membership against an array value; isNull/isNotNull test for NULL and ignore value; arrayOverlaps/arrayContains/arrayEmpty operate on array columns; or/and nest a FilterCondition[] group as their value and omit field.

• eq · neq— Equals / not equals.
• gt · gte · lt · lte— Greater / less than, with inclusive variants.
• like · ilike— SQL pattern match; ilike is case-insensitive.
• in · notIn— Membership test against an array of values.
• isNull · isNotNull— NULL presence check; the value field is ignored.
• arrayOverlaps · arrayContains · arrayEmpty— Array-column operators: overlap / contains against an array value, and an emptiness test.
• or · and— Group operators: value is a nested FilterCondition[]; field is omitted.

A single free-text term applied across searchFields with a case-insensitive partial match — the one-box search a UI usually wants, without composing filters by hand.

Which columns search scans, OR-combined with a case-insensitive ILIKE. Pass a COMMA-SEPARATED string (e.g. "name,description") — the server splits on commas and does not JSON-decode this field. It is required for search to do anything — with no searchFields the search term is ignored (there is no default column set). Note: the array form fails through the typed client (it JSON-encodes searchFields into a literal string), so use the comma-string form.

Example: "name,description"

An ordered list of { field, direction } where direction is 'asc' or 'desc'. Multiple entries sort by the first, then break ties with the next, and so on. Every sort field must be one the caller may read, or the list returns 403.

Example: [{ "field": "createdAt", "direction": "desc" }]

Projects the returned columns down to the requested set. Sent as a COMMA-SEPARATED string (e.g. select=id,name,price); the server splits on commas and does not JSON-decode it. id is always retained so a trimmed row stays addressable. Every requested field passes the same read gate as filter/sort: a sensitive column or a field outside a field-restricted read claim returns 403, and a field that doesn't exist on the table returns 400. Note: the array form fails through the typed client — like searchFields, select is JSON-encoded into a literal string, which the comma-split then turns into garbage field names → 400. Independently of select, three server-side trims always run: (1) an UNCONDITIONAL auth-secret redaction that strips password / password_hash / refresh_token_hash and the email-verification + password-reset token columns from every returned row and included relation at every depth (regardless of claims or whether auth is enabled); (2) config-declared `sensitive: true` columns are stripped from every returned row and included relation (at all depths) for a caller holding only the table-level read claim — the column survives ONLY when the caller holds a field-restricted read claim whose allowedFields includes it, and this stripping silently drops the column rather than returning 403; (3) claim-based field-level trimming when a field-restricted read claim applies. The (2) sensitive-column trim is the response-side complement of the filter/sort/select 403 gate above: the same per-column registry that returns 403 when such a column is used in filter/search/sort/select/distinct without the claim also scrubs it from rows on the way out. with[].columns remains parsed but unhonored.

Example: "id,name,price"

Parsed but not applied to the list query. To fetch the unique values of a single column, call GET /distinct/:field instead.

Parsed but not applied to the list query. Reserved for a future Postgres DISTINCT ON; use GET /distinct/:field for unique values today.

The relations to expand. Each RelationQuery names a relation and may add its own columns, where, limit and a nested with for deeper graphs.

The relation key as defined in relations.ts (e.g. 'author', 'comments').

Restrict which columns of the related rows come back.

Filter the related rows using the same condition shape as top-level filters.

Cap how many related rows load per parent record.

Nest another relation query to load grandchildren — the structure is fully recursive.

Whether the operation succeeded. The client uses this to route into your onAfterHandle vs onErrorHandle callbacks.

The payload. For lists it's { items, meta }; for single reads and mutations it's the record itself.

A human-readable status message, surfaced in toasts or logs.

Present only on failure; describes what went wrong.

On lists: page, limit, offset, totalItems, totalPages, hasNextPage, hasPrevPage, nextPage and prevPage — everything a pager needs, pre-computed.