SumAggregation@1

Der Node SumAggregation@1 führt gewichtete Summenaggregationen über mehrere gefilterte Datenquellen hinweg durch. Er wählt Daten aus verschiedenen Pfaden aus, wendet optionale Filterung an, extrahiert numerische Werte, wendet Multiplikatoren an und berechnet eine finale aggregierte Summe.

Adapter-Voraussetzungen

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

Node-Konfiguration

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

transformations:
- type: SumAggregation@1
  targetPath: $.totalValue             # Path where the final sum will be stored
  aggregations:                        # Array of aggregation items
    - path: $.orderItems[*]            # Path to select source objects
      filterPath: $.status             # Optional filter path
      comparisonValue: "active"        # Value to match for filtering
      aggregationPath: $.price         # Path to extract numeric values
      value: 1.0                       # Multiplier for extracted values
    - path: $.taxes[*]
      filterPath: $.type
      comparisonValue: "VAT"
      aggregationPath: $.amount
      value: 1.0

Parameter

Erforderliche Parameter

Parameter	Typ	Beschreibung
targetPath	string	Pfad, an dem die finale aggregierte Summe gespeichert wird
aggregations	array	Sammlung von Aggregationselementen, die Datenquellen und Berechnungen definieren

Parameter der Aggregationselemente

Jedes Element im Array aggregations unterstützt diese Parameter:

Parameter	Typ	Erforderlich	Beschreibung
path	string	Ja	JSONPath zur Auswahl von Container-Objekten aus den Wurzeldaten
filterPath	string	Nein	JSONPath zum Filtern der ausgewählten Objekte (relativ zu path)
comparisonValue	any	Nein	Wert, der beim Filtern übereinstimmen muss (exakter String-Vergleich)
aggregationPath	string	Ja	JSONPath zum Extrahieren numerischer Werte (relativ zu den gefilterten Objekten)
value	double	Ja	Multiplikator, der vor dem Summieren auf die extrahierten Werte angewendet wird

Verarbeitungsablauf

Der Node verarbeitet Daten in diesen Schritten:

1. Objektauswahl: Verwendet path, um Container-Objekte aus den Wurzeldaten auszuwählen
2. Optionale Filterung: Wenn filterPath angegeben ist, werden Objekte gefiltert, bei denen der Filterwert mit comparisonValue übereinstimmt
3. Wertextraktion: Extrahiert numerische Werte mithilfe von aggregationPath aus den gefilterten Objekten
4. Gewichtete Berechnung: Multipliziert jeden extrahierten Wert mit dem Multiplikator value
5. Akkumulation: Addiert alle gewichteten Werte zur laufenden Summe
6. Speicherung: Speichert die finale Summe am angegebenen targetPath

Filtermechanismus

• Die Filterung verwendet exakten String-Vergleich (Groß-/Kleinschreibung wird beachtet)
• Wenn filterPath angegeben ist, müssen ALLE Tokens an diesem Pfad mit comparisonValue übereinstimmen
• Setzen Sie filterPath auf null oder lassen Sie es weg, um die Filterung zu deaktivieren
• Objekte, die nicht mit dem Filter übereinstimmen, werden von der Aggregation ausgeschlossen

Wertkonvertierung

• Alle extrahierten Werte werden in Zahlen mit doppelter Genauigkeit umgewandelt
• Unterstützt Ganzzahlen, Gleitkommazahlen und numerische Strings
• Nicht-numerische Werte führen zu Verarbeitungsausnahmen
• Aus jedem Objekt können mehrere Werte extrahiert werden, die alle zur Summe beitragen

Beispiele

Beispiel 1: Einfache Bestellsumme

Berechnen Sie den Gesamtwert aller Bestellpositionen:

transformations:
- type: SumAggregation@1
  targetPath: $.orderTotal
  aggregations:
    - path: $.items[*]
      aggregationPath: $.price
      value: 1.0

Eingabe:

{
  "items": [
    { "name": "Widget A", "price": 29.99 },
    { "name": "Widget B", "price": 15.50 },
    { "name": "Widget C", "price": 8.75 }
  ]
}

