Zum Hauptinhalt springen

GroupBy@1

Der Node GroupBy@1 gruppiert die Elemente eines Arrays nach einem Schlüssel. Das Ergebnis ist ein Array mit einem Eintrag { key, items } je unterschiedlichem Schlüssel. Damit lässt sich ein Batch Entität für Entität verarbeiten: Elemente nach der Entitäts-ID gruppieren, mit ForEach@1 über die Gruppen iterieren und jede Entität nur einmal lesen und schreiben.

Der Node ist eine reine In-Memory-Transformation. Nicht zu verwechseln mit:

  • Group@1, einem rein strukturellen Container des grafischen Editors ohne Wirkung auf die Daten.
  • Distinct@1, der pro Schlüssel nur das erste Element behält und die übrigen verwirft. GroupBy@1 behält alle Elemente.

Adapter-Voraussetzungen​

  • Allgemeine Verfügbarkeit: Alle Adapter unterstützen diesen Node-Typ.

Node-Konfiguration​

Für die Felder path, targetPath, targetValueWriteMode, targetValueKind und documentMode siehe Überblick.

transformations:
- type: GroupBy@1
path: $.states # Pfad zum Quell-Array
keyPath: $.controlUuid # Pfad relativ zu jedem Element, ergibt einen einfachen Wert
targetPath: $.stateGroups # Pfad, unter dem die Gruppen gespeichert werden

Parameter​

ParameterTypErforderlichBeschreibung
pathstringJaJSON-Pfad zum Quell-Array
keyPathstringNeinPfad relativ zu jedem Element zu dem Wert, der die Gruppe bestimmt (String, Zahl, Boolean). Ohne keyPath muss das Array Skalarwerte enthalten; jeder Wert ist sein eigener Schlüssel
targetPathstringJaJSON-Pfad, unter dem die Gruppen gespeichert werden
targetValueWriteModestringNein (Overwrite)Wie das Ergebnis geschrieben wird (Overwrite, Append, Prepend)
targetValueKindstringNein (Simple)Die Art des zu schreibenden Werts (Simple, Array)
documentModestringNein (Extend)Dokumentmodus (Extend, Replace)

Ergebnis​

[
{ "key": "uuid-1", "items": [ { ... }, { ... } ] },
{ "key": "uuid-2", "items": [ { ... } ] }
]
  • Die Gruppen erscheinen in der Reihenfolge des ersten Vorkommens ihres Schlüssels.
  • Die Elemente behalten innerhalb einer Gruppe ihre ursprüngliche Reihenfolge.
  • Die Elemente werden kopiert; das Quell-Array bleibt unverändert.

Schlüsselvergleich​

Schlüssel werden nach Wert verglichen, mit denselben Regeln wie bei Distinct@1:

  • Strings werden ordinal verglichen (Groß-/Kleinschreibung beachtet). Strings, die wie Datumswerte aussehen, werden nicht geparst; 2024-01-01 und 2024-01-01T00:00:00 sind verschiedene Schlüssel.
  • Zahlen werden nach Wert verglichen: 1 und 1.0 sind derselbe Schlüssel.
  • Es findet keine Typkonvertierung statt: die Zahl 1, der String "1" und der Boolean true sind drei verschiedene Schlüssel.

Elemente ohne Schlüssel​

Elemente ohne einfachen Wert an keyPath (Pfad nicht gefunden, null, ein Objekt oder Array, oder ein Element, das kein Objekt ist) werden übersprungen. Der Node schlägt nicht fehl; er schreibt eine Warnung pro Lauf mit der Anzahl der übersprungenen Elemente.

Leere oder fehlende Quelle​

Ist die Quelle kein Array oder leer, wird nichts nach targetPath geschrieben und die Pipeline läuft weiter (wie bei Distinct@1).

Beispiel: Zustandsänderungen Entität für Entität verarbeiten​

Ein Batch enthält Zustandsänderungen mehrerer Controls. Nach Control gruppieren und jedes Control einmal behandeln:

transformations:
- type: GroupBy@1
path: $.states
keyPath: $.controlUuid
targetPath: $.stateGroups

- type: ForEach@1
path: $.stateGroups
iterationPath: $.stateGroups
transformations:
# in der Schleife: $.key.key ist die Control-UUID, $.key.items sind ihre Zustandsänderungen
- type: PrintDebug@1

Eingabe:

{
"states": [
{ "controlUuid": "c-1", "state": "active", "value": 1 },
{ "controlUuid": "c-2", "state": "active", "value": 0 },
{ "controlUuid": "c-1", "state": "totalDay", "value": 12.5 }
]
}

Ausgabe ($.stateGroups):

[
{ "key": "c-1", "items": [
{ "controlUuid": "c-1", "state": "active", "value": 1 },
{ "controlUuid": "c-1", "state": "totalDay", "value": 12.5 } ] },
{ "key": "c-2", "items": [
{ "controlUuid": "c-2", "state": "active", "value": 0 } ] }
]

Verwandte Nodes​

  • Distinct@1: Nur das erste Element je Schlüssel behalten
  • Group@1: Struktureller Editor-Container (ohne Laufzeitwirkung)
  • Flatten@1: Verschachtelte Array-Strukturen glätten