JSON.SET

Syntax text Syntax diagram API methods

JSON.SET key path value [NX | XX]

Client:

set(
    name: str,
    path: str,
    obj: JsonType,
    nx: Optional[bool] = False,
    xx: Optional[bool] = False,
    decode_keys: Optional[bool] = False
) → Optional[str]

jsonset(
    *args: Any,
    **kwargs: Any
) → Any

SET(
    key: RedisArgument,
    path: RedisArgument,
    json: RedisJSON,
    options?: JsonSetOptions
) → Any

jsonSet(
    key: Any,
    Path.ROOT_PATH: Any,
    pojo: Any
) → return

jsonSet(
    key: Any,
    Path.ROOT_PATH: Any,
    pojo: Any,
    params: Any
) → return

jsonSet(
    key: String,
    path: Path,
    pojo: Object
) → String

jsonSet(
    key: String,
    path: Path,
    pojo: Object,
    params: JsonSetParams
) → String

jsonSet(
    key: String,
    object: Object
) → default String

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    value: JsonValue,
    options: JsonSetArgs  // the JsonSetArgs the options for setting the value.
) → String  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    value: JsonValue
) → String  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    jsonString: String  // the JSON string to set.
) → String  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    jsonString: String,  // the JSON string to set.
    options: JsonSetArgs  // the JsonSetArgs the options for setting the value.
) → String  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    value: JsonValue,
    options: JsonSetArgs  // the JsonSetArgs the options for setting the value.
) → RedisFuture<String>  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    value: JsonValue
) → RedisFuture<String>  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    jsonString: String  // the JSON string to set.
) → RedisFuture<String>  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    jsonString: String,  // the JSON string to set.
    options: JsonSetArgs  // the JsonSetArgs the options for setting the value.
) → RedisFuture<String>  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    value: JsonValue,
    options: JsonSetArgs  // the JsonSetArgs the options for setting the value.
) → Mono<String>  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    value: JsonValue
) → Mono<String>  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    jsonString: String  // the JSON string to set.
) → Mono<String>  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

jsonSet(
    key: K,  // the key holding the JSON document.
    jsonPath: JsonPath,  // the JsonPath pointing to the value(s) where we want to set the value.
    jsonString: String,  // the JSON string to set.
    options: JsonSetArgs  // the JsonSetArgs the options for setting the value.
) → Mono<String>  // String "OK" if the set was successful, null if the JsonSetArgs conditions are not met. @since 6.8

JSONSet(
    ctx: context.Context,
    key: Any,
    path: string,
    value: interface{}
) → *StatusCmd

Set(
    key: Any,
    path: Any,
    json: Any,
    when: Any
) → return

Set(
    key: RedisKey,
    path: RedisValue,
    json: RedisValue,
    when: When
) → bool

Set(
    key: Any,
    path: Any,
    fileContent: Any,
    when: Any
) → return

jsonset(
    $key: string,
    $path: string,
    $value: string,
    ?string $subcommand = null: Any
) → string

Available in:: Redis Open Source / JSON 1.0.0
Time complexity:: O(M+N) when path is evaluated to a single value where M is the size of the original value (if it exists) and N is the size of the new value, O(M+N) when path is evaluated to multiple values where M is the size of the key and N is the size of the new value * the number of original values in the key
ACL categories:: @json, @write, @slow,
Compatibility:: Redis Software and Redis Cloud compatibility

Set or replace the value at each location resolved by path.

If the key does not exist, a new JSON document can be created only by setting the root path ($ or .).

JSON.SET can also create new object members when the parent object exists.

Examples

Required arguments

key

is a new key to create or an existing JSON key to modify.

path

A JSONPath expression that resolves to zero or more locations within the JSON document.

The root of the document is specified as $ or ..
If path resolves to one or more existing locations, the value at each matched location is replaced with value.
If the final token of path is a non-existing object member and the parent location exists and is an object, the member is created and set to value.
If any intermediate path element does not exist, the path cannot be created, and the command returns nil.

Optional arguments NX and XX modify this behavior for both new keys and existing JSON keys.

value

A valid JSON value to set at the specified path.

The value can be a scalar (string, number, boolean, or null) or a compound value such as an object or array.

Optional arguments

NX

Sets the value only if path has no matches.

XX

Sets the value only if path has one or more matches.

Examples

Replace an existing value

redis> JSON.SET doc $ '{"a":2}'
OK
redis> JSON.SET doc $.a '3'
OK
redis> JSON.GET doc $
"[{\"a\":3}]"

Add a new value

redis> JSON.SET doc $ '{"a":2}'
OK
redis> JSON.SET doc $.b '8'
OK
redis> JSON.GET doc $
"[{\"a\":2,\"b\":8}]"

Update multiple matches

redis> JSON.SET doc $ '{"f1": {"a":1}, "f2":{"a":2}}'
OK
redis> JSON.SET doc $..a 3
OK
redis> JSON.GET doc
"{\"f1\":{\"a\":3},\"f2\":{\"a\":3}}"

path does not exist and cannot be created

redis> JSON.SET doc $ 1
OK
redis> JSON.SET doc $.x.y 2
(nil)

XX condition unmet

redis> JSON.SET nonexistentkey $ 5 XX
(nil)
redis> JSON.GET nonexistentkey
(nil)

key does not exist and path is not root

redis> JSON.SET nonexistentkey $.x 5
(error) ERR new objects must be created at the root

Redis Software and Redis Cloud compatibility

Redis Software	Redis Cloud	Notes
✅ Supported	✅ Flexible & Annual ✅ Free & Fixed

Return information

RESP2 RESP3

One of the following:

Simple string reply: OK if executed correctly.
Null reply: if key exists but path does not exist and cannot be created, or if an NX or XX condition is unmet.
Simple error reply: (error) expected ... - if the value is invalid.
Simple error reply: (error) Error occurred on position ... expected ... - if the path is invalid.
Simple error reply: (error) ERR new objects must be created at the root - if key does not exist and path is not root ($ or .).
Simple error reply: (error) ERR wrong static path - if a dynamic path expression has no matching locations.
Simple error reply: (error) ERR index out of bounds - if the path refers to an array index outside the array bounds.

One of the following:

Simple string reply: OK if executed correctly.
Null reply: if key exists but path does not exist and cannot be created, or if an NX or XX condition is unmet.
Simple error reply: (error) expected ... - if the value is invalid.
Simple error reply: (error) Error occurred on position ... expected ... - if the path is invalid.
Simple error reply: (error) ERR new objects must be created at the root - if key does not exist and path is not root ($ or .).
Simple error reply: (error) ERR wrong static path - if a dynamic path expression has no matching locations.
Simple error reply: (error) ERR index out of bounds - if the path refers to an array index outside the array bounds.

Products

Tools

Get Redis

Connect

Learn

Latest

See how it works

JSON.SET

Required arguments

Optional arguments

Examples

Redis Software and Redis Cloud compatibility

Return information

See also

JSON.SET

Required arguments

Optional arguments

Examples

Redis Software and Redis Cloud compatibility

Return information

See also

Related topics