patch_array_item

Atomically patch one item of a structured array field by a portable non-null scalar key, instead of read-modify-full-array-write. Requires the active schema to declare that array with merge_array_by_key and the same key_field; missing/mismatched policy fails closed. Loads current state and writes inside one transaction, so concurrent patches to DIFFERENT keys both survive. Pass expected_item_version to detect a same-key race or expected_item_absent for race-safe creation; a conflict returns the current item instead of overwriting.

Name	Required	Description
`item`	Yes	Fields to set on the item identified by `key_value`. Merged onto the existing item (shallow) when the key already exists; `key_field` is always set to `key_value` on the written item regardless of what `item` contains.
`field`	Yes	Name of the array field to patch.
`user_id`	No
`entity_id`	Yes
`key_field`	Yes	Name of the field on each array item that identifies it. Must match the field's declared `merge_array_by_key` `key_field` for the write to be reflected in the snapshot's reducer output.
`key_value`	Yes	Portable non-null JSON scalar identifying the row. Numbers must be finite safe integers. The reducer preserves older rows with non-scalar or unsafe-number keys as unkeyed legacy rows, but new patches cannot create them.
`entity_type`	Yes
`idempotency_key`	Yes
`expected_item_absent`	No	When true, create only if no item with `key_value` exists. Concurrent creators for the same key produce one success and one `409 ERR_ARRAY_ITEM_CONFLICT` with the committed item.
`expected_item_version`	No	Content-hash version of the item as last observed by the caller (returned as `item_version` by a prior patch, or computable client-side as SHA-256 over UTF-8 stable serialization: object keys sort lexicographically, arrays preserve order, and scalar values use JSON spellings). When supplied and stale, the patch is refused with `409 ERR_ARRAY_ITEM_CONFLICT` and nothing is written. Omit to always last-write-win on this one row (still scoped — never touches other keys).

Name

Required

Description

Default

item

Yes

Fields to set on the item identified by `key_value`. Merged onto the existing item (shallow) when the key already exists; `key_field` is always set to `key_value` on the written item regardless of what `item` contains.

field

Yes

Name of the array field to patch.

user_id

entity_id

Yes

key_field

Yes

Name of the field on each array item that identifies it. Must match the field's declared `merge_array_by_key` `key_field` for the write to be reflected in the snapshot's reducer output.

key_value

Yes

Portable non-null JSON scalar identifying the row. Numbers must be finite safe integers. The reducer preserves older rows with non-scalar or unsafe-number keys as unkeyed legacy rows, but new patches cannot create them.

entity_type

Yes

idempotency_key

Yes

expected_item_absent

When true, create only if no item with `key_value` exists. Concurrent creators for the same key produce one success and one `409 ERR_ARRAY_ITEM_CONFLICT` with the committed item.

expected_item_version

Content-hash version of the item as last observed by the caller (returned as `item_version` by a prior patch, or computable client-side as SHA-256 over UTF-8 stable serialization: object keys sort lexicographically, arrays preserve order, and scalar values use JSON spellings). When supplied and stale, the patch is refused with `409 ERR_ARRAY_ITEM_CONFLICT` and nothing is written. Omit to always last-write-win on this one row (still scoped — never touches other keys).

Neotoma

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools