Finance Rules

Understanding Data Units

A Data Unit is the fundamental unit of work in OneStream's Finance Engine. Every time you run a calculation or consolidation, the engine breaks the work into Data Units and processes them individually. Your Finance Business Rule fires once per Data Unit.
ℹ️Info
Data Units are specific to Finance Business Rules — the rules attached to Cubes that run during Calculate, Translate, and Consolidate operations. Finance Business Rules can also be triggered on a per-Data Unit basis from a Custom Calculate Data Management step, which runs a CustomCalculate function against a targeted slice of Data Units without requiring a full calculation or consolidation. Other rule types (Dashboard DataSet, Dashboard Extender, Extensibility, etc.) are triggered by user actions or UI events and do not operate on Data Units.

What Is a Data Unit?

A Data Unit is defined by the intersection of:
  • Entity — Which entity is being calculated
  • Scenario — Which scenario (Actual, Budget, Forecast, etc.)
  • Time — Which time period
  • Consolidation member — Local, Translated, Share, Elimination, etc.
  • Parent — Which parent entity in the hierarchy (for consolidation)

Why Data Units Matter

Because your rule fires for every Data Unit, an unguarded rule runs far more often than you might expect. If you have 100 entities, 3 scenarios, and 12 months, that could be thousands of Data Unit executions — and your rule fires for each one.
The single most impactful performance practice is adding guard conditions at the top of your rule to skip Data Units that don't need your logic:
1If api.FunctionType = FinanceFunctionType.Calculate Then
2  ' Only fire for base entities at local currency
3  If api.Entity.IsBase AndAlso api.Cons.IsLocalCurrency Then
4      ' Your calculation logic here
5  End If
6End If

Guard Condition Patterns

Common guard patterns include:
  • api.Entity.IsBase — Only fire for base (leaf) entities, not parent rollups
  • api.Cons.IsLocalCurrency — Only fire at the Local Currency consolidation member
  • api.Scenario.Name = "Actual" — Only fire for a specific scenario
  • api.Entity.Name.StartsWith("US") — Only fire for entities matching a pattern
You can combine multiple guard conditions to narrow execution further:
1If api.FunctionType = FinanceFunctionType.Calculate Then
2  ' Only fire for base entities, local currency, and Actual scenario
3  If api.Entity.IsBase _
4      AndAlso api.Cons.IsLocalCurrency _
5      AndAlso api.Scenario.Name = "Actual" Then
6
7      ' This logic now only fires for a small fraction of all Data Units
8      api.Data.Calculate("A#Profit = A#Sales - A#Costs")
9  End If
10End If
⚠️Warning
Always add Data Unit guard conditions early in your rule. Without them, your calculations will run for every entity, scenario, time, and consolidation combination — leading to slow performance and potentially incorrect results at parent levels.

Related Content