Queries
Sorting
Sort by several fields, set a default order, and turn off keys that are expensive or ambiguous.
sorting is a list of keys and directions, applied in order:
sorting: [
{ key: "createdAt", dir: "desc" },
{ key: "reference", dir: "asc" },
],
};
Rows are sorted by createdAt descending, then by reference for rows with the same date. Any path reachable through the resource's relations is a valid key, unless the resource disables it.
Default order
sort: {
defaults: [{ key: "createdAt", dir: "desc" }],
},
} satisfies { sort: ExampleSortConfig };
Defaults apply only when sorting is empty. When the client sends any key, its list is used as it is; defaults are not appended.
Disabled keys
sort: {
disabled: ["orderLines.product.name"],
},
} satisfies { sort: ExampleSortConfig };
A request that sorts on a disabled key is rejected with Sorting field "…" is not allowed. The sample resource below disables orderLines.product.name: edit the key to customer.name to see it work.
What relation sorting costs
| Sort key | Join | Cost |
|---|---|---|
createdAt (root column) | none | Index the column. |
customer.name (many-to-one) | one join | Usually fine with indexes on the join and sort columns. |
orderLines.product.category (to-many) | lines and products | Several values per order: the order is ambiguous and the join inflates the rows. Disable it, or write a custom ids step. |
With cursor pagination, the root id is appended to the sort so that rows with equal keys keep a stable order. See Pagination.