SumAggregation@1

Node SumAggregation@1 performs weighted sum aggregations across multiple filtered data sources. It selects data from various paths, applies optional filtering, extracts numeric values, applies multipliers, and calculates a final aggregated sum.

Adapter Prerequisites

• General availability: All adapters support this node type.

Node Configuration

For fields targetPath, targetValueWriteMode, and targetValueKind, see Overview.

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

Parameters

Required Parameters

Parameter	Type	Description
targetPath	string	Path where the final aggregated sum will be stored
aggregations	array	Collection of aggregation items defining data sources and calculations

Aggregation Item Parameters

Each item in the aggregations array supports these parameters:

Parameter	Type	Required	Description
path	string	Yes	JSONPath to select container objects from root data
filterPath	string	No	JSONPath for filtering selected objects (relative to path)
comparisonValue	any	No	Value to match when filtering (exact string comparison)
aggregationPath	string	Yes	JSONPath to extract numeric values (relative to filtered objects)
value	double	Yes	Multiplier applied to extracted values before summing

Processing Workflow

The node processes data through these steps:

1. Object Selection: Uses path to select container objects from the root data
2. Optional Filtering: If filterPath is specified, filters objects where the filter value matches comparisonValue
3. Value Extraction: Extracts numeric values using aggregationPath from filtered objects
4. Weighted Calculation: Multiplies each extracted value by the value multiplier
5. Accumulation: Adds all weighted values to the running sum
6. Storage: Stores the final sum at the specified targetPath

Filtering Mechanism

• Filtering uses exact string comparison (case-sensitive)
• When filterPath is specified, ALL tokens at that path must match comparisonValue
• Set filterPath to null or omit it to disable filtering
• Objects that don't match the filter are excluded from aggregation

Value Conversion

• All extracted values are converted to double precision numbers
• Supports integers, floating-point numbers, and numeric strings
• Non-numeric values will cause processing exceptions
• Multiple values can be extracted from each object and all contribute to the sum

Examples

Example 1: Simple Order Total

Calculate the total value of all order items:

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

Input:

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

Output:

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

Example 2: Filtered Product Categories

Sum prices of only electronic products:

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

Input:

{
  "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 }
  ]
}

Output:

{
  "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
}

Example 3: Weighted Financial Calculation

Calculate net order value with taxes and discounts:

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

Input:

{
  "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 }
  ]
}

Output:

{
  "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
}

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

Example 4: Unit Conversion with Multipliers

Sum weights from different units (converting to grams):

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

Input:

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

Output:

{
  "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
}

Calculation: (2.5 × 1000) + 750 + (1.1 × 453.592) = 3248.9512 grams

Example 5: Multiple Values from Arrays

Sum all amounts from nested arrays:

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

Input:

{
  "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 }
      ]
    }
  ]
}

Output:

{
  "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
}

Use Cases

• Financial Calculations: Calculate order totals, taxes, discounts, and net amounts
• Inventory Management: Sum quantities across different warehouses or product categories
• Statistical Analysis: Compute weighted averages, totals, and aggregations
• Unit Conversion: Convert and sum values from different measurement units
• Multi-Source Aggregation: Combine data from various sources with different weighting factors
• Conditional Summation: Sum only values that meet specific criteria

Error Handling

The node will throw errors when:

• The input data context is null
• Values at aggregationPath cannot be converted to numbers
• Invalid JSONPath expressions are used

Notes

• Numeric Values Only: All aggregated values must be convertible to double precision numbers
• Filter Precision: String comparison for filtering is case-sensitive and exact
• Multiple Extractions: aggregationPath can select multiple values from each object
• Order Independence: The order of aggregation items doesn't affect the mathematical result
• Performance: Consider filter selectivity for large datasets - more restrictive filters should be placed first
• Precision: Results maintain double precision floating-point accuracy

Related Nodes

• Math@1: Perform mathematical operations on individual values
• Project@1: Select specific fields before aggregation
• If@1: Apply conditional logic before aggregation