Math@1

Node Math@1 performs mathematical operations on numeric data within JSON objects. It can add, subtract, multiply, divide, calculate modulo values, or round numbers to a specified number of decimal places using either a constant value or a value from another location in the data.

Adapter Prerequisites

• General availability: All adapters support this node type.

Node Configuration

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

transformations:
- type: Math@1
  path: $.sensors                      # Path to the objects containing numeric data
  itemPath: $.temperature             # Path within each object to the numeric value
  itemTargetPath: $.temperatureFahrenheit  # Path where the result will be stored
  operation: Multiply                  # Mathematical operation to perform
  value: 1.8                          # Constant value to use in operation
  # OR use valuePath instead of value:
  # valuePath: $.conversionFactor      # Path to value to use in operation

Parameters

Required Parameters

Parameter	Type	Description
path	string	JSON path to the objects containing the numeric data to process
itemPath	string	Relative path within each object to the numeric value to process
itemTargetPath	string	Relative path within each object where the result will be stored
operation	enum	Mathematical operation to perform: Add, Subtract, Multiply, Divide, Modulo, or Round

Optional Parameters

Parameter	Type	Default	Description
value	double	-	Constant numeric value to use in the mathematical operation
valuePath	string	-	JSON path to the value to use in the mathematical operation
decimalPlaces	int	0	Number of decimal places to round to (only used with Round operation)

Mathematical Operations

The node supports six basic mathematical operations:

• Add: Adds the specified value to the source value
• Subtract: Subtracts the specified value from the source value
• Multiply: Multiplies the source value by the specified value
• Divide: Divides the source value by the specified value
• Modulo: Returns the remainder after dividing the source value by the specified value
• Round: Rounds the source value to the specified number of decimal places (uses decimalPlaces parameter)

Value Sources

For arithmetic operations (Add, Subtract, Multiply, Divide, Modulo), you can specify the second operand in two ways:

1. Constant Value: Use the value parameter to specify a fixed numeric value
2. Dynamic Value: Use the valuePath parameter to reference a value from elsewhere in the data

Only one of value or valuePath should be specified. If valuePath is provided, it takes precedence over value.

Note: The Round operation does not use value or valuePath parameters. It only requires the decimalPlaces parameter to determine the precision of rounding.

Error Handling

The node will:

• Issue a warning if no source data is found at the specified path
• Issue a warning if no numeric value is found at the specified itemPath for an object
• Throw an error if the value (from value or valuePath) is null or not set
• Throw an error if an unsupported operation is specified

Examples

Example 1: Temperature Conversion (Constant Value)

Convert temperature from Celsius to Fahrenheit:

transformations:
- type: Math@1
  path: $.readings
  itemPath: $.celsius
  itemTargetPath: $.fahrenheit
  operation: Multiply
  value: 1.8
- type: Math@1
  path: $.readings
  itemPath: $.fahrenheit
  itemTargetPath: $.fahrenheit
  operation: Add
  value: 32

Input:

{
  "readings": [
    { "celsius": 20, "sensor": "A1" },
    { "celsius": 25, "sensor": "A2" }
  ]
}

Output after both transformations:

{
  "readings": [
    { "celsius": 20, "sensor": "A1", "fahrenheit": 68 },
    { "celsius": 25, "sensor": "A2", "fahrenheit": 77 }
  ]
}

Example 2: Price Calculation with Tax (Dynamic Value)

Calculate total price including tax using a dynamic tax rate:

transformations:
- type: Math@1
  path: $.orders
  itemPath: $.subtotal
  itemTargetPath: $.tax
  operation: Multiply
  valuePath: $.taxRate
- type: Math@1
  path: $.orders
  itemPath: $.subtotal
  itemTargetPath: $.total
  operation: Add
  valuePath: $.tax

Input:

{
  "taxRate": 0.15,
  "orders": [
    { "id": "ORD-001", "subtotal": 100 },
    { "id": "ORD-002", "subtotal": 250 }
  ]
}

Output after both transformations:

{
  "taxRate": 0.15,
  "orders": [
    { "id": "ORD-001", "subtotal": 100, "tax": 15, "total": 115 },
    { "id": "ORD-002", "subtotal": 250, "tax": 37.5, "total": 287.5 }
  ]
}

Example 3: Discount Application

Apply a percentage discount to product prices:

transformations:
- type: Math@1
  path: $.products
  itemPath: $.originalPrice
  itemTargetPath: $.discount
  operation: Multiply
  value: 0.2  # 20% discount
- type: Math@1
  path: $.products
  itemPath: $.originalPrice
  itemTargetPath: $.salePrice
  operation: Subtract
  valuePath: $.discount

Input:

{
  "products": [
    { "name": "Widget A", "originalPrice": 50 },
    { "name": "Widget B", "originalPrice": 75 }
  ]
}

