upstash · mdumandag · Jan 12, 2026 · Jan 12, 2026 · Jan 13, 2026 · Jan 14, 2026
diff --git a/docs.json b/docs.json
@@ -698,6 +698,88 @@
                   "redis/help/managing-healthcare-data"
                 ]
               },
+              {
+                "group": "Search",
+                "pages": [
+                  "redis/search/introduction",
+                  "redis/search/getting-started",
+                  "redis/search/index-management",
+                  "redis/search/schema-definition",
+                  "redis/search/querying",
+                  "redis/search/aggregations",
+                  "redis/search/counting",
+                  "redis/search/aliases",
+                  {
+                    "group": "Query Operators",
+                    "pages": [
+                      {
+                        "group": "Boolean Operators",
+                        "pages": [
+                          "redis/search/query-operators/boolean-operators/overview",
+                          "redis/search/query-operators/boolean-operators/must",
+                          "redis/search/query-operators/boolean-operators/should",
+                          "redis/search/query-operators/boolean-operators/must-not",
+                          "redis/search/query-operators/boolean-operators/boost"
+                        ]
+                      },
+                      {
+                        "group": "Field Operators",
+                        "pages": [
+                          "redis/search/query-operators/field-operators/overview",
+                          "redis/search/query-operators/field-operators/smart-matching",
+                          "redis/search/query-operators/field-operators/eq",
+                          "redis/search/query-operators/field-operators/in",
+                          "redis/search/query-operators/field-operators/range-operators",
+                          "redis/search/query-operators/field-operators/phrase",
+                          "redis/search/query-operators/field-operators/fuzzy",
+                          "redis/search/query-operators/field-operators/regex",
+                          "redis/search/query-operators/field-operators/boost"
+                        ]
+                      }
+                    ]
+                  },
+                  {
+                    "group": "Aggregation Operators",
+                    "pages": [
+                      {
+                        "group": "Metric Aggregations",
+                        "pages": [
+                          "redis/search/aggregation-operators/metric-aggregations/overview",
+                          "redis/search/aggregation-operators/metric-aggregations/avg",
+                          "redis/search/aggregation-operators/metric-aggregations/sum",
+                          "redis/search/aggregation-operators/metric-aggregations/min",
+                          "redis/search/aggregation-operators/metric-aggregations/max",
+                          "redis/search/aggregation-operators/metric-aggregations/count",
+                          "redis/search/aggregation-operators/metric-aggregations/cardinality",
+                          "redis/search/aggregation-operators/metric-aggregations/stats",
+                          "redis/search/aggregation-operators/metric-aggregations/extended-stats",
+                          "redis/search/aggregation-operators/metric-aggregations/percentiles"
+                        ]
+                      },
+                      {
+                        "group": "Bucket Aggregations",
+                        "pages": [
+                          "redis/search/aggregation-operators/bucket-aggregations/overview",
+                          "redis/search/aggregation-operators/bucket-aggregations/terms",
+                          "redis/search/aggregation-operators/bucket-aggregations/range",
+                          "redis/search/aggregation-operators/bucket-aggregations/histogram",
+                          "redis/search/aggregation-operators/bucket-aggregations/date-histogram",
+                          "redis/search/aggregation-operators/bucket-aggregations/facet"
+                        ]
+                      }
+                    ]
+                  },
+                  {
+                    "group": "Recipes",
+                    "pages": [
+                      "redis/search/recipes/overview",
+                      "redis/search/recipes/e-commerce-search",
+                      "redis/search/recipes/blog-search",
+                      "redis/search/recipes/user-directory"
+                    ]
+                  }
+                ]
+              },
               {
                 "group": "How To",
                 "pages": [

diff --git a/img/redis-search/redis-search-cover.png b/img/redis-search/redis-search-cover.png
diff --git a/redis/search/aggregation-operators/bucket-aggregations/date-histogram.mdx b/redis/search/aggregation-operators/bucket-aggregations/date-histogram.mdx
@@ -0,0 +1,87 @@
+---
+title: $dateHistogram
+---
+
+`$dateHistogram` groups date values into fixed time buckets.
+
+Use it for time-series analytics like events per hour/day.
+
+### Compatibility
+
+| Field Type | Supported |
+|------------|-----------|
+| TEXT | No |
+| U64/I64/F64 | No |
+| DATE | Yes |
+| BOOL | No |
+| KEYWORD | No |
+| FACET | No |
+
+Field must be `FAST`.
+
+### Arguments
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `field` | `string` | Yes | Date field to bucket on. |
+| `fixedInterval` | `string` | Yes | Interval string such as `"1m"`, `"1h"`, `"1d"`. |
+| `offset` | `string` | No | Shift bucket boundaries. |
+| `minDocCount` | `number` | No | Exclude buckets with fewer docs. |
+| `hardBounds` | `{ min: number, max: number }` | No | Hard clamp for bucket range. |
+| `extendedBounds` | `{ min: number, max: number }` | No | Emit buckets across this range, including empty ones. |
+| `keyed` | `boolean` | No | If `true`, returns buckets as an object. Default: `false`. |
+
+For `hardBounds` and `extendedBounds`, both `min` and `max` are required.
+
+<Tabs>
+
+<Tab title="TypeScript">
+```ts
+await index.aggregate({
+  aggregations: {
+    by_day: {
+      $dateHistogram: {
+        field: "createdAt",
+        fixedInterval: "1d",
+      },
+    },
+  },
+});
+```
+</Tab>
+
+<Tab title="Python">
+```python
+index.aggregate(
+    aggregations={
+        "by_day": {
+            "$dateHistogram": {
+                "field": "createdAt",
+                "fixedInterval": "1d",
+            }
+        }
+    }
+)
+```
+</Tab>
+
+<Tab title="Redis CLI">
+```bash
+SEARCH.AGGREGATE logs '{}' '{"by_day": {"$dateHistogram": {"field": "createdAt", "fixedInterval": "1d"}}}'
+```
+</Tab>
+
+</Tabs>
+
+### Output
+
+```json
+{
+  "by_day": {
+    "buckets": [
+      { "key": 1704067200000, "keyAsString": "2024-01-01T00:00:00Z", "docCount": 14 },
+      { "key": 1704153600000, "keyAsString": "2024-01-02T00:00:00Z", "docCount": 9 }
+    ]
+  }
+}
+```
diff --git a/redis/search/aggregation-operators/bucket-aggregations/facet.mdx b/redis/search/aggregation-operators/bucket-aggregations/facet.mdx
@@ -0,0 +1,170 @@
+---
+title: $facet
+---
+
+`$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" }`. |
+
+<Tabs>
+
+<Tab title="TypeScript">
+```ts
+await index.aggregate({
+  aggregations: {
+    by_category: {
+      $facet: {
+        field: "category",
+        path: "/category",
+      },
+    },
+  },
+});
+```
+</Tab>
+
+<Tab title="Python">
+```python
+index.aggregate(
+    aggregations={
+        "by_category": {
+            "$facet": {
+                "field": "category",
+                "path": "/category",
+            }
+        }
+    }
+)
+```
+</Tab>
+
+<Tab title="Redis CLI">
+```bash
+SEARCH.AGGREGATE products '{}' '{"by_category": {"$facet": {"field": "category", "path": "/category"}}}'
+```
+</Tab>
+
+</Tabs>
+
+### Output
+
+```json
+{
+  "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.
+
+<Tabs>
+
+<Tab title="TypeScript">
+```ts
+await index.aggregate({
+  aggregations: {
+    category_tree: {
+      $facet: {
+        field: "category",
+        path: "/category",
+        depth: 2,
+        size: 10,
+        minDocCount: 1,
+        order: { count: "desc" },
+      },
+    },
+  },
+});
+```
+</Tab>
+
+<Tab title="Python">
+```python
+index.aggregate(
+    aggregations={
+        "category_tree": {
+            "$facet": {
+                "field": "category",
+                "path": "/category",
+                "depth": 2,
+                "size": 10,
+                "minDocCount": 1,
+                "order": {"count": "desc"},
+            }
+        }
+    }
+)
+```
+</Tab>
+
+<Tab title="Redis CLI">
+```bash
+SEARCH.AGGREGATE products '{}' '{"category_tree": {"$facet": {"field": "category", "path": "/category", "depth": 2, "size": 10, "minDocCount": 1, "order": {"count": "desc"}}}}'
+```
+</Tab>
+
+</Tabs>
+
+With `depth: 2`, the response includes nested children:
+
+```json
+{
+  "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.