VSIM.SEARCH

Last updated 12 Oct 2026

VSIM.SEARCH index k value [value ...] [FILTER tag [tag ...]] [EF ef]

Group: Vector search
Complexity: O(log N) on average, N being the vectors in the index
Arity: -4 (at least 4 words, counting the command name)
Flags: read-only, slow
Keys: first 1, last 1, step 1
HotKV Cloud: All plans
On-Premise: no license needed

VSIM.SEARCH returns up to k keys from the vector index index whose vectors are closest to the query vector, nearest first, each with its distance. Give exactly as many values as the index has dimensions, right after k. The search is approximate: on large indexes a true neighbor can occasionally be missed; raise EF (or the index’s EF_SEARCH) to make that rarer.

Options

Option	Effect
`FILTER tag [tag ...]`	Only consider keys that carry all of these tags (see TAG.SET).
`EF ef`	Search effort for this call, at least 1. Higher is more accurate and slower. Defaults to the index’s `EF_SEARCH`.

FILTER takes every argument after it up to EF or the end. Tags are read from the node that runs the search, so in cluster mode a filtered search only sees tags set on that node.

Distances

Lower always means closer. What the number means depends on the index metric:

Metric	Distance
`COSINE`	1 minus the cosine similarity: 0 for the same direction, up to 2.
`L2`	The squared Euclidean distance.
`IP`	The negative inner product.

Return value

A flat array: key, distance, key, distance, and so on, nearest first. Keys and distances are bulk strings (distances with up to 8 significant digits). The shape is the same in RESP2 and RESP3. The array is empty when the index has no matching vectors.

Error replies:

ERR index 'name' not found
ERR invalid k (must be >= 1)
ERR expected 3 dimensions after k (with the index’s count) when values are missing.
ERR invalid float at dimension 0 for a value that is not a finite number.
ERR EF requires a value and ERR invalid EF value

Arguments after the vector other than FILTER and EF are ignored.

Examples

127.0.0.1:6379> VSIM.CREATEINDEX points 3 METRIC L2
OK
127.0.0.1:6379> VSIM.SET points p:1 1 0 0
(integer) 1
127.0.0.1:6379> VSIM.SET points p:2 1 1 0
(integer) 1
127.0.0.1:6379> VSIM.SET points p:3 0 2 2
(integer) 1
127.0.0.1:6379> VSIM.SEARCH points 2 1 0 0
1) "p:1"
2) "0"
3) "p:2"
4) "1"
127.0.0.1:6379> SET p:3 "..."
OK
127.0.0.1:6379> TAG.SET p:3 featured
(integer) 1
127.0.0.1:6379> VSIM.SEARCH points 2 1 0 0 FILTER featured
1) "p:3"
2) "9"

Compatibility

HotKV-only command. It is not related to the VSIM command of Redis 8 vector sets.

Ask the HotKV docs