Methods
| Method | Runs | Returns |
|---|---|---|
query | page ids, rows, then facets and summary if asked | { rows, pageInfo, facets?, summary? } |
findById | one row by root id, with the scope | the row or null |
queryIds | page ids only | { ids, pageInfo } |
queryRows | rows for ids you already have | rows, in the order of the ids |
queryFacets | facets only | { facets } |
querySummary | the summary only | the summary |
scan | every matching row, in batches | what your callback returns |
Every method takes the server context. query, findById, queryRows and scan also accept view or load to choose what each row contains.
resource.scan(options, consume)
Reads every matching row in batches, through an async iterable. PostgreSQL uses one cursor and one snapshot; other databases and custom steps page through the selection. The engine waits for your consumer between batches.
See Bulk scans for options, cancellation, exact totals and transactions.
resource.query(options)
Runs the whole request: page ids, rows, and facets or the summary when the request asks for them.
const result = await ordersResource.query({
context: { orgId: "acme" },
request: {
pagination: { mode: "offset", pageIndex: 1, pageSize: 25 },
sorting: [{ key: "createdAt", dir: "desc" }],
search: { value: "", fields: [] },
filters: [],
facets: [{ key: "status", mode: "exclude-self", limit: 10 }],
},
});
// result: { rows: TRow[]; pageInfo: QueryPageInfo; facets?: QueryFacetResult[] }
Returns: { rows, pageInfo, facets? }
rows: the page, typed from the load default, theloadoption or theview.pageInfo: the page information for the mode, withrowCountwhen an exact count was requested.facets: only whenrequest.facetsis not empty.summary: only when the call passessummary: true.
resource.findById(options)
Loads one row by its root id, with the scope applied and the findById load default.
const order = await ordersResource.findById({
id: "order_123",
context: { orgId: "acme" },
});
// order: hydrated order row | null
Returns: TRow | null
Use it for detail pages and before updates: a row outside the caller's scope comes back as null.
Choosing what rows contain
query, findById, scan and queryRows accept load, a named profile or a relation subset, or view, an exact view. Pass one or the other. The row type follows the choice. Both are set by your server, not by the client.
const detailPage = await ordersResource.query({
request,
context: { orgId: "acme" },
load: "detail",
});
const customerOnly = await ordersResource.findById({
id: "order_123",
context: { orgId: "acme" },
load: { customer: true },
});
queryIds and queryFacets don't load rows, so they accept neither.
resource.queryIds(options)
Runs only the page-ids step.
const { ids, pageInfo } = await ordersResource.queryIds({
context: { orgId: "acme" },
request,
});
Background jobs can raise the page-size limit for one call with execution.maxPageSize. Set it in your code, never from client input.
Returns: { ids: TId[], pageInfo: QueryPageInfo }
Use it to cache page ids separately from rows, to load rows in another service, or to select ids for several resources before loading.
resource.queryRows(options)
Loads the rows for ids you already have, without selecting ids again.
const rows = await ordersResource.queryRows({
context: { orgId: "acme" },
request,
ids, // ordered ids from a previous queryIds call
});
Pass the same execution.maxPageSize used for queryIds when the request page size exceeds the resource's public limit.
Returns: TRow[]
Rows come back in the order of ids. No count runs.
resource.queryFacets(options)
Computes facets without the page.
const { facets } = await ordersResource.queryFacets({
context: { orgId: "acme" },
request,
facets: [{ key: "status", mode: "exclude-self", limit: 10 }],
});
Returns: { facets: QueryFacetResult[] }
Use it when a filter sidebar refreshes separately from the table.
Return types
import type {
QueryFacetResult,
QueryFacetsResponse,
QueryIdsResponse,
QueryResponse,
} from "drizzle-resource";
type QueryResponseExample<TRow> = QueryResponse<TRow>;
type QueryIdsResponseExample<TId> = QueryIdsResponse<TId>;
type QueryFacetsResponseExample = QueryFacetsResponse;
type QueryFacetResultExample = QueryFacetResult;