UpdateRecordArrayItem@2
Der Node UpdateRecordArrayItem@2 aktualisiert mehrere Records eines RecordArrays in einem Durchlauf und schreibt das geänderte Array einmal. Damit lässt sich ein Batch von Änderungen an einer Entität mit einem Lese- und einem Schreibzugriff speichern: Änderungen nach Entität gruppieren (GroupBy@1), die Entität einmal lesen, alle Änderungen dieser Entität mit diesem Node anwenden und die Entität einmal schreiben (ApplyChanges@2).
Der Node ist eine reine In-Memory-Transformation. UpdateRecordArrayItem@1 ändert pro Aufruf genau einen Record, siehe UpdateRecordArrayItem@1.
Adapter-Voraussetzungen
- Allgemeine Verfügbarkeit: Mesh-Adapter (Mandanten-Adapter) unterstützen diesen Node-Typ.
Node-Konfiguration
Für die Felder path, targetPath, targetValueWriteMode, targetValueKind und documentMode siehe Überblick.
transformations:
- type: UpdateRecordArrayItem@2
path: $.key.Attributes.States # RecordArray der Entität
updatesPath: $.full.key.items # Array der Änderungen; jedes Element adressiert einen Record
matchAttributeName: ExternalId # Record-Attribut, über das zugeordnet wird
itemMatchValuePath: $.pollUuid # Relativ zur Änderung: der Wert, der den Record auswählt
targetPath: $.updates._updatedStates # Ziel des geänderten Arrays
attributeUpdates:
- attributeName: CurrentValue
valuePath: $.value # Relativ zur Änderung
- attributeName: LastUpdate
value: =now()
Parameter
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
path | string | Ja | JSON-Pfad zum RecordArray (die Records haben ein Attributes-Objekt) |
updatesPath | string | Ja | JSON-Pfad zum Array der Änderungen |
matchAttributeName | string | Ja | Name des Record-Attributs, das einen Record identifiziert |
itemMatchValuePath | string | Ja | Pfad relativ zur jeweiligen Änderung zum Wert, der den Record auswählt |
attributeUpdates | Liste | Ja | Attribut-Updates für jeden adressierten Record (siehe unten) |
targetPath | string | Ja | JSON-Pfad, in den das geänderte Array geschrieben wird |
targetValueWriteMode, targetValueKind, documentMode | Nein | Wie bei allen Nodes mit Zielpfad |
attributeUpdates
| Feld | Beschreibung |
|---|---|
attributeName | Name des Record-Attributs, das gesetzt wird |
valuePath | Pfad relativ zur Änderung, der den Wert liefert. Hat Vorrang vor value |
value | Statischer Wert. =now() setzt die aktuelle UTC-Zeit |
Verhalten
- Jede Änderung wird einem Record zugeordnet, indem der Wert an
itemMatchValuePathmit dem Record-AttributmatchAttributeNameverglichen wird. Der Vergleich ist nicht Groß-/Kleinschreibung-sensitiv und vergleicht den Text des Werts; die Zahl42passt also zum Text"42". Der Attribut-Schlüssel darf PascalCase (ExternalId) oder camelCase (externalId) gespeichert sein; vorhandene Schlüssel werden direkt aktualisiert, es entsteht kein doppelter Schlüssel. - Tragen mehrere Records denselben Schlüssel, wird der erste aktualisiert (wie bei
@1). - Mehrere Änderungen für denselben Record werden in Array-Reihenfolge angewendet: je Attribut gewinnt die letzte Änderung.
- Records ohne Änderung werden unverändert übernommen; die Reihenfolge des Arrays bleibt erhalten. Das Quell-Array unter
pathwird nie verändert. - Nicht zuordenbare Änderungen (kein Record mit diesem Schlüssel oder kein Schlüsselwert) werden übersprungen. Der Node schlägt nicht fehl, sondern schreibt eine Warnung pro Lauf mit der Anzahl der übersprungenen Änderungen (nie die Werte).
- Passt keine Änderung oder ist
updatesPathleer, wird nichts nachtargetPathgeschrieben und die Pipeline läuft weiter (wie bei@1). - Ist
pathoderupdatesPathkein Array, schreibt der Node eine Warnung, schreibt nichts und die Pipeline läuft weiter.
Beispiel: Batch von Zustandsänderungen mit einem Schreibzugriff pro Control speichern
transformations:
# 1. Zustandsänderungen nach Control gruppieren
- type: GroupBy@1
path: $.states
keyPath: $.controlUuid
targetPath: $.groups
- type: ForEach@1
iterationPath: $.groups
targetPath: $.groupResults
mergePath: $.updates
transformations:
# 2. Ein Lesezugriff pro 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. Alle Änderungen dieses Controls in einem Durchlauf
- 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. Ein Schreibzugriff: genau ein Update pro Control
- type: ApplyChanges@2
entityUpdatesPath: $._updateItems
Warum nicht ein ApplyChanges pro Änderung?
ApplyChanges@2 führt mehrere Updates derselben Entität innerhalb eines Aufrufs Attribut für Attribut zusammen, wobei das spätere Update gewinnt. Jedes mit UpdateRecordArrayItem@1 gebaute Update trägt das ganze Array mit den alten Werten aller anderen Records plus der eigenen einen Änderung. Beim Zusammenführen bleibt nur das letzte Array übrig, die anderen Änderungen gehen verloren. Mit UpdateRecordArrayItem@2 enthält das Array einer Entität alle ihre Änderungen; ApplyChanges@2 erhält ein Update pro Entität und hat nichts zusammenzuführen.
Gleichzeitigkeit
Dieser Node (wie die ganze Lesen-Ändern-Schreiben-Folge der Pipeline) ist bei parallelen Ausführungen nicht sicher: Er arbeitet mit dem Array, das er erhalten hat, und erkennt nicht, dass eine andere Pipeline-Ausführung dieselbe Entität zwischen Lesen und Schreiben geändert hat; der spätere Schreibzugriff ersetzt das ganze Array. Zwei Nachrichten für dieselbe Entität, die gleichzeitig laufen (zum Beispiel aus FromPipelineDataEvent@1, das Nachrichten parallel an mehrere Konsumenten derselben Queue liefert), überschreiben gegenseitig ihre Änderungen. @2 beseitigt verlorene Updates innerhalb eines Batches, nicht zwischen gleichzeitigen Ausführungen.
Können mehrere Ausführungen gleichzeitig Records derselben Entität ändern, lies und schreibe das Array nicht zurück. Verwende das atomare Item-Update von CreateUpdateInfo@1 (recordArrayItemUpdates): Es ändert die genannten Member des passenden Records in einem Datenbank-Statement ohne Lesezugriff, parallele Änderungen anderer Records gehen nicht verloren.
Verwandte Nodes
- GroupBy@1: Änderungen nach Entität gruppieren
- UpdateRecordArrayItem@1: Genau einen Record pro Aufruf aktualisieren
- CreateUpdateInfo@1: Update der Entität erzeugen