skip to content

What is a Redis vector set, and how do VADD and VSIM add elements and find the most similar ones?

level: juniorimportance: should knowfreq 25%

answer

  1. sorted set, minus the score
  2. string element plus an embedding
  3. VALUES takes a component count first
  4. ELE queries by an existing member
  5. COUNT defaults to ten

basics

~20 s

A vector set is a Redis key holding unique string elements, each paired with an embedding instead of a score. VADD inserts an element and its vector; VSIM returns the elements most similar to a given vector or element.

solid answer

~40 s

A vector set, which `TYPE` reports as `vectorset`, resembles a sorted set in holding unique strings, but each string carries a vector rather than a score. `VADD key VALUES 3 0.1 1.2 0.5 item` adds one and creates the key on first use; it replies 1 for a new element and 0 when the element already existed and its vector was replaced. `VSIM key VALUES ...` or `VSIM key ELE item` returns up to `COUNT` elements, ten by default, best match first, and `WITHSCORES` adds a similarity from 1 down to 0. The search walks an HNSW graph, so results are approximate unless you ask for `TRUTH`. Redis 8.0 introduced the type, and the 8.10 README still labels it beta.

code

plaintext · 13 lines
plaintext
> VADD points VALUES 2 1.0 1.0 pt:A
(integer) 1
> VADD points VALUES 2 -1.0 1.0 pt:C
(integer) 1
> VADD points VALUES 2 1.0 0 pt:E
(integer) 1
> TYPE points
vectorset
> VSIM points ELE pt:A WITHSCORES COUNT 2
1) "pt:A"
2) "1"
3) "pt:E"
4) "0.8535534143447876"

go deeper

for a junior

Recall the shape: a unique string plus a vector, VADD to write and VSIM to read, with VALUES carrying a component count before the numbers.

for a middle

Explain that the search is approximate because it walks an HNSW graph, that the vector returned by VEMB is approximate too, and what each kind of miss replies.

for a senior

Point out where the sorted-set comparison misleads: no rank, no score range, and a similarity that needs a recall measurement with TRUTH before you trust it in production.

for a principal

Mention the beta label early. Knowing the commands is the easy part; a lead asks whether a type still marked beta should carry this feature at all.

## What a vector set is A **vector set** is a Redis data type in which each **element** is a unique string tied to a **vector**, an array of floating point numbers. The vector is usually an **embedding**: the output of a machine-learning model that places similar items near each other. The type exists to answer one question: which elements lie closest to this vector, or closest to this element? `TYPE` reports such a key as `vectorset`. Redis does not compute embeddings. The application calls a model and hands Redis the numbers: 1. Turn each item into a vector with an embedding model. 2. Store it with `VADD`, under a short element name. 3. Turn the query into a vector with the same model. 4. Ask `VSIM` for the nearest elements, then use the names to fetch whatever they stand for. Redis added the type in 8.0. Its code sits under `modules/vector-sets` in the Redis source tree, but despite the folder name it is compiled into the server by default, so it needs no `loadmodule` line. The query engine and JSON differ here: a source build loads those from a module configuration. The 8.10 README still lists the type as "Vector set (beta)". ## Adding elements with VADD `VADD` takes the key, then the vector, then the element name: ``` VADD points VALUES 2 1.0 1.0 pt:A ``` - **`VALUES 2 1.0 1.0`** sends the vector as text, prefixed by its number of components. - **`FP32 <blob>`** is the binary alternative: 32-bit floats in little-endian order. The module README reports 10-20x speedups over `VALUES` for real embeddings. - **The first `VADD` creates the key** and fixes its dimension. A later vector of another length gets `ERR Vector dimension mismatch`. - **The reply** is 1 for a new element and 0 when the element already existed, in which case its vector is replaced. Vectors are normalized on insert and stored as 8-bit integers by default, so `VEMB`, which reads a vector back, returns an approximation of what you sent. ## Querying with VSIM `VSIM` names the key, then the query in one of three forms: `VALUES`, `FP32` or `ELE` plus an existing element. - **`COUNT`** caps the results, and defaults to 10. - **`WITHSCORES`** adds a similarity for each result, where 1 means identical and 0 means opposite. - **Order** is best match first. With `ELE`, the queried element itself normally comes back at the top. - **Misses differ:** a missing key replies with an empty array, while an unknown `ELE` element replies with `ERR element not found in set`. The search is **approximate**. Inside the key sits an **HNSW** (hierarchical navigable small world) graph, a layered structure of links between nearby vectors. `VSIM` walks those links and inspects a small part of the set, which is why it stays fast on millions of elements and why it can occasionally miss a true neighbour. The `TRUTH` option does an exact linear scan instead; that is a tool for measuring recall, not for serving traffic. ## Where the sorted-set analogy stops The Redis docs introduce the type as similar to a sorted set, and the likeness is real only for the outer shape. | Question | Sorted set | Vector set | |---|---|---| | What sits beside each unique string? | One numeric score | A vector, plus optional JSON attributes | | How do you normally read it? | By rank or score range | By similarity to a query | | Is the order exact? | Yes | Approximate, unless `TRUTH` is used | | Is there a range by name? | Yes, lexicographic ranges | Yes, `VRANGE`, since 8.4 | | How is one element removed? | `ZREM` | `VREM` | A vector set has no rank and no score to range over. Sorted-set commands such as `ZRANGE` do not work on it, because it is a distinct type. ## The smaller commands - **`VREM`** removes one element and reclaims its memory at once. Removing the last element removes the key. - **`VCARD`** returns the element count and **`VDIM`** the vector dimension. - **`VISMEMBER`** tests whether an element exists. - **`VSETATTR`** and **`VGETATTR`** write and read an element's JSON attributes, which the `FILTER` option of `VSIM` can test. - **`VINFO`** reports the quantization type, the graph's `M` setting and the element count.

  • Why does `VSIM key ELE item` usually return `item` itself, and what do you do about it?
    `ELE` reads the element's stored vector and searches with it, and nothing is closer to a vector than itself, so the element ranks first with a score near 1. For a 'more like this' feature, ask for one extra result with `COUNT` and drop the queried name in the application.
  • When would you send vectors with `FP32` instead of `VALUES`?
    For almost any real embedding. `VALUES` formats each float as text, which is slow to serialize and large on the wire, and the module README reports 10-20x speedups from `FP32`. The blob must be 32-bit floats in little-endian order. `VALUES` stays useful by hand in `redis-cli` and on platforms with a different byte order.

A sorted set is a leaderboard: every name has one number, and you read it by position. A vector set is a map with named pins: a pin has coordinates rather than a rank, and the natural question is which pins lie nearest this spot.

  • A vector set is a sorted set with the vector stored as the score.
  • VSIM returns the exact nearest elements by default.
  • You must create the key before the first VADD.
  • VADD on an existing element fails, so you delete the element first.
  • ZRANGE on a vector set lists elements in similarity order.
  • Redis computes the embedding when you pass text to VADD.

Assumes Redis 8.10; the type arrived in 8.0, is still labelled beta in the 8.10 README, and VRANGE arrived in 8.4.