Skip to main content

UpdateRecordArrayItem@2

Node UpdateRecordArrayItem@2 updates several records of one RecordArray in a single pass and writes the modified array once. Use it to store a batch of changes on one entity with one read and one write: group the changes by entity (GroupBy@1), read the entity once, apply all changes of that entity with this node, and write the entity once (ApplyChanges@2).

It is a pure in-memory transformation. UpdateRecordArrayItem@1 changes exactly one record per call; see UpdateRecordArrayItem@1.

Adapter Prerequisites​

  • General availability: Mesh adapters (tenant adapters) support this node type.

Node Configuration​

For fields path, targetPath, targetValueWriteMode, targetValueKind and documentMode, see Overview.

transformations:
- type: UpdateRecordArrayItem@2
path: $.key.Attributes.States # RecordArray of the entity
updatesPath: $.full.key.items # Array of changes; every item addresses one record
matchAttributeName: ExternalId # Record attribute to match
itemMatchValuePath: $.pollUuid # Relative to each change: the value that selects the record
targetPath: $.updates._updatedStates # Where the modified array is written
attributeUpdates:
- attributeName: CurrentValue
valuePath: $.value # Relative to each change
- attributeName: LastUpdate
value: =now()

Parameters​

ParameterTypeRequiredDescription
pathstringYesJSON path to the RecordArray (the records have an Attributes object)
updatesPathstringYesJSON path to the array of changes
matchAttributeNamestringYesName of the record attribute that identifies a record
itemMatchValuePathstringYesPath relative to each change to the value that selects the record
attributeUpdateslistYesAttribute updates applied to every addressed record (see below)
targetPathstringYesJSON path where the modified array is written
targetValueWriteMode, targetValueKind, documentModeNoAs for all target-path nodes

attributeUpdates​

FieldDescription
attributeNameName of the record attribute to set
valuePathPath relative to the change that supplies the value. Takes precedence over value
valueStatic value. =now() sets the current UTC time

Behavior​

  • Every change is matched to a record by comparing the value at itemMatchValuePath with the record attribute matchAttributeName. The comparison is case-insensitive and compares the text of the value, so the number 42 matches the text "42". The attribute key may be stored PascalCase (ExternalId) or camelCase (externalId); existing keys are updated in place, no duplicate key is created.
  • If several records carry the same key, the first one is updated (same as @1).
  • Several changes for the same record are applied in array order: for each attribute the last change wins.
  • Records without a change are copied unchanged; the order of the array is preserved. The source array at path is never modified.
  • Unmatched changes (no record with that key, or no key value) are skipped. The node does not fail; it writes one warning per run with the number of skipped changes (never the values).
  • If no change matched, or updatesPath is empty, nothing is written to targetPath and the pipeline continues (same as @1).
  • If path or updatesPath is not an array, the node logs a warning, writes nothing and the pipeline continues.

Example: Store a Batch of State Changes with One Write per Control​

transformations:
# 1. Group the state changes by control
- type: GroupBy@1
path: $.states
keyPath: $.controlUuid
targetPath: $.groups

- type: ForEach@1
iterationPath: $.groups
targetPath: $.groupResults
mergePath: $.updates
transformations:
# 2. One read per control
- type: GetRtEntitiesByType@1
ckTypeId: Loxone/Control
targetPath: $.updates._controls
fieldFilters:
- attributePath: LoxoneUuid
operator: Equals
comparisonValuePath: $.key.key
- type: ForEach@1
path: $
fullDocumentPath: $.full
iterationPath: $.updates._controls.Items
targetPath: $.updates._controlResults
mergePath: $.updates
transformations:
# 3. All changes of this control in one pass
- type: UpdateRecordArrayItem@2
path: $.key.Attributes.States
updatesPath: $.full.key.items
matchAttributeName: ExternalId
itemMatchValuePath: $.pollUuid
targetPath: $.updates._updatedStates
attributeUpdates:
- attributeName: CurrentValue
valuePath: $.value
- attributeName: LastUpdate
value: =now()
- type: CreateUpdateInfo@1
targetPath: $.updates._controlUpdate
targetValueKind: Array
updateKind: UPDATE
ckTypeIdPath: $.key.CkTypeId.SemanticVersionedFullName
rtIdPath: $.key.RtId
attributeUpdates:
- attributeName: States
attributeValueType: RecordArray
valuePath: $.updates._updatedStates

- type: Flatten@1
path: $.groupResults[*]._controlResults[*]._controlUpdate[*]
targetPath: $._updateItems
targetValueKind: Simple
targetValueWriteMode: Overwrite

# 4. One write: exactly one update per control
- type: ApplyChanges@2
entityUpdatesPath: $._updateItems

Why Not One ApplyChanges per Change?​

ApplyChanges@2 merges several updates of the same entity within one call attribute by attribute, and the later update wins. Every update that was built with UpdateRecordArrayItem@1 carries the whole array with the old values of all other records plus its own single change. When such updates are merged, only the last array survives and the other changes are lost. With UpdateRecordArrayItem@2 the array of an entity contains all its changes, so ApplyChanges@2 receives one update per entity and has nothing to merge.

Concurrency​

This node (like the whole read/modify/write sequence of the pipeline) is not safe against parallel executions: it works on the array it was given and cannot detect that another pipeline execution changed the same entity between your read and your write; the later write replaces the whole array. Two messages for the same entity that run at the same time (for example from FromPipelineDataEvent@1, which delivers messages to several consumers of the same queue in parallel) overwrite each other's changes. @2 removes the lost updates within one batch, not between concurrent executions.

If several executions can change records of the same entity at the same time, do not read and rewrite the array. Use the atomic item update of CreateUpdateInfo@1 (recordArrayItemUpdates): it changes the named members of the matched record in one database statement, without a read, and parallel changes of other records are not lost.