In Redis 8, what is the JSON data type, and which commands create a document and read it back?
answer
- more than text under a key
- parsed, stored as a tree
- new keys start at the root
- one write command, two read commands
- packaging changed at 8.0
basics
~20 sThe Redis JSON type stores a parsed document as a binary tree under one key, part of Redis Open Source since 8.0. JSON.SET creates or changes it, JSON.GET reads any path, and JSON.MGET reads one path across keys.
solid answer
~40 sThe JSON type keeps a document as a binary tree of typed values under one key, not as text, so Redis can reach inside it. `JSON.SET key $ '{...}'` creates the document, and a new key can only be created at the root, `$` or `.`. On an existing document the same command replaces whatever the path matches, or adds a member when the parent object exists. `NX` writes only when the path has no match and `XX` only when it has one, and an unmet condition returns nil. `JSON.GET key $.items` returns just that part as JSON text, and `JSON.MGET k1 k2 $.total` reads one path from several keys. Since Redis 8.0 the type is part of Redis Open Source, though a core-only source build does not have it.
code
plaintext · 7 lines> JSON.SET cart:42 $ '{"currency":"EUR","items":[{"sku":"A1","qty":2}]}' NX
OK
> JSON.GET cart:42 $.currency
"[\"EUR\"]"
> JSON.MGET cart:42 cart:43 $.currency
1) "[\"EUR\"]"
2) (nil)go deeper
Recall the three commands and the root rule: JSON.SET creates at the root, JSON.GET reads a path, JSON.MGET reads one path across keys. Say that the type stores a parsed tree, not text.
Explain what NX and XX look at, and which outcomes are nil rather than errors. Show you know that a dollar-sign path wraps its reply in an array even for a single match.
Check that the servers really have the type before depending on it: a core-only source build does not, and a client that treats nil as success will hide writes that never happened.
Treat the packaging change as a fleet question: moving to Redis 8 removes a separate module to manage, and it also changes the build and configuration you standardise on.
## What the JSON type is Redis has a dedicated **JSON** data type. A key holds a whole JSON document: an object, an array, or even a single scalar such as a number or a string. Redis does not keep the text it received. It parses the text and stores the values as **binary data in a tree structure**, which is what lets a command address one member or one array element without touching the rest. That makes it a different thing from a JSON string stored with `SET`. To `GET` and `SET`, a serialized string is only bytes. - A JSON key has its own type. `GET` on it fails with `WRONGTYPE`, and `JSON.GET` on a plain string key fails too. - Every JSON command can take a **path** saying which part of the document it means. `$` is the root. - Key-level commands such as `DEL` and `EXPIRE` work on the whole key, as with any other type. ## Creating and changing a document with JSON.SET ```text > JSON.SET cart:42 $ '{"currency":"EUR","items":[{"sku":"A1","qty":2}]}' OK > JSON.SET cart:42 $.coupon '"SPRING"' OK ``` The value must be valid JSON, so a string needs its own double quotes inside the shell's single quotes. `JSON.SET` then follows four rules: 1. A **new key** can only be created at the root. Any other path fails with `ERR new objects must be created at the root`. 2. When the path **matches** existing locations, the value at every match is replaced. 3. When only the **last token** is missing and its parent is an object, the member is created. 4. When an **intermediate** element is missing, nothing can be created and the command returns nil. Two options make the write conditional. They look at the path, and at the root that means whether the key exists: | Call | Situation | Reply | |---|---|---| | `JSON.SET k $ '{}' NX` | key `k` already exists | nil | | `JSON.SET k $ '{}' XX` | key `k` does not exist | nil | | `JSON.SET k $.a 1 NX` | member `a` already exists | nil | | `JSON.SET k $.a 1 XX` | member `a` already exists | `OK` | Nil is not an error, so code that only checks for errors will miss a write that did not happen. ## Reading with JSON.GET and JSON.MGET `JSON.GET` returns the value at a path as JSON text, and the reply carries only that part of the document. ```text > JSON.GET cart:42 $.items[0].sku "[\"A1\"]" > JSON.GET cart:42 $.currency $.coupon "{\"$.currency\":[\"EUR\"],\"$.coupon\":[\"SPRING\"]}" ``` - A `$` path wraps its result in an array, even for one match. - Several paths return one object with a member per path. The order of its keys is not guaranteed. - `JSON.GET` on a missing key returns nil. `JSON.MGET` takes several keys and **one** path, and returns one element per key, with nil for a key that does not exist. On Redis Cluster all those keys must be in the same hash slot. ## The rest of the command family The type has its own commands for changing part of a document in place, and each takes a path as well: - `JSON.NUMINCRBY` adds to a number. - `JSON.ARRAPPEND` adds to the end of an array. - `JSON.DEL` removes the value at a path, and removes the whole key when the path is the root. - `JSON.TYPE` reports what kind of value sits at a path. These are the reason to choose the type over a string at all, since string commands work on bytes and cannot address a member inside a document. ## Where the type comes from JSON used to be a separate module, RedisJSON, installed on its own or through Redis Stack. **Redis 8.0** (May 2025) made it part of Redis Open Source, and the release notes say the stand-alone module is no longer needed. Packaging still matters when you build from source: - A **release tarball** carries the module settings in its `redis.conf` and runs as it is. - A **git checkout** needs `make modules-update` before the build, then `./src/redis-server redis-full.conf`. - `make build redis` builds the core data structures only, so the JSON commands do not exist on that server. ## One limit to remember A JSON value passed to a command can nest up to **128** levels. A value nested 129 levels deep is rejected with a recursion limit error. Normal application documents are nowhere near this, so it usually means runaway or recursive data.
- What happens if you run `JSON.SET cart:42 $.shipping.city '"Oslo"'` when `shipping` does not exist?The command returns nil and changes nothing. `JSON.SET` can create only the final member of a path, and only when its parent already exists and is an object. Here the intermediate `shipping` is missing. Write `$.shipping` with the whole object first, then the nested member can be set. If the key itself did not exist, the same call would be an error, because new documents start at the root.
- A service has a plain string under `cart:42` and now runs `JSON.SET cart:42 $ '{}'`. What happens?It fails with `WRONGTYPE`, because a JSON command will not open a key holding another type. The reverse is not symmetrical: plain `SET` overwrites a key whatever its type, so an old writer can silently replace a JSON document with a string. Migrate under new key names, or delete the old key first.
- How deep can a document nest in the Redis JSON type?A value passed to a command can have a depth of up to 128, and a value nested 129 levels deep is rejected with a recursion limit error. The check also counts where you write: setting a value at a deep path adds that path's depth to the value's own, so a value that would be fine at the root can be refused further down.
- The JSON type just stores the JSON text and reparses it on every read.
- JSON.SET with any path will create the key if it is missing.
- An unmet NX or XX condition on JSON.SET returns an error.
- You still have to install Redis Stack to get JSON on Redis 8.
- Plain GET works on a JSON key and returns the document text.
Assumes Redis 8.10; the JSON type has been part of Redis Open Source since 8.0, and older servers need the stand-alone module.