CLOUD-4245 improve-redis-search-docs by up-ilter · Pull Request #651 · upstash/docs

up-ilter · 2026-03-16T20:24:09Z

No description provided.

linear · 2026-03-16T20:24:13Z

Copilot

Pull request overview

Adds and expands Upstash Redis Search documentation to make common usage patterns and failure modes easier to understand, with new reference-style pages and clearer response/parameter explanations.

Changes:

Added new Command Reference and Troubleshooting pages for Redis Search.
Expanded existing docs with response-format sections (query + aggregations) and added schema FAST/field-type reference material.
Updated navigation to include the new pages.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
redis/search/troubleshooting.mdx	New troubleshooting guide covering common index/query/aggregation/schema errors.
redis/search/command-reference.mdx	New command reference for `SEARCH.*` commands, parameters, and return formats.
redis/search/schema-definition.mdx	Adds field type reference table and FAST field explanation.
redis/search/querying.mdx	Documents query response format and adds LIMIT/OFFSET parameter table.
redis/search/query-operators/field-operators/overview.mdx	Adds quick-reference table for field operators.
redis/search/aggregations.mdx	Documents aggregation response format and adds FAST-field note.
redis/search/aggregation-operators/metric-aggregations/overview.mdx	Clarifies metric operator input format and common error messages.
redis/search/aggregation-operators/bucket-aggregations/overview.mdx	Clarifies bucket operator input format and nested `$aggs` behavior.
redis/search/index-management.mdx	Clarifies what `SEARCH.WAITINDEXING` waits for and when to use it.
redis/search/counting.mdx	Clarifies that `SEARCH.COUNT` returns a single integer.
docs.json	Adds the new Search docs pages to the sidebar/navigation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

redis/search/troubleshooting.mdx

+The `LIMIT` value must be between 1 and 1000.
+
+**Common causes:**
+- Using `LIMIT 0` — the minimum is 1
+- Using `LIMIT` greater than 1000


redis/search/command-reference.mdx

+- **Metric operators** (`$avg`, `$sum`, etc.) — a single number or stats object
+- **Bucket operators** (`$terms`, `$range`, etc.) — an array of bucket objects


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

up-ilter

Nitpick Review

Summary

Comprehensive documentation enhancement for Redis Search that adds two new guide pages (Command Reference and Troubleshooting) and enriches existing guides with request/response format examples, reference tables, and practical code samples across TypeScript, Python, and Redis CLI.

Key changes:

Added new Command Reference page documenting all SEARCH.* commands (SEARCH.CREATE, SEARCH.QUERY, SEARCH.AGGREGATE, SEARCH.COUNT, alias commands, etc.) with syntax, parameters, and examples
Added new Troubleshooting page covering common errors and fixes (index creation, query syntax, aggregation field requirements, schema issues, Upstash vs RediSearch differences)
Enhanced aggregation documentation with Response Format section showing result structures for TypeScript, Python, and Redis CLI with practical examples
Added Input Format sections to bucket and metric aggregation overviews with JSON examples for each operator type
Created Field Type Reference table documenting all field types (TEXT, KEYWORD, F64, DATE, BOOL, FACET) with FAST support and supported operators
Enhanced query documentation with Response Format examples and LIMIT/OFFSET parameter reference table
Added Field Operators Quick Reference table and expanded SEARCH.WAITINDEXING documentation with guidance on optimal usage patterns

Verdict

Metric	Value
Risk Score	35/100
Recommendation	request changes
Findings	13 accepted

Found 13 issue(s) across all reviewers. 5 blocking issue(s) require attention before merge. Overall risk score: 35/100. Changes are requested before merging.

Blockers

🟠 HIGH Bearer Token detected in added code (redis/search/command-reference.mdx:39)
🟠 HIGH Bearer Token detected in added code (redis/search/command-reference.mdx:144)
🟠 HIGH Bearer Token detected in added code (redis/search/command-reference.mdx:171)
🟠 HIGH Bearer Token detected in added code (redis/search/command-reference.mdx:208)
🟠 HIGH Bearer Token detected in added code (redis/search/command-reference.mdx:261)