Output:

{
  "products": [
    { "name": "Widget A", "originalPrice": 50, "discount": 10, "salePrice": 40 },
    { "name": "Widget B", "originalPrice": 75, "discount": 15, "salePrice": 60 }
  ]
}

Example 4: Unit Conversion

Convert measurements from meters to feet:

transformations:
- type: Math@1
  path: $.measurements
  itemPath: $.meters
  itemTargetPath: $.feet
  operation: Multiply
  value: 3.28084

Input:

{
  "measurements": [
    { "location": "Room A", "meters": 10 },
    { "location": "Room B", "meters": 15.5 }
  ]
}

Output:

{
  "measurements": [
    { "location": "Room A", "meters": 10, "feet": 32.8084 },
    { "location": "Room B", "meters": 15.5, "feet": 50.85302 }
  ]
}

Example 5: Modulo Operation for Remainders

Calculate remainder for pagination or cyclic patterns:

transformations:
- type: Math@1
  path: $.records
  itemPath: $.index
  itemTargetPath: $.pageGroup
  operation: Modulo
  value: 10

Input:

{
  "records": [
    { "id": "item-1", "index": 23 },
    { "id": "item-2", "index": 47 },
    { "id": "item-3", "index": 100 },
    { "id": "item-4", "index": 8 }
  ]
}

Output:

{
  "records": [
    { "id": "item-1", "index": 23, "pageGroup": 3 },
    { "id": "item-2", "index": 47, "pageGroup": 7 },
    { "id": "item-3", "index": 100, "pageGroup": 0 },
    { "id": "item-4", "index": 8, "pageGroup": 8 }
  ]
}

Example 6: Round Operation for Decimal Precision

Round values to a specific number of decimal places:

transformations:
- type: Math@1
  path: $.measurements
  itemPath: $.value
  itemTargetPath: $.rounded
  operation: Round
  decimalPlaces: 2

Input:

{
  "measurements": [
    { "id": "temp1", "value": 23.456789 },
    { "id": "temp2", "value": 19.1 },
    { "id": "temp3", "value": 25.999 },
    { "id": "temp4", "value": 20.0 }
  ]
}

Output:

{
  "measurements": [
    { "id": "temp1", "value": 23.456789, "rounded": 23.46 },
    { "id": "temp2", "value": 19.1, "rounded": 19.1 },
    { "id": "temp3", "value": 25.999, "rounded": 26.0 },
    { "id": "temp4", "value": 20.0, "rounded": 20.0 }
  ]
}

Example 7: Round to Integer (Default)

Round to nearest integer using default decimalPlaces (0):

transformations:
- type: Math@1
  path: $.scores
  itemPath: $.percentage
  itemTargetPath: $.roundedScore
  operation: Round

Input:

{
  "scores": [
    { "student": "Alice", "percentage": 87.6 },
    { "student": "Bob", "percentage": 92.4 },
    { "student": "Charlie", "percentage": 89.5 }
  ]
}

Output:

{
  "scores": [
    { "student": "Alice", "percentage": 87.6, "roundedScore": 88 },
    { "student": "Bob", "percentage": 92.4, "roundedScore": 92 },
    { "student": "Charlie", "percentage": 89.5, "roundedScore": 90 }
  ]
}

Use Cases

• Unit Conversion: Convert between different measurement units
• Price Calculation: Apply taxes, discounts, or markups to prices
• Data Normalization: Scale or adjust numeric values for analysis
• Formula Application: Apply mathematical formulas to transform data
• Percentage Calculations: Calculate percentages, ratios, or proportions
• Financial Calculations: Compute interest, fees, or other financial metrics
• Remainder Calculations: Use modulo for pagination, cyclic patterns, or hash buckets
• Data Partitioning: Distribute data across buckets using modulo operations
• Scheduling: Calculate recurring intervals or cycle positions
• Precision Control: Round values to specific decimal places for display or storage
• Data Cleaning: Standardize numeric precision across datasets

Notes

• Numeric Values Only: The node only operates on numeric values. Non-numeric values will cause warnings and be skipped
• Precision: Results maintain the precision of the input values and operations
• Array Processing: The node processes all objects found at the specified path
• Path Validation: Both itemPath and target paths are relative to each object found at path
• Division by Zero: Division by zero will result in infinity or NaN values depending on the input
• Modulo by Zero: Modulo by zero will throw a DivideByZeroException
• Value Requirements: Either value or valuePath must be specified for arithmetic operations, but not both
• Round Operation: The Round operation uses banker's rounding (MidpointRounding.ToEven) and only requires decimalPlaces
• Decimal Places: Default is 0 (round to integer), negative values are not supported

Related Nodes

• FormatString@1: Format numeric results into strings with custom formatting
• ConvertDataType@1: Convert between different data types including numeric conversions