Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 42 ยท Caching and Application Patterns

Redis Stack: JSON, Search and Vectors

Store documents with Redis JSON, query them with secondary indexes and full-text search, and use vector similarity for AI caching. Includes runnable stand-ins.

Core Redis finds data by key. That is fast and simple, but sooner or later you ask a different question: "all users in Oslo aged 30 to 40", "articles that mention caching", "the three FAQ entries closest in meaning to this question". With only strings, hashes and sets you would have to maintain your own indexes by hand. Redis offers ready-made answers in a set of capabilities that began as separate modules (bundled as Redis Stack) and are part of the standard distribution in recent major versions (Redis 8 and later; check what your server, managed service or Docker image actually includes with MODULE LIST or INFO modules).

This lesson introduces three of them: JSON documents, the query engine (secondary indexes, full-text search and aggregation, commands starting with FT.), and vector similarity search, which powers semantic search and AI response caches. You will also learn when plain data types are still the better choice.

Real Redis cannot run on this page, and these modules are the furthest from what a browser can imitate. So every command is shown as a read-only redis-cli transcript, and the runnable examples are JavaScript stand-ins that implement the ideas (path navigation, an inverted index, nearest-neighbour search). They are not the real engine and are not meant to match its speed or its exact query syntax.

Three capabilities

JSON Nested documents with path commands.
Search Indexes, text, filters, aggregates.
Vectors Find items closest in meaning.
1 / 2

JSON documents

A Redis JSON key holds a whole document: nested objects, arrays, strings, numbers, booleans and null. Unlike a JSON string stored with SET, Redis understands the structure, so you can read or change one part without sending the whole document back and forth.

TEXT
127.0.0.1:6379> JSON.SET user:1 $ '{"name":"Ana","age":31,"city":"Oslo","tags":["admin","beta"]}'
OK
127.0.0.1:6379> JSON.GET user:1 $.name
"[\"Ana\"]"
127.0.0.1:6379> JSON.NUMINCRBY user:1 $.age 1
"[32]"
127.0.0.1:6379> JSON.ARRAPPEND user:1 $.tags '"vip"'
1) (integer) 3
127.0.0.1:6379> JSON.GET user:1
"{\"name\":\"Ana\",\"age\":32,\"city\":\"Oslo\",\"tags\":[\"admin\",\"beta\",\"vip\"]}"

Paths use the JSONPath style that starts with $ (the root). Because a path can match several places, commands given a $ path reply with a JSON array of matches, which is why $.name returns ["Ana"]. Other useful commands: JSON.DEL, JSON.TYPE, JSON.STRLEN, JSON.OBJKEYS, JSON.MGET and JSON.TOGGLE. Updates such as JSON.NUMINCRBY are atomic, like other Redis commands.

When should you use JSON instead of a hash? Hashes are flat (field to string), compact and fast for records with simple fields. JSON wins when the data is nested or has arrays, when you want to update deep parts atomically, or when you want to index nested fields. A JSON string in a plain SET is only right if you always read and write the whole thing.

JS A JSON path stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The stand-in handles only simple paths ($, .field, [index]); real Redis JSON supports wildcards, filters and recursive descent too. The reply shapes match real Redis: a found path gives a one-element array, a missing path gives an empty array, and NUMINCRBY on a string gives [null].

Secondary indexes with the query engine

The query engine builds an index over keys whose names start with a prefix and then answers queries from it. You declare which fields to index and how:

TEXT
127.0.0.1:6379> FT.CREATE idx:users ON JSON PREFIX 1 user: SCHEMA
    $.name AS name TEXT
    $.city AS city TAG
    $.age AS age NUMERIC SORTABLE
OK
127.0.0.1:6379> FT.SEARCH idx:users "@city:{Oslo} @age:[30 40]"
1) (integer) 1
2) "user:1"
3) 1) "$"
   2) "{\"name\":\"Ana\",\"age\":32,\"city\":\"Oslo\", ...}"

Field types: TAG for exact values such as city, status or category; NUMERIC for ranges (@age:[30 40]); TEXT for full-text search with tokenizing, stemming and ranking; GEO for locations; VECTOR for embeddings. ON HASH indexes hashes the same way (field names instead of JSON paths). The index updates itself as keys change, so there is no manual bookkeeping, and FT.SEARCH supports sorting, paging (LIMIT 0 10), returning chosen fields (RETURN), highlighting and more. FT.AGGREGATE groups and computes (for example a count per city) on the server.

