Reference

Methods

Every method of a resource, what it runs and what it returns.
MethodRunsReturns
querypage ids, rows, then facets and summary if asked{ rows, pageInfo, facets?, summary? }
findByIdone row by root id, with the scopethe row or null
queryIdspage ids only{ ids, pageInfo }
queryRowsrows for ids you already haverows, in the order of the ids
queryFacetsfacets only{ facets }
querySummarythe summary onlythe summary
scanevery matching row, in batcheswhat 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, the load option or the view.
  • pageInfo: the page information for the mode, with rowCount when an exact count was requested.
  • facets: only when request.facets is not empty.
  • summary: only when the call passes summary: 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
;
Copyright © 2026