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.

Sorting on a disabled key real engine · 10,000 sample orders in your browser
requestplayground →
{
  "sorting": [
    {
      "key": "orderLines.product.name",
      "dir": "asc"
    }
  ]
}
Runs when scrolled into view.

What relation sorting costs

Sort keyJoinCost
createdAt (root column)noneIndex the column.
customer.name (many-to-one)one joinUsually fine with indexes on the join and sort columns.
orderLines.product.category (to-many)lines and productsSeveral 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.

Copyright © 2026