> For the complete documentation index, see [llms.txt](https://old-docs.clarifai.com/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://old-docs.clarifai.com/guide/v6.9/api-guide/api-overview/patching.md).

# Patching

We designed PATCH to work over multiple resources at the same time (bulk) and be flexible enough for all your needs to minimize round trips to the server. Therefore it might seem a little different to any PATCH you've seen before, but it's not complicated. All three actions that are supported do overwrite by default, but have special behaviour for lists of objects (for example lists of concepts).

## Merge

`merge` action will overwrite a key:value with key:new\_value or append to an existing list of values, merging dictionaries that match by a corresponding `id` field.

In the following examples A is being patched into B to create the Result:

```
*Merges different key:values*
A = `{"a":[1,2,3]}`
B = `{"blah":true}`
Result = `{"blah":true, "a":[1,2,3]}`

*For id lists, merge will append*
A = `{"a":[{"id": 1}]}`
B = `{"a":[{"id": 2}]}`
Result = `{"a":[{"id": 2}, {"id":1}]}`

*Simple merge of key:values and within a list*
A = `{"a":[{"id": "1", "other":true}], "blah":1}`
B = `{"a":[{"id": "2"},{"id":"1", "other":false}]}`
Result = `{"a":[{"id": "2"},{"id": "1"}], "blah":1}`

*Different types should overwrite fine*
A = `{"a":[{"id": "1"}], "blah":1}`
B = `{"a":[{"id": "2"}], "blah":"string"}`
Result = `{"a":[{"id": "2"},{"id": "1"}], "blah":1}`

*Deep merge, notice the "id":"1" matches, so those dicts are merged in the list*
A = `{"a":[{"id": "1","hey":true}], "blah":1}`
B = `{"a":[{"id": "1","foo":"bar","hey":false},{"id":"2"}], "blah":"string"}`
Result = `{"a":[{"hey":true,"id": "1","foo":"bar"},{"id":"2"}], "blah":1}`

*For non-id lists, merge will append*
A = `{"a":[{"blah": "1"}], "blah":1}`
B = `{"a":[{"blah": "2"}], "blah":"string"}`
Result = `{"a":[{"blah": "2"}, {"blah":"1"}], "blah":1}`

*For non-id lists, merge will append*
A = `{"a":[{"blah": "1"}], "blah":1, "dict":{"a":1,"b":2}}`
B = `{"a":[{"blah": "2"}], "blah":"string"}`
Result = `{"a":[{"blah": "2"}, {"blah":"1"}], "blah":1, "dict":{"a":1,"b":2}}`

*Simple overwrite root element*
A = `{"key1":true}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{"key1":true}`

*Overwrite a sub element*
A = `{"key1":{"key2":true}}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{"key1":{"key2":true, "key3":"value3"}}`

*Merge a sub element*
A = `{"key1":{"key2":{"key4":"value4"}}}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{"key1":{"key2":{"key4":"value4"}, "key3":"value3"}}`

*Merge multiple trees*
A = `{"key1":{"key2":{"key9":"value9"}, "key3":{"key4":"value4", "key10":[1,2,3]}}, "key6":{"key11":"value11"}}`
B = `{"key1":{"key2":"value2", "key3":{"key4":{"key5":"value5"}}}, "key6":{"key7":{"key8":"value8"}}}`
Result = `{"key1":{"key2":{"key9":"value9"}, "key3":{"key4":"value4", "key10":[1,2,3]}}, "key6":{"key7":{"key8":"value8"}, "key11":"value11"}}`

*Merge {} element will replace*
A = `{"key1":{"key2":{}}}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{"key1":{"key2":{}, "key3":"value3"}}`

*Merge a null element does nothing*
A = `{"key1":{"key2":null}}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{"key1":{"key2":"value2", "key3":"value3"}}`

*Merge a blank list [] will replace root element*
A = `{"key1":[]}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{"key1":[]}`

*Merge a blank list [] will replace single element*
A = `{"key1":{"key2":[]}}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{"key1":{"key2":[], "key3":"value3"}}`

*Merge a blank list [] will remove nested objects*
A = `{"key1":{"key2":[{"key3":"value3"}]}}`
B = `{"key1":{"key2":{"key3":"value3"}}}`
Result = `{"key1":{"key2":[{"key3":"value3"}]}}`

*Merge an existing list with some other struct*
A = `{"key1":{"key2":{"key3":[{"key4":"value4"}]}}}`
B = `{"key1":{"key2":[]}}`
Result = `{"key1":{"key2":{"key3":[{"key4":"value4"}]}}}`
```

## Remove

`remove` action will overwrite a key:value with key:new\_value or delete anything in a list that matches the provided values' ids.

In the following examples A is being patched into B to create the Result:

```
*Remove from list*
A = `{"a":[{"id": "1"}], "blah":1}`
B = `{"a":[{"id": "2"},{"id": "3"}, {"id":"1"}], "blah":"string"}`
Result = `{"a":[{"id": "2"},{"id":"3"}], "blah":1}`

*For non-id lists, remove will append*
A = `{"a":[{"blah": "1"}], "blah":1}`
B = `{"a":[{"blah": "2"}], "blah":"string"}`
Result = `{"a":[{"blah": "2"}, {"blah":"1"}], "blah":1}`

*Empty out a nested dictionary*
A = `{"key1":{"key2":true}}`
B = `{"key1":{"key2":"value2"}}`
Result = `{"key1":{}}`

*Remove the root element, should be empty*
A = `{"key1":true}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{}`

*Remove a sub element*
A = `{"key1":{"key2":true}}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{"key1":{"key3":"value3"}}`

*Remove a multiple sub elements*
A = `{"key1":{"key2":{"key3":true}, "key4":true}}`
B = `{"key1":{"key2":{"key3":{"key5":"value5"}}, "key4":{"key6":{"key7":"value7"}}}}`
Result = `{"key1":{"key2":{}}}`

*Remove one of the root elements if there are more than one*
A = `{"key1":true}`
B = `{"key1":{"key2":"value2", "key3":"value3"}, "key4":["a", "b", "c"]}`
Result = `{"key4":["a", "b", "c"]}`

*Remove with false should over write*
A = `{"key1":{"key2":false, "key3":true}, "key4":false}`
B = `{"key1":{"key2":"value2", "key3":"value3"}, "key4":[{"key5":"value5", "key6":"value6"}, {"key7": "value7"}]}`
Result = `{"key1":{"key2":false}, "key4":false}`

*Only objects with id's can be put into lists*
A = `{"key1":[{"key2":true}]}`
B = `{"key1":[{"key2":"value2"}, {"key3":"value3"}]}`
Result = `{}`

*Elements with {} should do nothing*
A = `{"key1":{}}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{"key1":{"key2":"value2", "key3":"value3"}}`

*Elements with nil should do nothing*
A = `{"key1":{"key2":null}}`
B = `{"key1":{"key2":"value2", "key3":"value3"}}`
Result = `{"key1":{"key2":"value2", "key3":"value3"}}`
```

## Overwrite

The `overwrite` action will overwrite the old object with the new object. If you want to change a field or sub-object with the `overwrite` action, it is suggested to first call `Get` to obtain the original object. Then you can change the field or sub-object you would like to overwrite, followed by assembling the `overwrite` request with the entire object.

In the following examples A is being patched into B to create the Result:

```
A = `{"a":[{"id": "1"}], "blah":1}`
B = `{"a":[{"id": "2"}], "blah":"string", "foo": "bar}`
Result = `{"a":[{"id": "1"}], "blah":1}`

A = `{}`
B = `{"a":[{"blah": "2"}], "blah":"string"}`
Result = `{}`
```

*Patch inputs with overwrite action will overwrite data object*

```
*Before Patch*
"input": {
    "id": "68be8de5a7de42c4873bf63fb6b8683d",
    "data": {
        "image": {
            "url": "https://samples.clarifai.com/your-image.jpg",
        },
        "concepts": [
            {
                "id": "car",
                "name": "car",
                "value": 1,
                "app_id": "your-application-id"
            }
        ],
        "geo": {
            "geo_point": {
                "longitude": 40.7129,
                "latitude": 74.0058
            }
        }
    },
}

*Patch Request*
{
    "inputs": [
        {
            "id": "68be8de5a7de42c4873bf63fb6b8683d",
            "data": {
                "concepts": [
                    {
                        "id": "ferrari",
                        "value": 1.0
                    }
                ],
                "metadata": {
                    "foo": "bar"
                }
            }
        }
    ],
    "action": "overwrite"
}

*Result*
"input": {
    "id": "68be8de5a7de42c4873bf63fb6b8683d",
    "data": {
        "image": {
            "url": "https://samples.clarifai.com/your-image.jpg",
        },
        "concepts": [
            {
                "id": "ferrari",
                "name": "ferrari",
                "value": ,
                "app_id": "your-application-id"
            }
        ],
        "metadata": {
            "foo": "bar"
        }
    },
}
```

*Patch models with overwrite action will overwrite output\_info and name*

```
*Before Patch*
"model": {
    "id": "test-model-1580486147",
    "name": "test-model-1580486147",
    "app_id": "test-app-1580486122",
    "output_info": {
        "data": {
            "concepts": [
                {
                    "id": "car",
                    "name": "car",
                    "value": 1,
                    "language": "en",
                    "app_id": "test-app-1580486122"
                },
                {
                    "id": "ferrari",
                    "name": "ferrari",
                    "value": 1,
                    "language": "en",
                    "app_id": "test-app-1580486122"
                }
            ]
        },
        "output_config": {
            "concepts_mutually_exclusive": false,
            "closed_environment": false,
            "max_concepts": 0,
            "min_value": 0,
            "test_split_percent": 10,
            "embed_model_version_id": "bb186755eda04f9cbb6fe32e816be104",
            "invalid_data_tolerance_percent": 5
        },
        "type": "concept",
        "type_ext": "concept"
    }
}

*Patch Request*
{
    "models": [
        {
            "id": "test-model-1580486147",
            "name": "my-new-model",
            "output_info": {
                "data": {
                    "concepts": [
                        {
                            "id": "animal"
                        },
                        {
                            "id": "dog"
                        },
                        {
                            "id": "cat"
                        }
                    ]
                },
                "output_config": {
                    "concepts_mutually_exclusive": true
                }
            }
        }
    ],
    "action": "overwrite"
}

*Result*
"model": {
    "id": "test-model-1580486147",
    "name": "my-new-model",
    "app_id": "test-app-1580486122",
    "output_info": {
        "data": {
            "concepts": [
                {
                    "id": "animal",
                    "name": "animal",
                    "value": 1,
                    "language": "en",
                    "app_id": "test-app-1580486122"
                },
                {
                    "id": "cat",
                    "name": "cat",
                    "value": 1,
                    "language": "en",
                    "app_id": "test-app-1580486122"
                },
                {
                    "id": "dog",
                    "name": "dog",
                    "value": 1,
                    "language": "en",
                    "app_id": "test-app-1580486122"
                }
            ]
        },
        "output_config": {
            "concepts_mutually_exclusive": true,
            "closed_environment": false,
            "max_concepts": 0,
            "min_value": 0,
            "test_split_percent": 10,
            "embed_model_version_id": "bb186755eda04f9cbb6fe32e816be104",
            "invalid_data_tolerance_percent": 5
        },
        "type": "concept",
        "type_ext": "concept"
    }
}
```