> ## Documentation Index > Fetch the complete documentation index at: https://upstash.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # VECTOR.QUERY > Find the nearest vectors to a query vector. Use `VECTOR.QUERY` to find the IDs whose vectors are closest to a query vector. `TOPK` sets how many results to return, and the query vector is given in the same three forms [`VECTOR.ADD`](/docs/redis/commands/vector/vector-add) accepts. The reply is a list of ID and score pairs, best match first. Scores are normalized to the range `0` to `1` for every metric, so a higher score always means a closer match and a threshold can be applied without knowing which metric the index uses. `PROFILE` trades recall against latency. `FAST` examines less of the index and returns sooner, `PRECISE` examines more and is likelier to return the true nearest neighbours, and `BALANCED`, the default, sits between them. The profile only changes how the query reads the index, never what is stored, so it can be varied per call. Search is approximate: a query may miss a true neighbour, and raising `TOPK` or moving to `PRECISE` reduces how often that happens. Asking for more results than the index holds simply returns everything it has. Vector indexes are an Upstash extension. See the [vector command overview](/docs/redis/commands/vector/overview) for how an index is created, written to, and queried. ## Syntax ```redis theme={"system"} VECTOR.QUERY TOPK [ ...] | FP32 | BASE64-FP32 > [PROFILE ] ``` ## Arguments | Argument | Required | Repeatable | Description | | - | - | - | - | | `` | Yes | No | Key holding the vector index. | | `TOPK ` | Yes | No | Maximum number of results to return. Must be between `1` and `1000`. | | `VALUES [ ...]` | No | No | Vector given as `` decimal elements. | | `FP32 ` | No | No | Vector given as a raw binary blob of little-endian 32-bit floats. Its length must be a non-zero multiple of 4. | | `BASE64-FP32 ` | No | No | Vector given as the standard base64 encoding of an `FP32` blob. | | `PROFILE ` | No | No | Recall and latency trade-off: `FAST`, `BALANCED`, or `PRECISE`. Defaults to `BALANCED`. | ## Important points * `TOPK` and the query vector are both required; the clauses may be given in any order. * The three vector forms are mutually exclusive and exactly one must be given. `VALUES` is the readable form; `FP32` avoids decimal formatting on a binary-safe connection; `BASE64-FP32` carries the same bytes through JSON, which is what the [REST API](/docs/redis/features/restapi) needs. * Results are ordered by score, highest first. Scores are normalized to `0` through `1` for every metric. * A query vector whose length differs from the index's `DIM` returns `ERR vector dimension mismatch: expected , got `. ## Response The reply reports the result of the operation. Error replies have the same shape in RESP2 and RESP3 and are surfaced as exceptions by the SDKs below. | Protocol | Reply | | - | - | | RESP2 | Array of two-element arrays, each an ID and its score as a bulk string containing a number | | RESP3 | Array of two-element arrays, each an ID and its score as a double | > [!NOTE] > > Client libraries often decode bulk strings, maps, sets, and numeric strings into language-native values. The table describes the Redis wire reply. ## Examples TCP examples use the TLS `REDIS_URL` from the Upstash console. REST examples use `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`. > **Redis CLI** > > ```bash theme={"system"} > VECTOR.QUERY my-index TOPK 5 VALUES 3 0.1 0.2 0.3 > ``` > **@upstash/redis** > > ```ts theme={"system"} > import { Redis } from "@upstash/redis"; > > const redis = Redis.fromEnv(); > > const index = redis.vector.index("my-index"); > const results = await index.query({ vector: [0.1, 0.2, 0.3], topK: 5 }); > console.log(results); // [{ id, score }, ...] > ``` > **upstash\_redis** > > ```python theme={"system"} > from upstash_redis import Redis > > redis = Redis.from_env() > > index = redis.vector.index("my-index") > results = index.query(vector=[0.1, 0.2, 0.3], top_k=5) > for match in results: > print(match.id, match.score) > ``` > **ioredis** > > ```ts theme={"system"} > import Redis from "ioredis"; > > const redis = new Redis(process.env.REDIS_URL!); > const result = await redis.call("VECTOR.QUERY", "my-index", "TOPK", "5", "VALUES", "3", "0.1", "0.2", "0.3"); > console.log(result); > ``` > **node-redis** > > ```ts theme={"system"} > import { createClient } from "redis"; > > const client = await createClient({ url: process.env.REDIS_URL }) > .on("error", console.error) > .connect(); > const result = await client.sendCommand(["VECTOR.QUERY", "my-index", "TOPK", "5", "VALUES", "3", "0.1", "0.2", "0.3"]); > console.log(result); > ``` > **redis-py** > > ```python theme={"system"} > import os > import redis > > client = redis.from_url(os.environ["REDIS_URL"]) > result = client.execute_command("VECTOR.QUERY", "my-index", "TOPK", "5", "VALUES", "3", "0.1", "0.2", "0.3") > print(result) > ``` > **go-redis** > > ```go theme={"system"} > 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(), "VECTOR.QUERY", "my-index", "TOPK", "5", "VALUES", "3", "0.1", "0.2", "0.3").Result() > if err != nil { > panic(err) > } > fmt.Println(result) > } > ``` > **jedis** > > ```java theme={"system"} > import java.net.URI; > > import redis.clients.jedis.Jedis; > > try (Jedis jedis = new Jedis(new URI(System.getenv("REDIS_URL")))) { > Object result = jedis.sendCommand(() -> "VECTOR.QUERY".getBytes(), "my-index", "TOPK", "5", "VALUES", "3", "0.1", "0.2", "0.3"); > System.out.println(result); > } > ``` > **redis-rs** > > ```rust theme={"system"} > 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("VECTOR.QUERY"); > command.arg("my-index"); > command.arg("TOPK"); > command.arg("5"); > command.arg("VALUES"); > command.arg("3"); > command.arg("0.1"); > command.arg("0.2"); > command.arg("0.3"); > let result: redis::Value = command.query(&mut connection)?; > println!("{result:?}"); > Ok(()) > } > ``` ## Related topics - [Query Vectors](/docs/vector/api/endpoints/query.md) - [Vector commands](/docs/redis/commands/vector/overview.md) - [Hybrid Indexes](/docs/vector/features/hybridindexes.md) - [Getting Started](/docs/vector/overall/getstarted.md) - [Metadata and Data](/docs/vector/features/metadata.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.