Ausgabe:

{
  "items": [
    { "name": "Widget A", "price": 29.99 },
    { "name": "Widget B", "price": 15.50 },
    { "name": "Widget C", "price": 8.75 }
  ],
  "orderTotal": 54.24
}

Beispiel 2: Gefilterte Produktkategorien

Summieren Sie nur die Preise elektronischer Produkte:

transformations:
- type: SumAggregation@1
  targetPath: $.electronicsTotal
  aggregations:
    - path: $.products[*]
      filterPath: $.category
      comparisonValue: "Electronics"
      aggregationPath: $.price
      value: 1.0

Eingabe:

{
  "products": [
    { "name": "Laptop", "category": "Electronics", "price": 999.99 },
    { "name": "Book", "category": "Media", "price": 12.99 },
    { "name": "Phone", "category": "Electronics", "price": 599.99 },
    { "name": "Shirt", "category": "Clothing", "price": 25.99 }
  ]
}

Ausgabe:

{
  "products": [
    { "name": "Laptop", "category": "Electronics", "price": 999.99 },
    { "name": "Book", "category": "Media", "price": 12.99 },
    { "name": "Phone", "category": "Electronics", "price": 599.99 },
    { "name": "Shirt", "category": "Clothing", "price": 25.99 }
  ],
  "electronicsTotal": 1599.98
}

Beispiel 3: Gewichtete Finanzberechnung

Berechnen Sie den Netto-Bestellwert mit Steuern und Rabatten:

transformations:
- type: SumAggregation@1
  targetPath: $.netTotal
  aggregations:
    - path: $.orderItems[*]
      filterPath: $.type
      comparisonValue: "product"
      aggregationPath: $.price
      value: 1.0                        # Add product prices
    - path: $.adjustments[*]
      filterPath: $.type
      comparisonValue: "discount"
      aggregationPath: $.amount
      value: -1.0                       # Subtract discounts
    - path: $.adjustments[*]
      filterPath: $.type
      comparisonValue: "tax"
      aggregationPath: $.amount
      value: 1.0                        # Add taxes

Eingabe:

{
  "orderItems": [
    { "type": "product", "name": "Widget A", "price": 100.0 },
    { "type": "product", "name": "Widget B", "price": 50.0 },
    { "type": "service", "name": "Setup", "price": 25.0 }
  ],
  "adjustments": [
    { "type": "discount", "description": "Bulk discount", "amount": 10.0 },
    { "type": "tax", "description": "Sales tax", "amount": 15.0 },
    { "type": "shipping", "description": "Express shipping", "amount": 12.0 }
  ]
}

Ausgabe:

{
  "orderItems": [
    { "type": "product", "name": "Widget A", "price": 100.0 },
    { "type": "product", "name": "Widget B", "price": 50.0 },
    { "type": "service", "name": "Setup", "price": 25.0 }
  ],
  "adjustments": [
    { "type": "discount", "description": "Bulk discount", "amount": 10.0 },
    { "type": "tax", "description": "Sales tax", "amount": 15.0 },
    { "type": "shipping", "description": "Express shipping", "amount": 12.0 }
  ],
  "netTotal": 155.0
}

Berechnung: (100 + 50) - 10 + 15 = 155.0

Beispiel 4: Einheitenumrechnung mit Multiplikatoren

Summieren Sie Gewichte aus verschiedenen Einheiten (Umrechnung in Gramm):

transformations:
- type: SumAggregation@1
  targetPath: $.totalWeightGrams
  aggregations:
    - path: $.items[*]
      filterPath: $.weightUnit
      comparisonValue: "kg"
      aggregationPath: $.weight
      value: 1000.0                     # Convert kg to grams
    - path: $.items[*]
      filterPath: $.weightUnit
      comparisonValue: "g"
      aggregationPath: $.weight
      value: 1.0                        # Grams remain as-is
    - path: $.items[*]
      filterPath: $.weightUnit
      comparisonValue: "lb"
      aggregationPath: $.weight
      value: 453.592                    # Convert pounds to grams

