Documentation Index
Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
$facet builds a hierarchical bucket tree from FACET field paths.
Use it for category navigation and drill-down style faceting.
Compatibility
| Field Type | Supported |
|---|
| TEXT | No |
| U64/I64/F64 | No |
| DATE | No |
| BOOL | No |
| KEYWORD | No |
| FACET | Yes |
Arguments
| Argument | Type | Required | Description |
|---|
field | string | Yes | FACET field name. |
path | string | Yes | Root path to expand. Must start with /. |
depth | number | No | Levels to traverse (>= 1). Default: 1. |
size | number | No | Max children per level. Default: 10. |
minDocCount | number | No | Minimum docs required for a child bucket. Default: 1. |
order | object | No | One-key order object: { "count": "asc|desc" } or { "path": "asc|desc" }. Default: { "count": "desc" }. |
TypeScript
Python
Redis CLI
await index.aggregate({
aggregations: {
by_category: {
$facet: {
field: "category",
path: "/category",
},
},
},
});
index.aggregate(
aggregations={
"by_category": {
"$facet": {
"field": "category",
"path": "/category",
}
}
}
)
SEARCH.AGGREGATE products '{}' '{"by_category": {"$facet": {"field": "category", "path": "/category"}}}'
Output
{
"by_category": {
"path": "/category",
"sumOtherDocCount": 0,
"children": [
{ "path": "/category/books", "docCount": 12, "sumOtherDocCount": 0 },
{ "path": "/category/electronics", "docCount": 9, "sumOtherDocCount": 0 }
]
}
}
- Increase
depth for multi-level facet trees.
- Use
size and minDocCount to control noise and response size.
- Use
order to sort by count or by path.
TypeScript
Python
Redis CLI
await index.aggregate({
aggregations: {
category_tree: {
$facet: {
field: "category",
path: "/category",
depth: 2,
size: 10,
minDocCount: 1,
order: { count: "desc" },
},
},
},
});
index.aggregate(
aggregations={
"category_tree": {
"$facet": {
"field": "category",
"path": "/category",
"depth": 2,
"size": 10,
"minDocCount": 1,
"order": {"count": "desc"},
}
}
}
)
SEARCH.AGGREGATE products '{}' '{"category_tree": {"$facet": {"field": "category", "path": "/category", "depth": 2, "size": 10, "minDocCount": 1, "order": {"count": "desc"}}}}'
depth: 2, the response includes nested children:
{
"by_cat": {
"path": "/category",
"sumOtherDocCount": 0,
"children": [
{
"docCount": 2,
"path": "/category/books",
"sumOtherDocCount": 0,
"children": [
{ "docCount": 1, "path": "/category/books/fiction", "sumOtherDocCount": 0 },
{ "docCount": 1, "path": "/category/books/nonfiction", "sumOtherDocCount": 0 }
]
},
{
"docCount": 2,
"path": "/category/electronics",
"sumOtherDocCount": 0,
"children": [
{ "docCount": 1, "path": "/category/electronics/laptops", "sumOtherDocCount": 0 },
{ "docCount": 1, "path": "/category/electronics/phones", "sumOtherDocCount": 0 }
]
}
]
}
}
$facet cannot contain $aggs.$facet cannot be used as a sub-aggregation inside another $aggs block.