Behind the scenes, a text or tag index is an inverted index: a map from each term to the set of documents that contain it. A query intersects or unions those sets. The next TryIt builds exactly that idea in a few lines: tag and text lookups through an inverted index, and a numeric range check, combined with AND.

JS A mini search index

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The stand-in has no ranking, stemming or stop words; real full-text search handles those, so cache can also find caching there while the stand-in only does exact terms and the explicit cach* prefix.

Trade-offs of indexing

Indexes cost memory (the index lives in RAM next to the data) and a little write time (each change updates the index). They shine for read-heavy lookups over fields you decide in advance. Alternatives built from basic types, such as a set per tag (SADD city:oslo user:1) or a sorted set per numeric field, are lighter and perfectly good for one or two simple access paths. Reach for the query engine when you need several combined filters, text search, sorting by arbitrary fields or aggregation.

Vector similarity for AI

An embedding is a list of numbers (a vector) that a machine-learning model produces for a piece of text or an image so that things with similar meaning get vectors that point in similar directions. Real embeddings have hundreds or thousands of dimensions. Vector search finds the stored vectors nearest to a query vector, the k nearest neighbours (KNN). Closeness is measured with a distance metric: COSINE (angle between vectors), L2 (straight-line distance) or IP (inner product).

TEXT
127.0.0.1:6379> FT.CREATE idx:faq ON HASH PREFIX 1 faq: SCHEMA
    answer TEXT
    embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINE
OK
127.0.0.1:6379> FT.SEARCH idx:faq "*=>[KNN 3 @embedding $vec AS dist]"
    PARAMS 2 vec "<binary FLOAT32 blob>" SORTBY dist DIALECT 2

The vector is sent as raw binary (little-endian 32-bit floats), which a client library builds for you. The index algorithm is FLAT (exact, compares everything, fine for small sets) or HNSW (approximate graph search, much faster on large sets, with a small chance of missing the true nearest neighbour). DIM must match your embedding model's output size.

Two common uses:

  • Semantic search / retrieval for LLM apps: embed documents once, embed each question, fetch the nearest chunks.
  • Semantic caching of AI responses: language-model calls are slow and cost money. If a new prompt is very close in meaning to one answered before, return the stored answer instead of calling the model.
flowchart TD
    A["New prompt"] --> B["Embed the prompt"]
    B --> C["KNN 1 in Redis"]
    C --> D{"distance below threshold?"}
    D -- yes --> E["Return cached answer"]
    D -- no --> F["Call the language model"]
    F --> G["Store prompt vector + answer (with TTL)"]
    G --> H["Return answer"]

A semantic cache only calls the model when no stored prompt is close enough.

The threshold is the hard part: too loose and users get answers to a slightly different question; too strict and the cache never hits. Tune it on real traffic, and give entries a TTL.

JS Nearest neighbours and a semantic cache

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Both real questions land within the threshold of the matching FAQ entry, while the unrelated question is far from everything and falls through to the model. This is exactly the decision the real cache makes, only with learned vectors and an HNSW index.

Time series: TS.* commands

A time series is a list of (timestamp, number) samples, such as a temperature every second or requests per minute. You could store them in a sorted set, but the TimeSeries data type (part of Redis 8 and of Redis Stack) does the bookkeeping for you: compact storage, automatic expiry of old samples, labels for finding series, and server-side aggregation.

Text
TS.CREATE sensor:1:temp RETENTION 86400000 LABELS room kitchen kind temp
TS.ADD sensor:1:temp * 21.5            # * means "use the server time in milliseconds"
TS.ADD sensor:1:temp 1700000060000 21.7
TS.RANGE sensor:1:temp - + AGGREGATION avg 60000
TS.GET sensor:1:temp                   # latest sample
TS.MRANGE - + FILTER room=kitchen      # query many series by label
  • RETENTION is in milliseconds. Samples older than that (relative to the newest sample) are dropped automatically, so the series never grows without bound. 0 keeps everything.
  • TS.RANGE key from to returns samples between two timestamps (- and + mean the ends). AGGREGATION avg 60000 groups them into one-minute buckets; other aggregators include min, max, sum, count, first, last, range, std.p.
  • TS.CREATERULE source dest AGGREGATION avg 3600000 builds a downsampling rule: a second series fills itself with hourly averages, so you keep minute detail for a day and hourly detail for a year (give the destination a longer retention).
  • DUPLICATE_POLICY decides what happens when two samples share a timestamp (BLOCK, FIRST, LAST, MIN, MAX, SUM).
  • Labels let TS.MRANGE and TS.MGET select many series with FILTER.