Suggested Commits

fix: bearer token detected in added code
fix: bearer token detected in added code
fix: bearer token detected in added code
fix: bearer token detected in added code
fix: bearer token detected in added code

Generated by Nitpick

up-ilter · 2026-03-17T08:05:48Z

redis/search/command-reference.mdx

+<Tab title="curl">
+```bash
+curl -X POST https://YOUR_ENDPOINT.upstash.io \
+  -H "Authorization: Bearer YOUR_TOKEN" \


🟠 HIGH — Bearer Token detected in added code

A potential Bearer Token was found in a newly added line. Secrets should never be committed to source control.

Recommendation: Remove the bearer token from source code. Use environment variables or a secrets manager instead. Rotate the exposed credential immediately.

[secrets] confidence: 85%

up-ilter · 2026-03-17T08:05:48Z

redis/search/command-reference.mdx

+<Tab title="curl">
+```bash
+curl -X POST https://YOUR_ENDPOINT.upstash.io \
+  -H "Authorization: Bearer YOUR_TOKEN" \


🟠 HIGH — Bearer Token detected in added code

A potential Bearer Token was found in a newly added line. Secrets should never be committed to source control.

Recommendation: Remove the bearer token from source code. Use environment variables or a secrets manager instead. Rotate the exposed credential immediately.

[secrets] confidence: 85%

up-ilter · 2026-03-17T08:05:48Z

redis/search/command-reference.mdx

+<Tab title="curl">
+```bash
+curl -X POST https://YOUR_ENDPOINT.upstash.io \
+  -H "Authorization: Bearer YOUR_TOKEN" \


🟠 HIGH — Bearer Token detected in added code

A potential Bearer Token was found in a newly added line. Secrets should never be committed to source control.

Recommendation: Remove the bearer token from source code. Use environment variables or a secrets manager instead. Rotate the exposed credential immediately.

[secrets] confidence: 85%

up-ilter · 2026-03-17T08:05:49Z

redis/search/command-reference.mdx

+<Tab title="curl">
+```bash
+curl -X POST https://YOUR_ENDPOINT.upstash.io \
+  -H "Authorization: Bearer YOUR_TOKEN" \


🟠 HIGH — Bearer Token detected in added code

A potential Bearer Token was found in a newly added line. Secrets should never be committed to source control.

Recommendation: Remove the bearer token from source code. Use environment variables or a secrets manager instead. Rotate the exposed credential immediately.

[secrets] confidence: 85%

up-ilter · 2026-03-17T08:05:49Z

redis/search/command-reference.mdx

+
+```bash
+curl -X POST https://YOUR_ENDPOINT.upstash.io \
+  -H "Authorization: Bearer YOUR_TOKEN" \


🟠 HIGH — Bearer Token detected in added code

A potential Bearer Token was found in a newly added line. Secrets should never be committed to source control.

Recommendation: Remove the bearer token from source code. Use environment variables or a secrets manager instead. Rotate the exposed credential immediately.

[secrets] confidence: 85%

up-ilter · 2026-03-17T08:05:49Z

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

+```json
+{"by_category": {"$terms": {"field": "category", "size": 10}}}
+{"price_ranges": {"$range": {"field": "price", "ranges": [{"to": 50}, {"from": 50, "to": 100}, {"from": 100}]}}}
+{"by_month": {"$histogram": {"field": "price", "interval": 10}}}


🔵 LOW — Bucket aggregation 'Input Format' example uses misleading alias for $histogram

The alias by_month is used for a $histogram example that groups by price with interval: 10. The alias suggests monthly grouping, but the actual aggregation is a numeric histogram over price in increments of 10. This is misleading to readers learning the API.

Recommendation: Change the alias to something that reflects the actual field, e.g. "price_buckets" or "by_price", so the example is self-consistent.

[dx] confidence: 92%

up-ilter · 2026-03-17T08:05:49Z

redis/search/aggregations.mdx

+#     {"key": "electronics", "doc_count": 42},
+#     {"key": "clothing", "doc_count": 31},
+#   ]
+# }


🔵 LOW — Inconsistent response key casing between TypeScript and Python examples

