CLOUD-4245 improve-redis-search-docs

docs.json

@@ -724,6 +724,8 @@
                   "redis/search/aggregations",
                   "redis/search/counting",
                   "redis/search/aliases",
+                  "redis/search/command-reference",
+                  "redis/search/troubleshooting",
                   {
                     "group": "Query Operators",
                     "pages": [

redis/search/aggregation-operators/bucket-aggregations/overview.mdx

@@ -16,8 +16,32 @@ Use bucket aggregations when you want segmented analytics (for example by catego
 | [`$dateHistogram`](./date-histogram) | Fixed date/time intervals |
 | [`$facet`](./facet) | Hierarchical FACET paths |
 
+### Input Format
+
+Every bucket operator takes an object with a `field` property and operator-specific parameters:
+
+**`$terms`** — group by distinct values:
+```json
+{"by_category": {"$terms": {"field": "category", "size": 10}}}
+```
+
+**`$range`** — custom range buckets:
+```json
+{"price_ranges": {"$range": {"field": "price", "ranges": [{"to": 50}, {"from": 50, "to": 100}, {"from": 100}]}}}
+```
+
+**`$histogram`** — fixed numeric intervals:
+```json
+{"price_buckets": {"$histogram": {"field": "price", "interval": 10}}}
+```
+
+**`$dateHistogram`** — fixed time intervals:
+```json
+{"by_month": {"$dateHistogram": {"field": "createdAt", "fixedInterval": "30d"}}}
+```
+
 ### Behavior Notes
 
-- Bucket operators can contain nested `$aggs`.
+- Bucket operators can contain nested `$aggs` for per-bucket metrics.
 - `$terms`, `$range`, `$histogram`, and `$dateHistogram` support nested `$aggs`.
 - `$facet` does not support nested `$aggs` and cannot be used as a sub-aggregation.

redis/search/aggregation-operators/metric-aggregations/overview.mdx

@@ -20,9 +20,21 @@ Use metrics when you want one value (or stats object), not grouped buckets.
 | [`$extendedStats`](./extended-stats) | `$stats` + variance and std deviation metrics |
 | [`$percentiles`](./percentiles) | Distribution percent points |
 
+### Input Format
+
+Every metric operator takes an object with at least a `field` property:
+
+```json
+{"alias_name": {"$avg": {"field": "price"}}}
+{"alias_name": {"$avg": {"field": "price", "missing": 0}}}
+```
+
+The `field` value must be a string pointing to a FAST field in your schema.
+Do **not** pass a bare string — it must be an object with `{"field": "..."}`.
+
 ### Behavior Notes
 
-- Metric operators require a `field`.
-- The field must be `FAST` in your schema.
+- Metric operators require a `field` — you will get `missing required 'field' property` if it's omitted.
+- The field must be `FAST` in your schema — otherwise you will get an error: `operator '$avg' requires field '<field>' to be FAST`. See [FAST Fields](/redis/search/schema-definition#fast-fields).
 - Metric operators do not support nested `$aggs`.
 - For many metric operators, `missing` lets you provide a fallback value for documents where the field does not exist.

redis/search/aggregations.mdx

@@ -47,6 +47,74 @@ Aggregation requests have two phases:
 
 Each aggregation is defined with an **alias** (the key you choose for the result) and an **operator** that specifies what to compute.
 
+### Response Format
+
+<Tabs>
+
+<Tab title="TypeScript">
+```ts
+const result = await index.aggregate({
+  aggregations: {
+    avg_price: { $avg: { field: "price" } },
+    by_category: { $terms: { field: "category", size: 5 } },
+  },
+});
+
+// result is an object keyed by alias:
+// {
+//   avg_price: 49.99,
+//   by_category: [
+//     { key: "electronics", docCount: 42 },
+//     { key: "clothing", docCount: 31 },
+//   ]
+// }
+```
+</Tab>
+
+<Tab title="Python">
+```python
+result = index.aggregate(
+    aggregations={
+        "avg_price": {"$avg": {"field": "price"}},
+        "by_category": {"$terms": {"field": "category", "size": 5}},
+    },
+)
+
+# result is a dict keyed by alias:
+# {
+#   "avg_price": 49.99,
+#   "by_category": [
+#     {"key": "electronics", "doc_count": 42},
+#     {"key": "clothing", "doc_count": 31},
+#   ]
+# }
+```
+</Tab>
+
+<Tab title="Redis CLI">
+```bash
+SEARCH.AGGREGATE products '{}' '{"avg_price": {"$avg": {"field": "price"}}, "by_category": {"$terms": {"field": "category", "size": 5}}}'
+
+# Response (`redis-cli --json`) is an object keyed by alias:
+# {"avg_price":{"value":49.99},"by_category":{"buckets":[{"key":"electronics","docCount":42},{"key":"clothing","docCount":31}]}}
+```
+</Tab>
+
+</Tabs>
+
+<Note>
+Each SDK normalizes response keys to match its language's conventions: camelCase for TypeScript
+(e.g., `docCount`) and snake_case for Python (e.g., `doc_count`). In `redis-cli --json`, Redis CLI
+returns a JSON object keyed by aggregation alias.
+</Note>
+
+<Note>
+All metric aggregation operators require the target field to be marked as `FAST` in your schema.
+If the field is not FAST, you will get an error like:
+`Aggregation '<name>' operator '$avg' requires field '<field>' to be FAST`.
+See [FAST Fields](/redis/search/schema-definition#fast-fields) for details.
+</Note>
+
 ## Filtering
 
 Use `filter` to restrict which documents participate in the aggregation.