RedisJSON

JSON support for Redis

Discord Github

The RedisJSON module provides JSON support for Redis. RedisJSON lets you store, update, and retrieve JSON values in a Redis database, similar to any other Redis data type. RedisJSON also works seamlessly with RediSearch to let you index and query JSON documents.

Primary features

  • Full support for the JSON standard
  • A JSONPath syntax for selecting/updating elements inside documents (see JSONPath syntax)
  • Documents stored as binary data in a tree structure, allowing fast access to sub-elements
  • Typed atomic operations for all JSON value types

Use RedisJSON

To learn how to use RedisJSON, it's best to start with the Redis CLI. The following examples assume that you're connected to a Redis server with RedisJSON enabled.

redis-cli examples

First, start redis-cli in interactive mode.

The first RedisJSON command to try is JSON.SET, which sets a Redis key with a JSON value. JSON.SET accepts all JSON value types. This example creates a JSON string:

127.0.0.1:6379> JSON.SET animal $ '"dog"'
"OK"
127.0.0.1:6379> JSON.GET animal $
"[\"dog\"]"
127.0.0.1:6379> JSON.TYPE animal $
1) "string"

Note how the commands include the dollar sign character $. This is the path to the value in the JSON document (in this case it just means the root).

Here are a few more string operations. JSON.STRLEN tells you the length of the string, and you can append another string to it with JSON.STRAPPEND.

127.0.0.1:6379> JSON.STRLEN animal $
1) "3"
127.0.0.1:6379> JSON.STRAPPEND animal $ '" (Canis familiaris)"'
1) "22"
127.0.0.1:6379> JSON.GET animal $
"[\"dog (Canis familiaris)\"]"

Numbers can be incremented and multiplied:

127.0.0.1:6379> JSON.SET num $ 0
OK
127.0.0.1:6379> JSON.NUMINCRBY num $ 1
"[1]"
127.0.0.1:6379> JSON.NUMINCRBY num $ 1.5
"[2.5]"
127.0.0.1:6379> JSON.NUMINCRBY num $ -0.75
"[1.75]"
127.0.0.1:6379> JSON.NUMMULTBY num $ 24
"[42]"

Here's a more interesting example that includes JSON arrays and objects:

127.0.0.1:6379> JSON.SET example $ '[ true, { "answer": 42 }, null ]'
OK
127.0.0.1:6379> JSON.GET example $
"[[true,{\"answer\":42},null]]"
127.0.0.1:6379> JSON.GET example $[1].answer
"[42]"
127.0.0.1:6379> JSON.DEL example $[-1]
(integer) 1
127.0.0.1:6379> JSON.GET example $
"[[true,{\"answer\":42}]]"

The JSON.DEL command deletes any JSON value you specify with the path parameter.

You can manipulate arrays with a dedicated subset of RedisJSON commands:

127.0.0.1:6379> JSON.SET arr $ []
OK
127.0.0.1:6379> JSON.ARRAPPEND arr $ 0
1) (integer) 1
127.0.0.1:6379> JSON.GET arr $
"[[0]]"
127.0.0.1:6379> JSON.ARRINSERT arr $ 0 -2 -1
1) (integer) 3
127.0.0.1:6379> JSON.GET arr $
"[[-2,-1,0]]"
127.0.0.1:6379> JSON.ARRTRIM arr $ 1 1
1) (integer) 1
127.0.0.1:6379> JSON.GET arr $
"[[-1]]"
127.0.0.1:6379> JSON.ARRPOP arr $
1) "-1"
127.0.0.1:6379> JSON.ARRPOP arr $
1) (nil)

JSON objects also have their own commands:

127.0.0.1:6379> JSON.SET obj $ '{"name":"Leonard Cohen","lastSeen":1478476800,"loggedOut": true}'
OK
127.0.0.1:6379> JSON.OBJLEN obj $
1) (integer) 3
127.0.0.1:6379> JSON.OBJKEYS obj $
1) 1) "name"
   2) "lastSeen"
   3) "loggedOut"

To return a JSON response in a more human-readable format, run redis-cli in raw output mode and include formatting keywords such as INDENT, NEWLINE, and SPACE with the JSON.GET command:

$ redis-cli --raw
127.0.0.1:6379> JSON.GET obj INDENT "\t" NEWLINE "\n" SPACE " " $
[
	{
		"name": "Leonard Cohen",
		"lastSeen": 1478476800,
		"loggedOut": true
	}
]

Python example

This code snippet shows how to use RedisJSON with raw Redis commands from Python with redis-py:

import redis

data = {
    'dog': {
        'scientific-name' : 'Canis familiaris'
    }
}

r = redis.Redis()
r.json().set('doc', '$', data)
doc = r.json().get('doc', '$')
dog = r.json().get('doc', '$.dog')
scientific_name = r.json().get('doc', '$..scientific-name')

Build on Ubuntu 20.04

The following packages are required to successfully build RedisJSON on Ubuntu 20.04:

$ sudo apt install build-essential llvm cmake libclang1 libclang-dev cargo

Then, run make or cargo build --release in the repository directory.

Load the module to Redis

Requirements:

To load the RedisJSON module, use one of the following methods:

Configuration file

We recommend you have Redis load the module during startup by adding the following to your redis.conf file:

loadmodule /path/to/module/target/release/librejson.so

On Mac OS, if this module was built as a dynamic library, run:

loadmodule /path/to/module/target/release/librejson.dylib

In the preceding lines, replace /path/to/module/ with the actual path to the module's library.

Command-line option

Alternatively, you can have Redis load the module using the following command-line argument syntax:

$ redis-server --loadmodule ./target/release/librejson.so

MODULE LOAD command

You can also use the MODULE LOAD command to load RedisJSON. Note that MODULE LOAD is a dangerous command and may be blocked/deprecated in the future due to security considerations.

After the module has been loaded successfully, the Redis log should have lines similar to:

...
9:M 11 Aug 2022 16:24:06.701 * <ReJSON> version: 20009 git sha: d8d4b19 branch: HEAD
9:M 11 Aug 2022 16:24:06.701 * <ReJSON> Exported RedisJSON_V1 API
9:M 11 Aug 2022 16:24:06.701 * <ReJSON> Enabled diskless replication
9:M 11 Aug 2022 16:24:06.701 * <ReJSON> Created new data type 'ReJSON-RL'
9:M 11 Aug 2022 16:24:06.701 * Module 'ReJSON' loaded from /opt/redis-stack/lib/rejson.so
...