Field rules
Every field path of a resource can be used in four ways by a client request. Each one has its own setting in query, checked before any SQL runs.
| Use | Setting | Without the setting | When a request breaks the rule |
|---|---|---|---|
| Search | search.allowed, search.defaults | every field is allowed | Unknown search field "…" |
| Sort | sort.disabled | every field is allowed | Sorting field "…" is not allowed |
| Filter | filters.hidden, filters.disabled | every field is allowed | Unknown filter field "…" |
| Facet | facets.allowed | every field is allowed | Unknown facet field "…" |
Everything is open by default. Set these explicitly in production, especially search.allowed and facets.allowed, which also control cost.
These rules are about client requests. Fields that must never be returned or queried are declared once on the engine as private.
Search
const query = {
search: {
allowed: ["reference", "customer.name", "orderLines.product.name"],
defaults: ["reference", "customer.name"],
},
} satisfies { search: ExampleSearchConfig };
Without allowed, every field path is searchable. Keep defaults short: each default field adds one condition to every search.
Sort
const query = {
sort: {
defaults: [{ key: "createdAt", dir: "desc" }],
disabled: ["orderLines.product.name"],
},
} satisfies { sort: ExampleSortConfig };
Disable sorting on many-to-many paths: without an aggregate the order is ambiguous, and the join is expensive. A request that sorts on a disabled key is rejected.
Filter
const query = {
filters: {
hidden: ["internalCostPrice", "marginPercent", "internalNotes"],
disabled: ["deletedAt"],
},
} satisfies { filters: ExampleFiltersConfig };
| Setting | Clients | Scope and trusted server calls | Use it for |
|---|---|---|---|
hidden | can't filter, sort, search or facet on it | can use it | tenant keys and fields your server filters on |
disabled | can't use it | can't use it either | fields that must not be queried at all |
Both remove the field from client requests. The difference is the scope: a tenant key your scope relies on belongs in hidden.
Facet
const query = {
facets: {
allowed: ["status", "customer.name", "orderLines.product.category.label"],
},
} satisfies { facets: ExampleFacetsConfig };
Without allowed, every field can be requested as a facet. Each facet adds an aggregate query or joins a shared one, so only allow facets you have measured.
One field, four answers
The tenant key is a typical case: the scope uses it, clients can't touch it.
const query = {
filters: {
hidden: ["customer.orgId"],
},
search: {
allowed: ["reference", "customer.name"],
defaults: ["reference", "customer.name"],
},
facets: {
allowed: ["status", "customer.name"],
},
};
| Field | Search | Sort | Filter | Facet |
|---|---|---|---|---|
reference | yes | yes | yes | no |
customer.name | yes | yes | yes | yes |
status | no | yes | yes | yes |
customer.orgId | no | no | no | no |