Getting started

Quick start

Create the engine, define a resource for an orders table, and run a request against it.

This page builds an orders endpoint in three steps. The examples use an orders table with a customer relation and orderLines that point to products.

1. Create the engine

Create the engine once and share it between resources.

engine.ts
import { 
createQueryEngine
} from "drizzle-resource";
import {
db
} from "./db";
import {
schema
} from "./schema";
import {
relations
} from "./relations";
export const
engine
=
createQueryEngine
({
db
,
schema
,
relations
}).
withContext
<{
orgId
: string }>();

.withContext<T>() declares the per-request values your server passes in, here the caller's organisation. The scope function and custom stages receive it. Leave it out if you don't need request context.

2. Define a resource

A resource names the root table, the relations to load with each row, and what clients are allowed to do.

orders.resource.ts
import { 
engine
} from "./engine";
export const
ordersResource
=
engine
.
defineResource
("orders", {
// Relations loaded with each row
relations
: {
customer
: true,
orderLines
: {
with
: {
product
: true },
}, },
query
: {
// Added to every request on the server. Clients cannot remove it.
scope
: (
f
,
ctx
) =>
f
.
is
("customer.orgId",
ctx
.
orgId
),
// Fields a search may match. `defaults` is used when the request lists none.
search
: {
allowed
: ["reference", "customer.name", "orderLines.product.name"],
defaults
: ["reference", "customer.name"],
}, // Order used when the request sends no sorting
sort
: {
defaults
: [{
key
: "createdAt",
dir
: "desc" }],
}, // Fields that clients may request bucket counts for
facets
: {
allowed
: ["status", "customer.name", "orderLines.product.category"],
},
pagination
: {
modes
: ["cursor", "offset"],
},
defaults
: {
pagination
: {
mode
: "cursor",
pageSize
: 25 },
}, }, });

3. Run a request

Call query from your route handler. context comes from your server, request from the client.

orders.controller.ts
import { 
ordersResource
} from "./orders.resource";
const
result
= await
ordersResource
.
query
({
context
: {
orgId
: "acme" },
request
: {
pagination
: {
mode
: "cursor",
pageSize
: 25 },
sorting
: [{
key
: "createdAt",
dir
: "desc" }],
// fields: [] searches the resource's default fields
search
: {
value
: "laptop",
fields
: [] },
// Top-level filters are combined with AND
filters
: [
{
type
: "condition",
key
: "status",
operator
: "isAnyOf",
value
: ["pending", "processing"],
}, ],
context
: {},
facets
: [
{
key
: "status",
mode
: "exclude-self",
limit
: 10 },
{
key
: "customer.name",
mode
: "include-self",
limit
: 20 },
], }, });
result
.
rows
; // typed rows, with customer and orderLines loaded
result
.
pageInfo
; // next cursor, and the exact count when requested
result
.
facets
; // one bucket list per requested facet

See it run

The example below runs a similar request on 10,000 sample orders, in your browser, with the real engine. Open sql for the statements it ran, or edit to change the request: invalid keys fail with the same errors as on your server.

Pending and processing orders real engine · 10,000 sample orders in your browser
requestplayground →
{
  "sorting": [
    {
      "key": "createdAt",
      "dir": "desc"
    }
  ],
  "search": {
    "value": "",
    "fields": []
  },
  "filters": [
    {
      "type": "condition",
      "key": "status",
      "operator": "isAnyOf",
      "value": [
        "pending",
        "processing"
      ]
    }
  ],
  "facets": [
    {
      "key": "status",
      "mode": "exclude-self",
      "limit": 10
    },
    {
      "key": "orderLines.product.category",
      "mode": "exclude-self",
      "limit": 10
    }
  ]
}
Runs when scrolled into view.

The five methods

MethodUse it when
resource.query(...)You want a page: ids, rows, and facets or totals if requested.
resource.findById(...)You need one row by id, with the scope applied.
resource.queryIds(...)You only need the ids of a page and its page information.
resource.queryRows(...)You already have ordered ids and need the rows.
resource.queryFacets(...)You need facet counts without the page.

Start with query. The narrower methods are for caching and batching flows.

Next

Copyright © 2026