Facets
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 },
],
};
| Field | Meaning |
|---|---|
key | A field path in the resource's facets.allowed. |
mode | Whether this facet's own filter applies to its counts (below). |
limit | The 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.
| Mode | This facet's own filter | Use it for |
|---|---|---|
exclude-self | ignored | Filter sidebars: users can still see and add other values. |
include-self | applied | Drill-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 field | Cost |
|---|---|
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 }],
});