Zum Hauptinhalt springen

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​

ParameterTypPflichtBeschreibung
pathstringJaJSON-Pfad zum RecordArray (die Records haben ein Attributes-Objekt)
updatesPathstringJaJSON-Pfad zum Array der Änderungen
matchAttributeNamestringJaName des Record-Attributs, das einen Record identifiziert
itemMatchValuePathstringJaPfad relativ zur jeweiligen Änderung zum Wert, der den Record auswählt
attributeUpdatesListeJaAttribut-Updates für jeden adressierten Record (siehe unten)
targetPathstringJaJSON-Pfad, in den das geänderte Array geschrieben wird
targetValueWriteMode, targetValueKind, documentModeNeinWie bei allen Nodes mit Zielpfad

attributeUpdates​

FeldBeschreibung
attributeNameName des Record-Attributs, das gesetzt wird
valuePathPfad relativ zur Änderung, der den Wert liefert. Hat Vorrang vor value
valueStatischer Wert. =now() setzt die aktuelle UTC-Zeit

Verhalten​

  • Jede Änderung wird einem Record zugeordnet, indem der Wert an itemMatchValuePath mit dem Record-Attribut matchAttributeName verglichen wird. Der Vergleich ist nicht Groß-/Kleinschreibung-sensitiv und vergleicht den Text des Werts; die Zahl 42 passt 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 path wird 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 updatesPath leer, wird nichts nach targetPath geschrieben und die Pipeline läuft weiter (wie bei @1).
  • Ist path oder updatesPath kein 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​