{
  "schema_version": 2,
  "id": "commands/json.merge",
  "title": "JSON.MERGE",
  "url": "https://redis.io/docs/latest/commands/json.merge/",
  "summary": "Merges a given JSON value into matching paths. Consequently, JSON values at matching paths are updated, deleted, or expanded with new children",
  "since": "2.6.0",
  "tags": [
    "docs",
    "develop",
    "stack",
    "oss",
    "rs",
    "rc",
    "oss",
    "kubernetes",
    "clients"
  ],
  "last_updated": "2026-09-18T09:47:58+01:00",
  "page_type": "content",
  "content_hash": "83d830e9137ff577bb607642fafdb4bc803ce5130fec2379b6e6c56e5a5b1a67",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "Merge a given JSON value into matching paths. Consequently, JSON values at matching paths are updated, deleted, or expanded with new children.\n\nThis command complies with [RFC7396](https://datatracker.ietf.org/doc/html/rfc7396) Json Merge Patch\n\n[Examples](#examples)"
    },
    {
      "id": "required-arguments",
      "title": "Required arguments",
      "role": "content",
      "text": "<details open><summary><code>key</code></summary>\n\nis the key to merge into.\n</details>\n\n<details open><summary><code>path</code></summary>\n\nspecifies the JSONPath. For non-existing keys the `path` must be `$`. For existing keys, for each matched `path`, the value that matches the `path` is merged with the JSON `value`. For existing keys, when the path exists, except for the last element, a new child is added with the JSON `value`.\n\n</details>\n\n<details open><summary><code>value</code></summary>\n\nis the JSON value to merge with at the specified path. Merging is done according to the following rules per JSON value in the `value` argument while considering the corresponding original value if it exists:\n*   merging an existing object key with a `null` value deletes the key\n*   merging an existing object key with non-null value updates the value\n*   merging a non-existing object key adds the key and value\n*   merging an existing array with any merged value, replaces the entire array with the value\n</details>"
    },
    {
      "id": "examples",
      "title": "Examples",
      "role": "example",
      "text": "JSON.MERGE provides four different behaviors to merge changes on a given key: create a non-existent path, update an existing path with a new value, delete an existing path, or replace an array with a new array\n\n<details open>\n<summary><b>Create a non-existent path-value</b></summary>\n\n\nredis> JSON.SET doc $ '{\"a\":2}'\nOK\nredis> JSON.MERGE doc $.b '8'\nOK\nredis> JSON.GET doc $\n\"[{\\\"a\\\":2,\\\"b\\\":8}]\"\n\n\n</details>\n\n<details open>\n<summary><b>Replace an existing value</b></summary>\n\n\nredis> JSON.SET doc $ '{\"a\":2}'\nOK\nredis> JSON.MERGE doc $.a '3'\nOK\nredis> JSON.GET doc $\n\"[{\\\"a\\\":3}]\"\n\n\n</details>\n\n<details open>\n<summary><b>Delete an existing value</b></summary>\n\n\nredis> JSON.SET doc $ '{\"a\":2}'\nOK\nredis> JSON.MERGE doc $ '{\"a\":null}'\nOK\nredis> JSON.GET doc $\n\"[{}]\"\n\n\n</details>\n\n<details open>\n<summary><b>Replace an Array</b></summary>\n\n\nredis> JSON.SET doc $ '{\"a\":[2,4,6,8]}'\nOK\nredis> JSON.MERGE doc $.a '[10,12]'\nOK\nredis> JSON.GET doc $\n\"[{\\\"a\\\":[10,12]}]\"\n\n\n</details>\n\n<details open>\n<summary><b>Merge changes in multi-paths</b></summary>\n\n\nredis> JSON.SET doc $ '{\"f1\": {\"a\":1}, \"f2\":{\"a\":2}}'\nOK\nredis> JSON.GET doc\n\"{\\\"f1\\\":{\\\"a\\\":1},\\\"f2\\\":{\\\"a\\\":2}}\"\nredis> JSON.MERGE doc $ '{\"f1\": null, \"f2\":{\"a\":3, \"b\":4}, \"f3\":[2,4,6]}'\nOK\nredis> JSON.GET doc\n\"{\\\"f2\\\":{\\\"a\\\":3,\\\"b\\\":4},\\\"f3\\\":[2,4,6]}\"\n\n\n</details>"
    },
    {
      "id": "redis-software-and-redis-cloud-compatibility",
      "title": "Redis Software and Redis Cloud compatibility",
      "role": "content",
      "text": "| Redis<br />Software | Redis<br />Cloud | <span style=\"min-width: 9em; display: table-cell\">Notes</span> |\n|:----------------------|:-----------------|:------|\n| <span title=\"Supported\">&#x2705; Standard</span><br /><span title=\"Supported\"><nobr>&#x2705; Active-Active</nobr></span> | <span title=\"Supported\">&#x2705; Standard</span><br /><span title=\"Supported\"><nobr>&#x2705; Active-Active</nobr></span> |  |"
    },
    {
      "id": "return-information",
      "title": "Return information",
      "role": "returns",
      "text": "**RESP2:**\n\nOne of the following:\n* [Simple string reply](https://redis.io/docs/latest/develop/reference/protocol-spec#simple-strings): `OK` if executed correctly.\n* [Simple error reply](https://redis.io/docs/latest/develop/reference/protocol-spec#simple-errors): if the operation fails to set the new values.\n\n**RESP3:**\n\nOne of the following:\n* [Simple string reply](https://redis.io/docs/latest/develop/reference/protocol-spec#simple-strings): `OK` if executed correctly.\n* [Simple error reply](https://redis.io/docs/latest/develop/reference/protocol-spec#simple-errors): if the operation fails to set the new values."
    },
    {
      "id": "see-also",
      "title": "See also",
      "role": "related",
      "text": "[`JSON.GET`](https://redis.io/docs/latest/commands/json.get) | [`JSON.MGET`](https://redis.io/docs/latest/commands/json.mget) | [`JSON.SET`](https://redis.io/docs/latest/commands/json.set) | [`JSON.MSET`](https://redis.io/docs/latest/commands/json.mset)"
    },
    {
      "id": "related-topics",
      "title": "Related topics",
      "role": "related",
      "text": "* [RedisJSON](https://redis.io/docs/latest/develop/data-types/json)\n* [Index and search JSON documents](https://redis.io/docs/latest/develop/ai/search-and-query/indexing)"
    }
  ],
  "examples": []
}