Use a time series for metrics, sensor readings and prices when you read ranges and aggregates. Use a plain sorted set when you need ranking, and a stream when each entry carries several fields or must be consumed once.

Bloom filters and other probabilistic types

A Bloom filter answers "have I seen this item?" using a small fixed amount of memory. It can say definitely not or probably yes: false positives happen at a rate you choose, but there are never false negatives. That fits checks such as "has this user already seen this article?", "is this username possibly taken?" or "is this URL already crawled?", where an occasional wrong "yes" costs little and storing every item would cost a lot.

Text
BF.RESERVE seen:articles 0.01 1000000   # 1% error rate, sized for 1,000,000 items
BF.ADD seen:articles article:42         # 1 if new, 0 if probably already there
BF.EXISTS seen:articles article:42      # 1 = probably yes, 0 = definitely no
BF.MADD seen:articles a:1 a:2 a:3

The related types follow the same idea of trading exactness for memory, as HyperLogLog does for counting:

Type Question it answers Commands
Bloom filter Is this item in the set? (no deletes) BF.ADD, BF.EXISTS
Cuckoo filter The same, but items can be removed CF.ADD, CF.EXISTS, CF.DEL
Count-Min Sketch About how many times did this item occur? CMS.INCRBY, CMS.QUERY
Top-K Which items are most frequent? TOPK.ADD, TOPK.LIST
t-digest What is the 99th percentile? TDIGEST.ADD, TDIGEST.QUANTILE

The model below stores a time series with retention and one-minute averaging, then builds a small Bloom filter to show false positives (but no false negatives). It is a model, not the real module.

JS TS.RANGE downsampling and a Bloom filter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The filter uses 2,000 bits (250 bytes) for 200 items, and the false-positive percentage you see is the price of that small size. Give a real BF.RESERVE a lower error rate and a bigger capacity and it will allocate more memory, but still far less than storing the items.

Choosing the right tool

  • Look up by key, counters, queues, rankings: plain data types. No modules needed.
  • Nested documents, partial updates: JSON (and index it if you need to query inside).
  • Filter by several fields, text search, aggregates: the query engine with an index.
  • Similar meaning, recommendations, AI caching, retrieval: a vector field, ideally combined with tag or numeric filters in the same query.
  • Heavy relational queries, joins, reporting: keep a real database as the system of record and use Redis search on a copy.

Check your server's version and licence terms for these modules, and test index memory use on realistic data before committing.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does JSON.GET user:1 $.name reply with ["Ana"] instead of "Ana"?

    JSONPath-style queries may match many values, so Redis returns a JSON array of every match, even when there is only one.
  2. 2. Which index field type fits an exact value such as a city or status, matched with @city:{Oslo}?

    TAG fields hold exact values that are matched as whole units. TEXT tokenizes for full-text search and NUMERIC is for ranges.
  3. 3. What data structure idea underlies text and tag indexes?

    An inverted index looks up a term and gets the matching document ids at once. Combined queries intersect or union those sets.
  4. 4. In a semantic cache for an LLM, when should the cached answer be returned?

    The new prompt's embedding is compared with stored ones. If the nearest is close enough, the stored answer is reused; otherwise the model is called and the result stored.
  5. 5. When is a plain set per tag (SADD city:oslo user:1) a better choice than a search index?

    Hand-built indexes from basic types are light and fast for simple lookups. The query engine pays off for combined filters, text and aggregation.

Summary

  • Redis JSON stores nested documents and updates parts of them atomically with $ paths; $ queries reply with arrays of matches.
  • The query engine (FT.CREATE, FT.SEARCH, FT.AGGREGATE) indexes hashes or JSON with TEXT, TAG, NUMERIC, GEO and VECTOR fields and keeps the index current automatically.
  • Vector search returns the k nearest neighbours by COSINE, L2 or IP distance, using FLAT (exact) or HNSW (approximate) indexes.
  • A semantic cache reuses AI answers when a new prompt is close enough in meaning; tune the threshold and set TTLs.
  • Use plain data types when they suffice, and check which modules your Redis version includes.

Next, how Redis keeps data across restarts: Persistence: RDB and AOF.