Queries

Request shape

Every field of a request, what it does, and what happens when it is left out.

A call has two parts. context comes from your server: the tenant, the user, their permissions. request comes from the client and says which page, in which order, with which filters and search.

resource
.
query
({
context
:
T
, // set by your server
request
:
QueryRequest
, // sent by the client
});

context is never read from the request body. The generated request schemas reject a body that contains it.

The type

import type { 
QueryFacetRequest
,
QueryFilterNode
,
QueryPagination
} from "drizzle-resource";
type
QueryRequest
= {
pagination
:
QueryPagination
;
sorting
:
Array
<{
key
: string; // a field path of the resource
dir
: "asc" | "desc";
}>;
filters
:
QueryFilterNode
[]; // combined with AND
search
: {
value
: string;
fields
: string[]; // [] searches the resource's default fields
};
facets
?:
QueryFacetRequest
[];
};
FieldLeft empty or outDetails
paginationThe resource's default mode and page size.Pagination
sortingsort.defaults; without defaults, no ORDER BY.Sorting
filtersNo filter beyond the scope.Filters
searchNo search when value is empty or only spaces.Search
facetsNo facet queries run.Facets

Try it

Every field can be edited. Change a key to one the resource doesn't allow, such as "sorting": [{ "key": "orderLines.product.name", "dir": "asc" }], and the engine rejects the request before running any SQL.

A full request real engine · 10,000 sample orders in your browser
requestplayground →
{
  "pagination": {
    "mode": "offset",
    "pageIndex": 1,
    "pageSize": 5,
    "count": "exact"
  },
  "sorting": [
    {
      "key": "totalAmount",
      "dir": "desc"
    }
  ],
  "search": {
    "value": "",
    "fields": []
  },
  "filters": [
    {
      "type": "condition",
      "key": "status",
      "operator": "isNot",
      "value": "cancelled"
    }
  ],
  "facets": [
    {
      "key": "status",
      "mode": "exclude-self",
      "limit": 10
    }
  ]
}
Runs when scrolled into view.

What happens before any SQL runs

  1. The resource's scope is added to the top-level filters with AND.
  2. Defaults fill in empty sorting, search fields and page size.
  3. Every sort key, filter key, search field and facet key is checked against the resource. An unknown or disallowed key throws an error naming it.

See How a request is handled for the steps that follow.

Copyright © 2026