Appendix E: Comprehensive Calculation Functions Reference
This appendix outlines all available expressions you can use inside the Calculated Output window, as well as expected system behaviors for troubleshooting.
To reference data from your knowledge model, always use the Concept[Property] syntax.
1. Mathematical Functions
Use these functions to evaluate numerical properties and return a newly calculated number.
|
Expression Syntax |
Description |
Example Kobai Question Usage |
|
abs(value) |
Returns the absolute (positive) value of a number. |
abs(Financials[BudgetVariance]) |
|
ceil(value) |
Rounds a decimal number up to the nearest whole integer. |
ceil(Equipment[ProductionHours]) |
|
floor(value) |
Rounds a decimal number down to the nearest whole integer. |
floor(Equipment[ProductionHours]) |
|
round(value, precision) |
Rounds a number to a specified number of decimal places. |
round(Material[UnitCost], 2) |
|
max(value_1, value_2) |
Returns the highest number among the provided values. |
max(0, Inventory[StockLevel]) |
|
min(value_1, value_2) |
Returns the lowest number among the provided values. |
min(Asset[MaxCapacity], Asset[CurrentLoad]) |
|
mod(dividend, divisor) |
Returns the remainder after dividing the first number by the second. |
mod(Shipment[TotalUnits], Pallet[MaxCapacity]) |
2. Relative Date Functions
These expressions dynamically calculate timeframes based on the exact time the Question is executed. You pass a Date property into the function, and it returns a numerical value representing the time elapsed (or time remaining) between that date and today.
|
Expression Syntax |
Description |
Example Kobai Question Usage |
|
days_from_today(value) |
Generates the number of days from the value to today. This can be negative if the date is in the future. |
days_from_today (Invoice[DueDate]) |
|
weeks_from_today(value) |
Generates the number of weeks from the value to today. This can be negative if the date is in the future. |
weeks_from_today (Contract[SignedDate]) |
|
months_from_today(value) |
Generates the number of months from the value to today. This can be negative if the date is in the future. |
months_from_today (Contract[RenewalDate]) |
|
years_from_today(value) |
Generates the number of years from the value to today. This can be negative if the date is in the future. |
years_from_today (Employee[HireDate]) |
3. Date Modification Functions
Use this expression to modify an existing Date or Date/Time property within your model to project a future or past date.
|
Expression Syntax |
Description |
Example Kobai Question Usage |
|
date_add("unit", value, property) |
Adds a specified duration to a target date property. Valid units are "days", "weeks", "months", "years". |
date_add("months", 6, Asset[MaintenanceDate]) |
4. Duration Functions
These expressions represent a block of time rather than a fixed calendar date. They calculate the time elapsed between the UNIX epoch (Jan 1, 1970) and a Date/Time property, and are typically used as variables inside larger formulas or logic filters.
|
Expression Syntax |
Description |
Example Kobai Question Usage |
|
days(value) |
Represents a span of days. |
days(SLA[ResolutionTargetDays]) |
|
weeks(value) |
Represents a span of weeks. |
weeks(4) |
|
months(value) |
Represents a span of months. |
months(Finance[QuarterlySpan]) |
|
years(value) |
Represents a span of years. |
years(Asset[LifecycleYears]) |
Troubleshooting & Expected Behaviors
If you are experiencing unexpected results or validation errors when building your calculations, review these standard system behaviors.
Mathematical Function Behaviors
- Decimal Handling: Floating-point mathematics and decimal properties are fully supported within functions like mod.
- Divide by Zero: If the divisor in a mod calculation is 0, the system will safely return a null value rather than crashing.
- Data Type Mismatches: Passing a Text or Date property into a mathematical function (e.g., max(10, Project[Deadline])) will result in a validation error. Dates cannot be implicitly converted to integers for math comparisons.
Date Function Behaviors
- Null Base Dates: If you use date_add on a property that is empty, the function will safely return null (blank) rather than defaulting to today's date or the UNIX epoch.
- Date/Time Preservation: When using date_add on a Date/Time property, the specific time component (e.g., 14:30) is preserved and calculated correctly, not stripped away.
- Relative Decimals: Passing a decimal into a relative date function will be processed according to standard truncation/rounding rules (e.g., adding 1.5 weeks).
- Negative Durations: Negative integer values are permitted for durations (e.g., months(-3)), which is highly useful for backward-looking filters.
