Quick start
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.
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.
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.
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.
The five methods
| Method | Use 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.