SEARCH.QUERY - Upstash Documentation

Use SEARCH.QUERY to search for documents matching a JSON filter. The filter is a JSON object naming index fields and the values to match, so '{"name": "headphones", "inStock": true}' combines conditions with an implicit AND. Text fields are matched with the analysis configured in the schema while other types are matched exactly, and operators such as $fuzzy, $prefix, $range, $or, and $mustNot cover the cases where plain field matching is not enough. Querying an index that does not exist returns null. Results come back ordered by relevance score by default. ORDERBY sorts by a FAST field instead, LIMIT and OFFSET page through the matches, SELECT and NOCONTENT cut the payload down to the fields you need, HIGHLIGHT wraps the matched terms in tags for display, and SCOREFUNC blends numeric fields such as popularity or recency into the relevance score. For multi-value TEXT, KEYWORD, U64, I64, F64, and DATE fields, a document matches when any indexed array element satisfies the condition. Phrase queries on TEXT stay within one array element. HIGHLIGHT preserves the stored array shape in the response, marking matching string elements while leaving other elements unchanged. See Multi-value queries for examples. See Querying and filtering for the full filter syntax and worked examples, and SEARCH.COUNT when you only need the number of matches.

Syntax

SEARCH.QUERY <name> '<query>'
  [LIMIT <count>]
  [OFFSET <offset>]
  [ORDERBY <field> [ASC|DESC]]
  [SELECT <count> <field> [<field> ...]]
  [NOCONTENT]
  [HIGHLIGHT FIELDS <count> <field> [<field> ...] [TAGS <open> <close>]]
  [SCOREFUNC
    FIELDVALUE <field>
      [MODIFIER <NONE|LOG|LOG1P|LOG2P|LN|LN1P|LN2P|SQUARE|SQRT|RECIPROCAL>]
      [FACTOR <number>]
      [MISSING <number>]
    [FIELDVALUE ...]
    [SCOREMODE <SUM|MULTIPLY|REPLACE>]
    [COMBINEMODE <SUM|MULTIPLY>]]

Arguments

Argument	Description	Default
`LIMIT`	Maximum number of results to return. Must be between 1 and 1000.	`10`
`OFFSET`	Number of results to skip for pagination. Must be between 0 and 10,000.	`0`
`ORDERBY`	Sort by a `FAST` field. The direction defaults to `DESC` when omitted.	Relevance score, descending
`SELECT`	Return only the specified number of document fields. When the schema uses `FROM`, specify the source document field rather than its index alias.	All fields
`NOCONTENT`	Return keys and scores without document content.	Disabled
`HIGHLIGHT`	Wrap matching terms in tags. The default tags are `<em>` and `</em>`.	Disabled
`SCOREFUNC`	Adjust relevance scores using one or more `FAST` numeric fields. `FACTOR` defaults to `1`, `MISSING` to `0`, `MODIFIER` to `NONE`, `SCOREMODE` to `SUM`, and `COMBINEMODE` to `SUM`.	Disabled

NOCONTENT cannot be combined with SELECT or HIGHLIGHT. SCOREFUNC cannot be combined with ORDERBY. Inside MULTI or EVAL, the command requires NOCONTENT.

See Querying and filtering for the JSON filter operators and detailed query examples.

Response

Returns an array of [key, score, content] results, or null if the index does not exist:

key is the Redis key of the matching document.
score is the floating-point relevance score.
content is an array of field-value pairs. JSON indexes return [["$", "<json_string>"]]; hash indexes return [["field", "value"], ...].

When NOCONTENT is used, each result is [key, score]. When SELECT is used, only fields that exist in the document appear in the content. For an index created with ON STREAM, key is the entry ID of the matching stream entry. A highlighted multi-valued field keeps its array form in the reply. Highlighting a on a document whose a is ["hello world", "foo & bar", 7] returns ["<em>hello</em> world","foo & bar",7].

[
  ["key1", 1.25, [["$", "{\"name\":\"...\"}"]]],
  ["key2", 0.75, [["$", "{\"name\":\"...\"}"]]]
]

Examples

Redis CLI

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

@upstash/redis

import { Redis, s } from "@upstash/redis";

const redis = Redis.fromEnv();
const products = redis.search.index({
  name: "products",
  schema: s.object({ name: s.string() }),
});

const results = await products.query({
  filter: { name: "wireless" },
  limit: 10,
  offset: 0,
});

upstash_redis

from upstash_redis import Redis

redis = Redis.from_env()
products = redis.search.index(name="products")

results = products.query(
    filter={"name": "wireless"},
    limit=10,
    offset=0,
)

ioredis

import IORedis from "ioredis";
import { createSearch, s } from "@upstash/search-ioredis";

const redis = new IORedis(process.env.REDIS_URL!);
const search = createSearch(redis);
const products = search.index({
  name: "products",
  schema: s.object({ name: s.string() }),
});

const results = await products.query({
  filter: { name: "wireless" },
  limit: 10,
  offset: 0,
});

node-redis

import { createClient } from "redis";
import { createSearch, s } from "@upstash/search-redis";

const client = await createClient({ url: process.env.REDIS_URL })
  .on("error", console.error)
  .connect();
const search = createSearch(client);
const products = search.index({
  name: "products",
  schema: s.object({ name: s.string() }),
});

const results = await products.query({
  filter: { name: "wireless" },
  limit: 10,
  offset: 0,
});

redis-py

import os
import redis

client = redis.from_url(os.environ["REDIS_URL"])
result = client.execute_command(
    "SEARCH.QUERY",
    "products",
    "{\"name\": \"wireless\"}",
    "LIMIT",
    "10",
    "OFFSET",
    "0",
)
print(result)

go-redis

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/redis/go-redis/v9"
)

func main() {
    opts, err := redis.ParseURL(os.Getenv("REDIS_URL"))
    if err != nil {
        panic(err)
    }
    client := redis.NewClient(opts)
    result, err := client.Do(
        context.Background(),
        "SEARCH.QUERY",
        "products",
        "{\"name\": \"wireless\"}",
        "LIMIT",
        "10",
        "OFFSET",
        "0",
    ).Result()
    if err != nil {
        panic(err)
    }
    fmt.Println(result)
}

jedis

import java.net.URI;

import redis.clients.jedis.Jedis;

try (Jedis jedis = new Jedis(new URI(System.getenv("REDIS_URL")))) {
  Object result = jedis.sendCommand(
      () -> "SEARCH.QUERY".getBytes(),
      "products",
      "{\"name\": \"wireless\"}",
      "LIMIT",
      "10",
      "OFFSET",
      "0"
  );
  System.out.println(result);
}

redis-rs

fn main() -> redis::RedisResult<()> {
    let url = std::env::var("REDIS_URL").expect("REDIS_URL is not set");
    let client = redis::Client::open(url)?;
    let mut connection = client.get_connection()?;

    let mut command = redis::cmd("SEARCH.QUERY");
    command.arg("products");
    command.arg("{\"name\": \"wireless\"}");
    command.arg("LIMIT");
    command.arg("10");
    command.arg("OFFSET");
    command.arg("0");
    let result: redis::Value = command.query(&mut connection)?;
    println!("{result:?}");
    Ok(())
}

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"]'

​Syntax

​Arguments

​Response

​Examples

Syntax

Arguments

Response

Examples