ContextQMD
Back to Redis

JSON.SET

content/commands/json.set.md

latest6.0 KB
Original Source

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

<details open><summary><code>key</code></summary>

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

</details> <details open><summary><code>path</code></summary>

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.

</details> <details open><summary><code>value</code></summary>

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.

</details>

Optional arguments

<details open><summary><code>NX</code></summary>

Sets the value only if path has no matches.

</details> <details open><summary><code>XX</code></summary>

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

</details>

Examples

<details open> <summary><b>Replace an existing value</b></summary>

{{< highlight bash >}} redis> JSON.SET doc $ '{"a":2}' OK redis> JSON.SET doc $.a '3' OK redis> JSON.GET doc $ "[{"a":3}]" {{< / highlight >}}

</details> <details open> <summary><b>Add a new value</b></summary>

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

</details> <details open> <summary><b>Update multiple matches</b></summary>

{{< highlight bash >}} 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}}" {{< / highlight >}}

</details> <details open> <summary><b>path does not exist and cannot be created</b></summary>

{{< highlight bash >}} redis> JSON.SET doc $ 1 OK redis> JSON.SET doc $.x.y 2 (nil) {{< / highlight >}}

</details> <details open> <summary><b>XX condition unmet</b></summary>

{{< highlight bash >}} redis> JSON.SET nonexistentkey $ 5 XX (nil) redis> JSON.GET nonexistentkey (nil) {{< / highlight >}}

</details> <details open> <summary><b>key does not exist and path is not root</b></summary>

{{< highlight bash >}} redis> JSON.SET nonexistentkey $.x 5 (error) ERR new objects must be created at the root {{< / highlight >}}

</details>

Redis Software and Redis Cloud compatibility

| Redis Software | Redis Cloud | <span style="min-width: 9em; display: table-cell">Notes</span> | |:----------------------|:-----------------|:------| | <span title="Supported">✅ Supported</span> | <span title="Supported">✅ Flexible & Annual</span> <span title="Supported">✅ Free & Fixed</nobr></span> | |

Return information

{{< multitabs id="json-set-return-info" tab1="RESP2" tab2="RESP3" >}}

One of the following:

  • [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): OK if executed correctly.
  • [Null reply]({{< relref "/develop/reference/protocol-spec#nulls" >}}): if key exists but path does not exist and cannot be created, or if an NX or XX condition is unmet.
  • [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): (error) expected ... - if the value is invalid.
  • [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): (error) Error occurred on position ... expected ... - if the path is invalid.
  • [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): (error) ERR new objects must be created at the root - if key does not exist and path is not root ($ or .).
  • [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): (error) ERR wrong static path - if a dynamic path expression has no matching locations.
  • [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): (error) ERR index out of bounds - if the path refers to an array index outside the array bounds.

-tab-sep-

One of the following:

  • [Simple string reply]({{< relref "/develop/reference/protocol-spec#simple-strings" >}}): OK if executed correctly.
  • [Null reply]({{< relref "/develop/reference/protocol-spec#nulls" >}}): if key exists but path does not exist and cannot be created, or if an NX or XX condition is unmet.
  • [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): (error) expected ... - if the value is invalid.
  • [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): (error) Error occurred on position ... expected ... - if the path is invalid.
  • [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): (error) ERR new objects must be created at the root - if key does not exist and path is not root ($ or .).
  • [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): (error) ERR wrong static path - if a dynamic path expression has no matching locations.
  • [Simple error reply]({{< relref "/develop/reference/protocol-spec#simple-errors" >}}): (error) ERR index out of bounds - if the path refers to an array index outside the array bounds. {{< /multitabs >}}

See also

[JSON.GET]({{< relref "commands/json.get/" >}}) | [JSON.MGET]({{< relref "commands/json.mget/" >}})

  • [RedisJSON]({{< relref "/develop/data-types/json/" >}})
  • [Index and search JSON documents]({{< relref "/develop/ai/search-and-query/indexing/" >}})