UNION
Category: Assumptions & result sets
Overview
The UNION function combines the result sets of two or more input nodes into one output. All inputs must have the same levels and must not have overlapping rows.
Use this function when you want to append non-overlapping result slices from nodes that share the same dimensional structure. UNION is a stricter version of ADDITION (+) and can serve as an extra guardrail because the inputs are required to have the same levels.
Syntax
UNION('Node1', 'Node2' [, 'Node3', ...])
Example usage: UNION('Salary Q1', 'Salary Q2')
Parameters
| Parameter | Description | Type | Required |
|---|---|---|---|
| Node1 | First input node to combine | Node reference | Yes |
| Node2 | Second input node to combine | Node reference | Yes |
| Additional nodes | Any number of additional input nodes to combine | Node reference | No |
Output Shape
| Aspect | Behavior |
|---|---|
| Dimensionality | Same as all inputs (they must all have the same levels). |
| Level values | Union of all level values from all inputs. |
| Row count | Sum of all input row counts. No aggregation or deduplication is performed. |
Watch Out
- All inputs must have the same levels.
- Inputs must not have overlapping rows. If any row key appears in more than one input, the calculation fails at runtime.
- The same node cannot appear more than once in the parameter list.
- All inputs must have the same unit.
Examples
Appending non-overlapping slices
This example shows UNION combining two disjoint salary slices with the same level structure. Because the rows do not overlap, the result appends both slices into one output.
Input node: Node1
| Year | Employee | Salary |
|---|---|---|
| 2025 | E1 | 50,000 |
| 2025 | E2 | 60,000 |
Input node: Node2
| Year | Employee | Salary |
|---|---|---|
| 2026 | E1 | 55,000 |
| 2026 | E2 | 66,000 |
Formula: UNION('Node1', 'Node2')
| Year | Employee | → UNION Result |
|---|---|---|
| 2025 | E1 | 50,000 |
| 2025 | E2 | 60,000 |
| 2026 | E1 | 55,000 |
| 2026 | E2 | 66,000 |
Related Functions
| Function | When to use instead |
|---|---|
| ADDITION (+) | When overlap is allowed or expected, or when the inputs do not need UNION’s same-level and no-overlap constraints. |
| ROLLUP | When you need to change granularity or aggregate a node to different levels instead of combining disjoint result slices. |