# Patch Object

Patches a record of a given type by applying only the requested field changes.

Use a Patch Object node in your Flow to apply a partial update to a record of the specified Object Type. The Patch Object node only modifies the specified fields, leaving the rest of the record unchanged.

<figure><img src="https://2803907488-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJF7AoTYz7NHacejws5p9%2Fuploads%2Fgit-blob-768b61bf2fa65af45766556613d060eb62064e5d%2Fimage.png?alt=media" alt="Example of settings for a Create Object node"><figcaption><p>Example of settings for a Create Object node</p></figcaption></figure>

## Config tab

* **Name** - optional display name for the node in the editor
* **Config** - the native-object config used to access your Object Types
* **Type Id** - the Object Type to update, specified using one of several value types:
  * *type* - choose this option for a dropdown that includes the Display Names of the Object Types you have created in your Contextual tenant. If the dropdown appears empty for you, be sure that your Flow has been [initialized with a Config](https://docs.contextual.io/documentation-and-resources/components-and-data/flows/node-red-flow-editor/config), after which the dropdown will be kept in sync with your tenant.
  * *string* - choose the string option and type the Object Type ID directly. Using *type* is recommended when possible.
  * *msg.* - choose this option to read the Object Type ID from the current message, for example `msg.payload.typeId` or `msg.event.typeId`.
  * *env variable* - choose this option to read the Object Type ID from an agent environment variable.
* **Object Id** - the record identifier to patch
* **Input** - the typed-input path to an array of patch operations. In most flows, this comes from `msg` or an environment variable.
* **Concurrency control** - optional optimistic-locking toggle
* **Hash** - the message path that contains the record hash when concurrency control is enabled
* **Output** - the message path that receives the updated record
* **Response** - the message path that receives response metadata

The **Input** value should point to an array of patch operations. Each member of the array should be an object with these properties:

* `op` - the operation, one of `set`, `add`, `remove`, or `increment`
* `path` - the JSON path of the field to update, for example `/foo/bar`
* `value` - the value to set, when applicable

[See below](#patch-operations) for a description of these operations.

When the Patch Object node is included in the path of your flow, it will patch a record and return its updated details, including [\_metaData](https://docs.contextual.io/documentation-and-resources/components-and-data/object-types/object-type-details/data-schema/automatic-metadata), for further use within your flow as desired.

## Concurrency control

The optional **Concurrency control** setting enables optimistic locking by record hash.

When enabled, the node reads a hash value from the configured message path and sends it with the update. If the record has changed since that hash was captured, the patch fails with a `412 Precondition Failed` response instead of applying against a newer version of the record.

The hash you pass here typically comes from a previously retrieved record's `_metaData.hash`.

## Source tab

The **Source** tab controls how the node behaves when it is processing a source stream rather than a single message.

* **Parallelism** can be set to `None`, `Ordered`, or `Unordered`
* `None` processes source items sequentially
* `Ordered` processes source items concurrently up to **Max** while preserving output order
* `Unordered` processes source items concurrently up to **Max** and emits results as they finish

These settings only apply when the node is operating on a source.

### Patch operations

Each patch operation makes a change based on its value for `op`. The below examples show how operations would be applied to a record with this JSON structure:

```json
{
  "name": "Oz",
  "items": ["first", "second"],
  "info": { "valid": true }
}
```

#### Set

A `set` operation (also aliased as `replace`) will add or change the value at the given path. For example, applied to the record above, this operation:

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "op": "set",
  "path": "/name",
  "value": "Yin"
}
</code></pre>

will change the value of "name":

<pre class="language-json" data-full-width="false"><code class="lang-json">{
<strong>  "name": "Yin",
</strong>  "items": ["first", "second"],
  "info": { "valid": true }
}
</code></pre>

Using `set` with a path that doesn't exist adds it:

{% columns %}
{% column %}

```json
{
  "op": "set",
  "path": "/count",
  "value": 4
}
```

{% endcolumn %}

{% column %}

<pre class="language-reason"><code class="lang-reason">{
  "name": "Oz",
  "items": ["first", "second"],
  "info": { "valid": true },
<strong>  "count": 4
</strong>}
</code></pre>

{% endcolumn %}
{% endcolumns %}

To set a value in a nested location, use slashes in the `path`:

{% columns %}
{% column %}

```json
[
  {
    "op": "set",
    "path": "/items/0",
    "value": "1st"
  },
  {
    "op": "set",
    "path": "/info/counts/n",
    "value": 2
  }
]
```

{% endcolumn %}

{% column %}

<pre class="language-reason"><code class="lang-reason">{
  "name": "Oz",
<strong>  "items": ["1st", "second"],
</strong>  "info": {
    "valid": true,
    "counts": {
<strong>      "n": 2
</strong>    }
  }
}
</code></pre>

{% endcolumn %}
{% endcolumns %}

#### Add

An `add` operation works the same as a `set` operation with one exception. With `add` , a value can be appended to an array by adding `"/-"` to the `path` to indicate the end position of the array:

{% columns %}
{% column width="41.66666666666667%" %}

```json
{
  "op": "add",
  "path": "/items/-",
  "value": "third"
}
```

{% endcolumn %}

{% column width="58.33333333333333%" %}

<pre class="language-reason"><code class="lang-reason">{
  "name": "Oz",
<strong>  "items": ["first", "second", "third"],
</strong>  "info": { "valid": true }
}
</code></pre>

{% endcolumn %}
{% endcolumns %}

The only way to insert a value elsewhere into an array is to replace the entire array:

{% columns %}
{% column %}

```json
{
  "op": "add",
  "path": "/items",
  "value": ["0th", "first", "second"]
}
```

{% endcolumn %}

{% column %}

<pre class="language-reason"><code class="lang-reason">{
  "name": "Oz",
<strong>  "items": ["0th", "first", "second"],
</strong>  "info": { "valid": true }
}
</code></pre>

{% endcolumn %}
{% endcolumns %}

> Note: it would be more clear to use `set` or `replace` for modifying an array like this, but this example demonstrates that `add` has the same behavior in this situation.

#### Remove

A `remove` operation deletes the value at `path`:

{% columns %}
{% column %}

```json
{
  "op": "remove",
  "path": "/info"
}
```

{% endcolumn %}

{% column %}

```reason
{
  "name": "Oz",
  "items": ["first", "second"]
}
```

{% endcolumn %}
{% endcolumns %}

If used on an array element, it removes that element from the array:

{% columns %}
{% column %}

```json
{
  "op": "remove",
  "path": "/items/0"
}
```

{% endcolumn %}

{% column %}

<pre class="language-reason"><code class="lang-reason">{
  "name": "Oz",
<strong>  "items": ["second"],
</strong>  "info": { "valid": true }
}
</code></pre>

{% endcolumn %}
{% endcolumns %}

#### Increment

An `increment` operation (also aliased as `incr` ) atomically increases a numeric value by the `value` amount:

{% columns %}
{% column %}

```json
{
  "op": "increment",
  "path": "/count",
  "value": 2
}
```

{% endcolumn %}

{% column %}

<pre class="language-reason"><code class="lang-reason">{
  "name": "Oz",
  "items": ["first", "second"],
  "info": { "valid": true },
<strong>  "count": 6
</strong>}
</code></pre>

{% endcolumn %}
{% endcolumns %}

This can be superior to using `set` to change the value to `6` because if another operation has incremented the value since it was read, it will still be increased by the intended amount.

It cannot be used on values of other types. If there is no value at the path, it acts as a `set`.