In the aggregations response format, the TypeScript example uses docCount (camelCase) while the Python example uses doc_count (snake_case) for bucket results. If both SDKs return the same wire format, one of these is wrong. If they differ by design (SDK-specific casing), this should be called out explicitly to avoid confusion.

Recommendation: Add a brief note clarifying that each SDK normalizes response keys to its language's conventions (camelCase for TS, snake_case for Python), or verify the actual SDK behavior and correct whichever is wrong.

[dx] confidence: 72%

up-ilter · 2026-03-17T08:05:49Z

redis/search/querying.mdx

+
+<Tab title="TypeScript">
+```ts
+const results = await index.query({


🔵 LOW — SEARCH.QUERY response format described in two places with different detail levels

The raw Redis CLI response format for SEARCH.QUERY is documented both in querying.mdx (new 'Response Format' section) and in command-reference.mdx (under SEARCH.QUERY). The two descriptions are consistent but at different detail levels — command-reference.mdx explains key, score, content tuple structure, while querying.mdx shows it only in a comment. If either is updated in the future, they could drift apart.

Recommendation: In querying.mdx, add a brief cross-reference like 'For a detailed breakdown of the response structure, see Command Reference.' to establish a single source of truth.

[dx] confidence: 70%

up-ilter · 2026-03-17T08:05:49Z

redis/search/aggregations.mdx

@@ -47,6 +47,68 @@ Aggregation requests have two phases:



⚪ INFO — Response field naming differs between SDK examples without explicit explanation

In aggregations.mdx, the TypeScript response example uses docCount (camelCase) while the Python example uses doc_count (snake_case) for the same bucket aggregation field. While this is likely intentional SDK-level normalization to match each language's conventions, no note explains that the wire format is transformed differently per SDK, which could confuse users working across languages.

Recommendation: Consider adding a brief note (e.g., in a <Note> block) mentioning that each SDK normalizes response keys to match language conventions (camelCase for TypeScript, snake_case for Python), and that the Redis CLI returns the raw wire format.

[architecture] confidence: 65%

up-ilter · 2026-03-17T08:05:49Z

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

+
+Every bucket operator takes an object with a `field` property and operator-specific parameters:
+
+```json


⚪ INFO — Bucket aggregation 'Input Format' block is not valid JSON (multiple root objects)

The Input Format example in the bucket aggregations overview shows four separate JSON objects on consecutive lines inside a single ```json block. This is not valid JSON (a JSON document must have a single root value). While each line is individually valid, the block as a whole could confuse readers or tools.

Recommendation: Either separate each example into its own code block, or use JSONL / plain text syntax highlighting, or wrap them in an array. A common pattern is to show each operator as a separate mini-example with a label.

[dx] confidence: 75%

CLOUD-4245 improve-redis-search-docs

43d8e85

mintlify bot deployed to staging March 16, 2026 20:26 View deployment

up-ilter requested a review from Copilot March 16, 2026 20:26

Copilot started reviewing on behalf of up-ilter March 16, 2026 20:27 View session

Copilot AI reviewed Mar 16, 2026

View reviewed changes

buggyhunter requested a review from mdumandag March 16, 2026 21:37

Potential fix for pull request finding

45c531b

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

mintlify bot deployed to staging March 17, 2026 07:56 View deployment

up-ilter commented Mar 17, 2026

View reviewed changes

CLOUD-4245 improve-redis-search-docs

9033424

mintlify bot deployed to staging March 17, 2026 08:14 View deployment

CLOUD-4245 improve-redis-search-docs

eddc802

mintlify bot deployed to staging March 17, 2026 09:34 View deployment

		- Metric operators (`$avg`, `$sum`, etc.) — a single number or stats object
		- Bucket operators (`$terms`, `$range`, etc.) — an array of bucket objects


		Every bucket operator takes an object with a `field` property and operator-specific parameters:

		```json

Conversation

up-ilter commented Mar 16, 2026

Uh oh!

linear bot commented Mar 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

up-ilter left a comment

Choose a reason for hiding this comment

Nitpick Review

Summary

Verdict

Blockers

Suggested Commits

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants