Queries

Facets

Bucket counts for filter sidebars, computed in the same request as the page.

A facet counts the matching rows per value of one field: "612 shipped, 231 pending". Facets are requested with the page and use the same scope, filters and search.

  
facets
: [
{
key
: "status",
mode
: "exclude-self",
limit
: 10 },
{
key
: "customer.name",
mode
: "include-self",
limit
: 20 },
], };
FieldMeaning
keyA field path in the resource's facets.allowed.
modeWhether this facet's own filter applies to its counts (below).
limitThe number of buckets to return, largest first.

Leave facets out and no facet query runs.

exclude-self and include-self

The example below filters on status: shipped and asks for the status facet with exclude-self: it still lists every status, so the sidebar keeps showing the other options. Change mode to include-self and only shipped remains.

A status filter with an exclude-self status facet real engine · 10,000 sample orders in your browser
requestplayground →
{
  "filters": [
    {
      "type": "condition",
      "key": "status",
      "operator": "is",
      "value": "shipped"
    }
  ],
  "facets": [
    {
      "key": "status",
      "mode": "exclude-self",
      "limit": 10
    },
    {
      "key": "orderLines.product.category",
      "mode": "exclude-self",
      "limit": 10
    }
  ]
}
Runs when scrolled into view.
ModeThis facet's own filterUse it for
exclude-selfignoredFilter sidebars: users can still see and add other values.
include-selfappliedDrill-down: show only what remains after the filter.

exclude-self only removes the client's filter on that field. The scope always applies.

The response

result
.
facets
= [
{
key
: "status",
options
: [
{
value
: "pending",
count
: 12 },
{
value
: "processing",
count
: 4 },
{
value
: "shipped",
count
: 31 },
],
total
: 3,
}, ];

total is the number of distinct values in the filtered result, whatever the limit, so the interface can show "10 of 47".

The SQL

Each facet groups the filtered rows by its field:

SELECT field_value, count(*) AS count
FROM root_table
[joins for the relation path]
WHERE [scope + client filters, minus this facet's own filter in exclude-self mode]
GROUP BY field_value
ORDER BY count DESC
LIMIT :limit

On PostgreSQL, facets with the same filters and joins share one GROUPING SETS statement.

Facet fieldCost
Root column (status)No join. The cheapest.
Many-to-one (customer.name)One join. Fast with an index on the join column.
Through to-many (orderLines.product.category)Junction joins and count(distinct). Measure before allowing it.

Allowed facets

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

A facet key outside allowed is rejected with Unknown facet field "…". Without allowed, every field path can be requested, so set it.

Facets without the page

When a sidebar refreshes separately from the list, queryFacets computes facets without loading the page:

const 
facets
= await
ordersResource
.
queryFacets
({
context
: {
orgId
: "acme" },
request
,
facets
: [{
key
: "status",
mode
: "exclude-self",
limit
: 10 }],
});
Copyright © 2026