Command Reference

A complete reference of all Upstash Redis Search commands, their syntax, and return values.

Upstash Redis Search uses SEARCH.* commands. These are not the same as the FT.* commands from the open-source RediSearch module. The two are completely separate implementations and are not compatible with each other.

Index Commands

SEARCH.CREATE

Creates a new search index.

SEARCH.CREATE <name> ON <JSON|HASH|STRING>
  PREFIX <count> <prefix> [<prefix> ...]
  [LANGUAGE <language>]
  [SKIPINITIALSCAN]
  [EXISTSOK]
  SCHEMA <field> <type> [FAST] [NOSTEM] [NOTOKENIZE] [FROM <source_field>] ...

Returns: 1 on success. With EXISTSOK, returns 0 if an identical index already exists. Returns an error if the existing index has a different configuration.

Redis CLI

SEARCH.CREATE products ON JSON PREFIX 1 product: SCHEMA name TEXT price F64 FAST inStock BOOL

curl

curl -X POST https://YOUR_ENDPOINT.upstash.io \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
  -d '["SEARCH.CREATE", "products", "ON", "JSON", "PREFIX", "1", "product:", "SCHEMA", "name", "TEXT", "price", "F64", "FAST", "inStock", "BOOL"]'

---

SEARCH.DROP

Removes an index. The underlying Redis keys are not deleted.

SEARCH.DROP <name>

Returns: 1 if dropped, 0 if the index was not found.

---

SEARCH.DESCRIBE

Returns metadata about an index.

SEARCH.DESCRIBE <name>

Returns: Index metadata including name, data type, prefixes, language, and schema definition. Returns null if the index does not exist.

---

SEARCH.WAITINDEXING

Blocks until all pending index updates are processed and visible to queries.

SEARCH.WAITINDEXING <name>

Returns: 1 when indexing is complete, 0 if the index was not found.

Do not call SEARCH.WAITINDEXING after every write. Batch updates are necessary for optimal indexing performance. Use this command only when you need to ensure queries reflect recent changes, such as in tests or CI pipelines.

---

Query Commands

SEARCH.QUERY

Searches for documents matching a JSON filter.

SEARCH.QUERY <name> '<json_filter>'
  [LIMIT <count>]
  [OFFSET <offset>]
  [ORDERBY <field> <ASC|DESC>]
  [SELECT <count> <field> [<field> ...]]
  [NOCONTENT]
  [HIGHLIGHT FIELDS <count> <field> [<field> ...] [TAGS <open> <close>]]
  [SCOREFUNC ...]

Parameters:

Parameter	Description	Default
LIMIT	Maximum number of results to return. Must be between 1 and 1000.	10
OFFSET	Number of results to skip (for pagination).	0
ORDERBY	Sort by a FAST field in ASC or DESC order.	Sort by relevance score (descending)
SELECT	Return only specific fields. Prefix with count of fields.	All fields
NOCONTENT	Return only keys and scores, no document content.	Disabled
HIGHLIGHT	Wrap matching terms in tags. Default tags: <em> / </em>.	Disabled
SCOREFUNC	Adjust relevance scores using numeric field values.	Disabled

Response format (Redis CLI):

[
  ["key1", "score1", [["$", "{\"name\": \"...\", ...}"]]],
  ["key2", "score2", [["$", "{\"name\": \"...\", ...}"]]]
]

Each result is an array of [key, score, content] where:

• key — the Redis key of the matching document
• score — relevance score (float)
• content — array of field-value pairs (for JSON indexes: [["$", "<json_string>"]]; for HASH indexes: [["field", "value"], ...])

When NOCONTENT is used, the content element is omitted. When SELECT is used, only the selected fields appear in the content.

Redis CLI

SEARCH.QUERY products '{"name": "wireless"}' LIMIT 10 OFFSET 0

curl

curl -X POST https://YOUR_ENDPOINT.upstash.io \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
  -d '["SEARCH.QUERY", "products", "{\"name\": \"wireless\"}", "LIMIT", "10", "OFFSET", "0"]'

---

SEARCH.COUNT

Returns the number of documents matching a query without retrieving them.

SEARCH.COUNT <name> '<json_filter>'

Returns: An integer — the count of matching documents.

Redis CLI

SEARCH.COUNT products '{"inStock": true}'

curl

curl -X POST https://YOUR_ENDPOINT.upstash.io \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
  -d '["SEARCH.COUNT", "products", "{\"inStock\": true}"]'

---

SEARCH.AGGREGATE

Computes analytics (metrics and buckets) over matching documents.

SEARCH.AGGREGATE <name> '<json_filter>' '<json_aggregations>'

Response format (Redis CLI):

In redis-cli --json, the response is an object keyed by alias:

{
  "avg_price": { "value": 49.99 },
  "by_category": { "buckets": [{ "key": "electronics", "docCount": 42 }] }
}

Raw RESP output may be rendered differently by client/protocol settings, but semantically each top-level alias maps to its aggregation result.

Redis CLI

SEARCH.AGGREGATE products '{}' '{"avg_price": {"$avg": {"field": "price"}}}'

curl

curl -X POST https://YOUR_ENDPOINT.upstash.io \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
  -d '["SEARCH.AGGREGATE", "products", "{}", "{\"avg_price\": {\"$avg\": {\"field\": \"price\"}}}"]'

---

Alias Commands

SEARCH.ALIASADD

Creates or updates an alias pointing to an index.

SEARCH.ALIASADD <alias> <index_name>

Returns: 1 if a new alias was created, 2 if an existing alias was updated.

---

SEARCH.ALIASDEL

Removes an alias.

SEARCH.ALIASDEL <alias>

Returns: 1 if deleted, 0 if the alias was not found.

---

SEARCH.LISTALIASES

Returns all aliases and the indices they point to.

SEARCH.LISTALIASES

Returns: An array of [alias, index_name] pairs.

---

REST API Usage

All search commands can be sent via the Upstash REST API using a JSON array POST body. Each element of the array corresponds to a token in the command.

curl -X POST https://YOUR_ENDPOINT.upstash.io \
  -H "Authorization: Bearer $UPSTASH_REDIS_REST_TOKEN" \
  -d '["COMMAND", "arg1", "arg2", ...]'

The JSON filter and aggregation arguments are passed as string values within the array (not as nested JSON objects):

# Correct — filter is a string inside the array
["SEARCH.QUERY", "products", "{\"name\": \"wireless\"}", "LIMIT", "10"]

# Incorrect — filter is a nested object
["SEARCH.QUERY", "products", {"name": "wireless"}, "LIMIT", "10"]

Search commands also work through the /pipeline endpoint for batching multiple commands in a single HTTP request.