skip to content

In Redis, how does a vector set differ from a VECTOR field in an FT.CREATE index, and when does each one fit?

level: middleimportance: should knowfreq 25%

answer

  1. where do the vectors live
  2. one key or many documents
  3. metric chosen, or fixed
  4. attributes scanned, fields indexed
  5. who merges across shards

basics

~20 s

A vector set is one key holding its own elements, graph and JSON attributes, with cosine ranking. A VECTOR field indexes vectors stored in hash or JSON documents and combines them with text, tag and numeric fields in queries.

solid answer

~40 s

A vector set is a self-contained data type: one key holds the elements, the HNSW graph and optional JSON attributes, and you talk to it with `VADD` and `VSIM`. A `VECTOR` field belongs to a query-engine index: vectors stay in hashes or JSON documents under a key prefix, `FT.CREATE` builds a secondary index over them, and you choose `FLAT`, `HNSW` or `SVS-VAMANA` and a metric of `L2`, `IP` or `COSINE`. So the index fits when vector search must combine with text, tags or aggregation over documents you already store, with each document keeping its own TTL. The vector set fits a simple similarity job where a command or two is enough, at the price of cosine only, no per-element expiry, a beta label, and splitting across keys yourself.

code

plaintext · 9 lines
plaintext
# Vector set: the key is the whole structure
VADD emb:vset VALUES 3 0.1 0.2 0.3 doc:1
VSIM emb:vset VALUES 3 0.1 0.2 0.3 COUNT 5

# Query engine: the vector stays in a hash, the index sits beside it
FT.CREATE documents ON HASH PREFIX 1 docs:
  SCHEMA doc_embedding VECTOR HNSW 6
    TYPE FLOAT32 DIM 3 DISTANCE_METRIC COSINE
HSET docs:1 doc_embedding <vector_bytes> category sports

go deeper

for a junior

Remember the core split: a vector set is one key of its own type, while a VECTOR field indexes vectors held in hashes or JSON documents.

for a middle

Explain the consequences of that split: a fixed metric, a filter evaluated during the walk with no attribute index, element-level expiry absent, and a split-it-yourself approach to scale.

for a senior

Reason from the query mix: selective filters, full text or per-document TTL point to the index, and a bounded similarity job with light attributes points to the type.

for a principal

Weigh a beta type against a schema your team must own. Keep a single pattern per kind of job so the organisation does not run both for the same collection.

## Two separate features Redis 8 ships two unrelated ways to search vectors, and they share no storage. - A **vector set** is a data type. One key of type `vectorset` holds the elements, their vectors, an **HNSW** graph (a layered structure of links between nearby vectors) and optional JSON attributes. Commands are `VADD`, `VSIM`, `VREM` and friends. - A **`VECTOR` field** is part of a schema in the **query engine**. Your vectors remain ordinary fields in hashes or JSON documents; `FT.CREATE` defines a **secondary index** over the keys matching a prefix, and you search with the query engine's commands. An `FT.CREATE` index reads `HASH` or `JSON` documents, so it cannot index a vector set, and `VSIM` cannot read an index. They do not interoperate. The 8.0 release notes describe vector sets as complementing the existing vector search in the query engine, not replacing it. ## Side by side | Aspect | Vector set | `VECTOR` field in `FT.CREATE` | |---|---|---| | Where vectors live | Inside one `vectorset` key | In hash or JSON documents | | How you write | `VADD` | `HSET` or `JSON.SET`, and the index follows | | Search structure | HNSW only, plus a `TRUTH` linear scan | `FLAT`, `HNSW` or `SVS-VAMANA` | | Metric | Fixed: cosine, or normalized Hamming with `BIN` | `DISTANCE_METRIC` of `L2`, `IP` or `COSINE` | | Other data | One JSON string per element | Indexed text, tag, numeric and geo fields | | Filtering | Expression tested on nodes during the walk | Planner picks batches or brute force | | Expiry | Whole key only | Each document key keeps its own TTL | | Redis Cluster | One key in one slot; you split and merge | Results fan out and merge across shards | | Status in 8.10 | README says beta | Part of Redis since 8.0, with no beta label | ## How filtering differs This is the difference that decides most real cases. `VSIM` with `FILTER` evaluates a small expression against the JSON attributes of each node the search visits. There is **no index on attributes**. The search walks the graph and tests as it goes, up to a limit of `COUNT * 100` candidates by default, and when matches are rare it may return fewer results than you asked for. The query engine holds real indexes on `TAG` and `NUMERIC` fields. Its docs describe two strategies, chosen by heuristics: pulling batches of nearest neighbours until enough pass the filter, or scoring every document that passes it, which is exact. So a selective filter is a normal case there, and it is the hard case for a vector set. ## Operational differences - **Expiry.** A vector set has no element-level TTL; you remove entries with `VREM`. A document in an index is an ordinary key with its own expiry, and the docs state that from Redis 8 a query returns only documents that are valid when it starts. - **Scaling.** Every vector set command names one key, and one key lives in one slot on one node. To grow past that, you partition into several keys and merge `VSIM ... WITHSCORES` results in the client. The query engine handles fan-out itself: its docs even offer `$SHARD_K_RATIO` to tune how many results each shard fetches. - **Availability.** Vector sets compile into the server by default. On a source build, the query engine loads from a module configuration such as `redis-full.conf`, so a plain build with no module configuration does not have `FT.CREATE`. - **Payload shape.** A vector set keeps little beyond a name per element, so the application usually fetches the real record elsewhere. An index can return document fields directly. ## Choosing 1. Do you need full-text, tag or numeric queries, aggregation, or hybrid ranking? Use the query engine. 2. Are the vectors attributes of documents you already keep in hashes or JSON? Use the query engine, and add a field to the schema. 3. Do you need `L2` or inner product as the metric? Use the query engine. A vector set normalizes vectors on insert, so length cannot influence ranking. 4. Is it a bounded similarity job, such as a semantic cache, semantic routing or 'related items' over one collection, with light attributes? A vector set is the shorter path, with far less schema to manage. The last case has a real appeal: no index to define, no schema to migrate, and threaded searches by default. The price is the beta label and doing your own partitioning and expiry.

  • Can `VSIM`'s `FILTER` stand in for a `TAG` field when most queries filter on one rare value?
    Not well. `FILTER` tests each node the graph walk reaches, with no index, so a rare value burns the effort limit and may return too few results. Either raise `FILTER-EF` and pay the time, split the collection into one key per value, or use a query-engine index, whose planner can score just the matching documents.
  • Why might a team still pick the vector set when it already runs the query engine?
    For a small, separate job such as a semantic cache, it avoids a schema, a prefix and document keys. `VSIM` runs on a background thread by default and `VREM` reclaims memory at once. If the data does not need text or tag queries, an index adds nothing. The trade is the beta label and managing expiry yourself.

  • A vector set is a convenience wrapper over the query engine's HNSW index.
  • FILTER uses indexes on attributes, so selective filters are cheap.
  • FT.CREATE can index an existing vector set key.
  • Both let you choose L2, IP or COSINE as the metric.
  • A vector set element can expire on its own, like a document key.

Assumes Redis 8.10; the query engine became part of Redis in 8.0, and the 8.10 README still marks vector sets as beta.