State Transformer
Description
The state-transformer node maintains a per-key state value that can be updated conditionally with each incoming event. On the first event for a given key, the state is initialized using the Initial Value expression. On subsequent events, the state is updated using the New Value expression, which has access to the current state via the #current variable. The update only happens when the Transform When condition is satisfied. Note that the condition does not apply to the Initial Value: the state is always initialized on the first event, regardless of the condition.
The state has a configurable time-to-live (TTL). The TTL timer resets each time the state is updated. After expiration, the next event is treated as the first one for that key, re-initializing the state.
Events are always emitted regardless of the condition. When the condition is false, the current state value is emitted unchanged.
Initial Value, New Value and Transform When must not evaluate to null. When that happens, the event is reported as an error and skipped, and the state is left untouched.
Parameters and configuration
| Name | Description |
|---|---|
| Group By | Groups events by key. Events with the same key share one state. Defaults to empty string (all events share a single state) |
| Initial Value | Expression evaluated on the first event for a key to initialize the state. Has access to the event context. Determines the data type of #current and of the output variable |
| New Value | Expression that computes the new state value. Use #current to access the current state. Its type must be assignable to the Initial Value type |
| Transform When | Condition that controls when to update the state. When true, the state is updated and the TTL timer resets. When false, the current state is emitted unchanged. Does not apply to the initial value, the state is always initialized on the first event. Default: true (always update) |
| TTL | Time after which the state expires. The timer resets each time the state is updated. After expiration, the next event re-initializes the state. Must be a positive duration. |
| Output variable name | The variable that will hold the current state value after processing |
Example
Given a stream of transaction events, to track the maximum transaction amount per user:
- Group By:
#input.userId - Initial Value:
#input.amount - New Value:
T(java.lang.Math).max(#current, #input.amount) - Transform When:
true - TTL: 1 hour
The output variable will contain the highest transaction amount seen for the current user within the TTL window.
Conditional update example
To update the state only when the new value is greater than the previous one:
- Group By:
#input.userId - Initial Value:
#input.amount - New Value:
#input.amount - Transform When:
#input.amount > #current - TTL: 1 hour
When the condition is false, the event still passes through with the current (unchanged) state value.