Resources

Define a resource

Every option of defineResource, what it controls, and the page that covers it in detail.

engine.defineResource(root, options) creates a resource for one root table. Every option is optional except the root name.

import { 
engine
} from "./engine";
const
ordersResource
=
engine
.
defineResource
("orders", {
relations
: {}, // relations that may be loaded and used in field paths
hydration
: {}, // named subsets of relations per read method
views
: {}, // exact response shapes
query
: {}, // scope, search, sort, filters, facets, pagination, defaults
summary
:
undefined
, // totals over the filtered set
strategy
: {}, // custom implementations of single steps
});
OptionControlsDetails
rootThe table the resource is built on, by its name in your schema.This page
relationsWhich relations exist for this resource, for loading and field paths.Relations
hydrationWhich relations each read method loads by default.Relations
viewsExact response shapes, each with an inferred row type.Views
queryScope, search, sorting, filters, facets, pagination and defaults.Below
summaryAggregates over the whole filtered set.Summaries
strategyYour own implementation of the ids, rows, facets or full query step.Strategies

relations

The relations a resource may load and use in field paths:

import { 
engine
} from "./engine";
engine
.
defineResource
("orders", {
relations
: {
customer
: true,
orderLines
: {
with
: {
product
: true,
}, }, }, });

This makes customer.name, orderLines.product.name and orderLines.product.category valid paths for search, sorting, filters and facets. Filtering through a relation does not require returning it: the page-ids query joins what the filters need, row loading uses what the read method asks for.

hydration

Named subsets of relations, so a list loads less than a detail page without a second resource:

import { 
engine
} from "./engine";
engine
.
defineResource
("orders", {
relations
: {
customer
: true,
orderLines
: {
with
: {
product
: true } },
},
hydration
: {
profiles
: {
list
: {
customer
: true },
detail
: {
customer
: true,
orderLines
: {
with
: {
product
: true } },
},
root
: {},
},
defaults
: {
query
: "list",
findById
: "detail",
}, }, });

query() and queryRows() use the query default, findById() the findById default. Without a default, the full relations tree is loaded. A call can choose a profile, or pass its own subset, with load:

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 },
});

load replaces the default exactly; profiles are never merged. It is a server-side choice and is not part of the client request.

query

query.scope

Filters added to every request on the server, typically the tenant:

const 
query
= {
scope
: (
f
:
ExampleFilterBuilder
,
ctx
: {
orgId
: string }) =>
f
.
and
([
f
.
is
("customer.orgId",
ctx
.
orgId
)]),
};

See Scope.

query.search

The fields a search may match, and the ones used when the request lists none:

const 
query
= {
search
: {
allowed
: ["reference", "customer.name", "orderLines.product.name"],
defaults
: ["reference", "customer.name"],
}, } satisfies {
search
:
ExampleSearchConfig
};

See Search.

query.sort

The default order, and keys clients may not sort by:

const 
query
= {
sort
: {
defaults
: [{
key
: "createdAt",
dir
: "desc" }],
disabled
: ["orderLines.product.name"],
}, } satisfies {
sort
:
ExampleSortConfig
};

See Sorting.

query.filters

Fields clients may not filter on:

const 
query
= {
filters
: {
hidden
: [],
disabled
: [],
}, } satisfies {
filters
:
ExampleFiltersConfig
};

hidden removes a field from client requests while the scope can still use it. disabled removes it for everyone, the scope included. See Field rules.

query.facets

Fields clients may request bucket counts for:

const 
query
= {
facets
: {
allowed
: ["status", "customer.name", "orderLines.product.category.label"],
}, } satisfies {
facets
:
ExampleFacetsConfig
};

A facet key outside allowed is rejected. See Facets.

query.pagination and query.defaults

pagination.modes lists the modes clients may use ("offset", "cursor"). defaults.pagination fills in what the request leaves out:

const 
query
= {
defaults
: {
pagination
: {
pageSize
: 25 },
}, } satisfies {
defaults
:
ExampleDefaultsConfig
};

See Pagination.

strategy

Your own implementation of one step, when the generated SQL isn't the plan you want. Measure first; see Strategies.

Copyright © 2026