Eingabe:

{
  "items": [
    { "name": "Package A", "weight": 2.5, "weightUnit": "kg" },
    { "name": "Package B", "weight": 750, "weightUnit": "g" },
    { "name": "Package C", "weight": 1.1, "weightUnit": "lb" }
  ]
}

Ausgabe:

{
  "items": [
    { "name": "Package A", "weight": 2.5, "weightUnit": "kg" },
    { "name": "Package B", "weight": 750, "weightUnit": "g" },
    { "name": "Package C", "weight": 1.1, "weightUnit": "lb" }
  ],
  "totalWeightGrams": 3248.9512
}

Berechnung: (2.5 × 1000) + 750 + (1.1 × 453.592) = 3248.9512 Gramm

Beispiel 5: Mehrere Werte aus Arrays

Summieren Sie alle Beträge aus verschachtelten Arrays:

transformations:
- type: SumAggregation@1
  targetPath: $.grandTotal
  aggregations:
    - path: $.invoices[*]
      aggregationPath: $.lineItems[*].amount
      value: 1.0

Eingabe:

{
  "invoices": [
    {
      "id": "INV-001",
      "lineItems": [
        { "description": "Item 1", "amount": 50.0 },
        { "description": "Item 2", "amount": 30.0 }
      ]
    },
    {
      "id": "INV-002",
      "lineItems": [
        { "description": "Item 3", "amount": 75.0 },
        { "description": "Item 4", "amount": 25.0 }
      ]
    }
  ]
}

Ausgabe:

{
  "invoices": [
    {
      "id": "INV-001",
      "lineItems": [
        { "description": "Item 1", "amount": 50.0 },
        { "description": "Item 2", "amount": 30.0 }
      ]
    },
    {
      "id": "INV-002",
      "lineItems": [
        { "description": "Item 3", "amount": 75.0 },
        { "description": "Item 4", "amount": 25.0 }
      ]
    }
  ],
  "grandTotal": 180.0
}

Anwendungsfälle

• Finanzberechnungen: Berechnen Sie Bestellsummen, Steuern, Rabatte und Nettobeträge
• Bestandsverwaltung: Summieren Sie Mengen über verschiedene Lager oder Produktkategorien hinweg
• Statistische Analyse: Berechnen Sie gewichtete Mittelwerte, Summen und Aggregationen
• Einheitenumrechnung: Konvertieren und summieren Sie Werte aus verschiedenen Maßeinheiten
• Aggregation aus mehreren Quellen: Kombinieren Sie Daten aus verschiedenen Quellen mit unterschiedlichen Gewichtungsfaktoren
• Bedingte Summierung: Summieren Sie nur Werte, die bestimmte Kriterien erfüllen

Fehlerbehandlung

Der Node löst Fehler aus, wenn:

• Der Eingabedatenkontext null ist
• Werte an aggregationPath nicht in Zahlen umgewandelt werden können
• Ungültige JSONPath-Ausdrücke verwendet werden

Hinweise

• Nur numerische Werte: Alle aggregierten Werte müssen in Zahlen mit doppelter Genauigkeit umwandelbar sein
• Filterpräzision: Der String-Vergleich für die Filterung beachtet Groß-/Kleinschreibung und ist exakt
• Mehrfachextraktion: aggregationPath kann mehrere Werte aus jedem Objekt auswählen
• Reihenfolgeunabhängigkeit: Die Reihenfolge der Aggregationselemente hat keinen Einfluss auf das mathematische Ergebnis
• Performance: Berücksichtigen Sie die Filterselektivität bei großen Datensätzen – restriktivere Filter sollten zuerst platziert werden
• Genauigkeit: Die Ergebnisse behalten die Gleitkommagenauigkeit doppelter Präzision bei

Verwandte Nodes

• Math@1: Führen Sie mathematische Operationen an einzelnen Werten durch
• Project@1: Wählen Sie vor der Aggregation bestimmte Felder aus
• If@1: Wenden Sie vor der Aggregation bedingte Logik an