Strategies
A strategy replaces one step of a request with your code. The request and response shapes stay the same, and the other steps keep running as usual.
| Strategy | Built-in behaviour | Replace it when |
|---|---|---|
ids | One SQL query for the page's ids, and the count if asked | You need a different join shape or a hand-tuned query. |
rows | Drizzle relational query for those ids, in page order | Rows come from another source or need another shape. |
facets | Grouped aggregates, shared on PostgreSQL when possible | Counts come from pre-aggregated data. |
query | The whole pipeline | The staged model doesn't fit the endpoint at all. |
Start with none. Replace ids first when measurements show it is slow: it is where most of the time goes. Summaries need the built-in ids and query steps.
strategy.ids
const strategy = {
ids: async ({ request, context, utils }: any) => {
const { pagination, sorting, filters, search } = request;
const where = utils.buildWhereClause({ filters, search });
return {
ids: [],
pageInfo: offsetPageInfo,
};
},
};
request is already normalized: the scope is merged, defaults are applied and every key is validated. utils.buildWhereClause compiles its filters and search to a Drizzle condition.
strategy.rows
const strategy = {
rows: async ({ ids, relations, utils }: any) => utils.executeRowsQuery({ ids, relations }),
};
ids is in page order and relations is the load profile for this call. Return rows in the same order as ids, or use utils.executeRowsQuery, which loads, deduplicates and restores the order.
strategy.facets
const strategy = {
facets: async ({ request, facets, context, utils }: any) =>
utils.resolveFacets({ request, facets }),
};
strategy.query
Replaces the whole pipeline. Use it only when the endpoint doesn't fit the ids, rows and facets steps:
const strategy = {
query: async ({ request, context, relations, utils }: any) => ({
rows: [],
pageInfo: offsetPageInfo,
}),
};
Helpers
Every strategy receives utils, built from the resource's field paths, filter compiler and Drizzle setup:
| Helper | Does |
|---|---|
utils.buildWhereClause({ filters, search }) | Compiles a Drizzle where condition. |
utils.compileOrderBy(sorting) | Compiles a Drizzle orderBy list. |
utils.executeIdsQuery(options) | Runs the built-in page-ids query and the count if asked. |
utils.executeRowsQuery({ ids, relations }) | Loads rows by id in page order. |
utils.resolveFacets({ request, facets }) | Runs the built-in facet aggregation. |
utils.resolveField(path) | Returns the Drizzle column for a field path. |
Using them keeps your step consistent with the rest of the engine. See the strategy utils reference and Performance for when a custom step is worth it.