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@1behä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
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
path | string | Ja | JSON-Pfad zum Quell-Array |
keyPath | string | Nein | Pfad 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 |
targetPath | string | Ja | JSON-Pfad, unter dem die Gruppen gespeichert werden |
targetValueWriteMode | string | Nein (Overwrite) | Wie das Ergebnis geschrieben wird (Overwrite, Append, Prepend) |
targetValueKind | string | Nein (Simple) | Die Art des zu schreibenden Werts (Simple, Array) |
documentMode | string | Nein (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-01und2024-01-01T00:00:00sind verschiedene Schlüssel. - Zahlen werden nach Wert verglichen:
1und1.0sind derselbe Schlüssel. - Es findet keine Typkonvertierung statt: die Zahl
1, der String"1"und der Booleantruesind 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