VSIM

Syntax
VSIM key (ELE | FP32 | VALUES num) (vector | element) [WITHSCORES] [WITHATTRIBS] [COUNT num]
  [EPSILON delta] [EF search-exploration-factor] [FILTER expression] [FILTER-EF max-filtering-effort]
  [TRUTH] [NOTHREAD]
Available since:
Redis Open Source 8.0.0
Time complexity:
O(log(N)) where N is the number of elements in the vector set.

Return elements similar to a given vector or element. Use this command to perform approximate or exact similarity searches within a vector set.

You can query using either a vector (via FP32 or VALUES num) or by referencing another element (using ELE). Optional parameters let you control the search behavior, such as score output, result count, and filtering options.

VSIM word_embeddings ELE apple
1) "apple"
2) "apples"
3) "pear"
4) "fruit"
5) "berry"
6) "pears"
7) "strawberry"
8) "peach"
9) "potato"
10) "grape"

You can include similarity scores, attributes (if any), and limit the number of results:

VSIM word_embeddings ELE apple WITHSCORES WITHATTRIBS COUNT 3
1) "apple"
2) "0.9998867657923256"
3) "{\"len\": 5}"
4) "apples"
5) "0.859852746129036"
6) "{\"len\": 6}"
7) "pear"
8) "0.8226882070302963"
9) "{\"len\": 4}"

Set the EF (exploration factor) to improve recall at the cost of performance. Use the TRUTH option to perform an exact linear scan, useful for benchmarking. The NOTHREAD option runs the search in the main thread and may increase server latency.

Required arguments

key

is the name of the key that holds the vector set data.

ELE | FP32 | VALUES num

specifies how the input vector is provided. Use ELE to refer to an existing element, FP32 for binary float format, or VALUES num for a list of stringified float values.

vector or element

is either the vector data (for FP32 or VALUES) or the name of the element (for ELE) to use as the similarity reference.

Optional arguments

WITHSCORES

returns the similarity score (from 1 to 0) alongside each result. A score of 1 is identical; 0 is the opposite.

WITHATTRIBS

returns, for each element, the JSON attribute associated with the element or NULL when no attributes are present.

COUNT num

limits the number of returned results to num.

EPSILON delta

is a floating point number between 0 and 1. It is used to retrieve elements that have a distance that is no further than the specified delta. In vector sets, returned elements have a similarity score (when compared to the query vector) that is between 1 and 0, where 1 means identical and 0 means opposite vectors. For example, if the EPSILON option is specified with an argument of 0.2, it means only elements that have a similarity of 0.8 or better (a distance < 0.2) are returned. This is useful when you specify a large COUNT, but you don't want elements that are too far away from the query vector.

EF search-exploration-factor

controls the search effort. Higher values explore more nodes, improving recall at the cost of speed. Typical values range from 50 to 1000.

FILTER expression

applies a filter expression to restrict matching elements. See the filtered search section for syntax details.

FILTER-EF max-filtering-effort

limits the number of filtering attempts for the FILTER expression. See the filtered search section for more.

TRUTH

forces an exact linear scan of all elements, bypassing the HNSW graph. Use for benchmarking or to calculate recall. This is significantly slower (O(N)).

NOTHREAD

executes the search in the main thread instead of a background thread. Useful for small vector sets or benchmarks. This may block the server during execution.

Return information

One of the following:

History

  • Starting with Redis version 8.2.0: added the WITHATTRIBS option.