Docs
Calculation language
Blockbax lets you combine metrics and properties using a simple expression language. This language is used when defining a calculated metric, when adding a calculation to a series in the explorer or in dashboard widgets.
Calculated metrics support additional functionality on top of this language, such as defining variables, which isn’t available for calculations in the explorer or dashboard widgets.
Arithmetic operations
All basic arithmetic operations can be applied to values in your calculation:
| Operation | Symbol | Example | Comment |
|---|---|---|---|
| Addition | + | 5 + 7 | - |
| Subtraction | - | 10 - 5 | - |
| Multiplication | * | 3 * 9 | - |
| Division | / | 10 / 2 | Division by 0 will produce no result |
| Parenthesis | ( ) | (5 + 7) * 8 | Here 5 + 7 takes precedence over multiplication by 8 |
Multiplication and division take precedence over addition and subtraction, as per the standard arithmetic rules. Any (decimal) number value can be used in arithmetic, and operations can be chained.
Functions
Many default computations are available as functions. Functions can be used anywhere in your computation where a numeric value is expected, and can take as input any literal value or arithmetic.
abs(value)
Computes the absolute value of a number value.
| Parameter | Description |
|---|---|
| value | Input value to compute absolute value for |
acos(value)
Computes the angle in degrees whose cosine is the specified number.
| Parameter | Description |
|---|---|
| value | Value representing a cosine |
asin(value)
Computes the angle in degrees whose sine is the specified number.
| Parameter | Description |
|---|---|
| value | Value representing a sine |
atan(value)
Computes the angle in degrees whose tangent is the specified number.
| Parameter | Description |
|---|---|
| value | Value representing a tangent |
atan2(y,x)
Computes the angle in degrees whose tangent is the quotient of two specified numbers
| Parameter | Description |
|---|---|
| y | The y coordinate of a point |
| x | The x coordinate of a point |
ceil(value)
Rounds decimal numbers up to the closest integer value.
| Parameter | Description |
|---|---|
| value | Value to round |
cos(degrees)
Computes the cosine of the provided number of degrees.
| Parameter | Description |
|---|---|
| degrees | Input in degrees |
distanceBetween(latitudeFrom,longitudeFrom,latitudeTo,longitudeTo)
Computes the Geodetic (across the Earth’s surface) distance in meters between two points using the WGS84 coordinate reference system.
| Parameter | Description |
|---|---|
| latitudeFrom | From position latitude in degrees |
| longitudeFrom | From position longitude in degrees |
| latitudeTo | To position latitude in degrees |
| longitudeTo | To position longitude in degrees |
distanceBetweenXY(xFrom,yFrom,xTo,yTo)
Computes the Euclidean (straight) distance between two 2D points. Distance is in the same unit as provided coordinates.
| Parameter | Description |
|---|---|
| xFrom | From position x coordinate |
| yFrom | From position y coordinate |
| xTo | To position x coordinate |
| yTo | To position y coordinate |
distanceBetweenXYZ(xFrom,yFrom,zFrom,xTo,yTo,zTo)
Computes the Euclidean (straight) distance between two 3D points. Distance is in the same unit as provided coordinates.
| Parameter | Description |
|---|---|
| xFrom | From position x coordinate |
| yFrom | From position y coordinate |
| zFrom | From position z coordinate |
| xTo | To position x coordinate |
| yTo | To position y coordinate |
| zTo | To position z coordinate |
floor(value)
Rounds decimal numbers down to the closest integer value.
| Parameter | Description |
|---|---|
| value | Value to round |
log(value)
Computes the natural logarithm of a value.
| Parameter | Description |
|---|---|
| value | Input value to compute logarithm for |
max(value1,value2)
Computes the maximum value of two number values.
| Parameter | Description |
|---|---|
| value1 | First value to compare |
| value2 | Second value to compare |
min(value1,value2)
Computes the minimum value of two number values.
| Parameter | Description |
|---|---|
| value1 | First value to compare |
| value2 | Second value to compare |
now()
Provides the current time in milliseconds since Unix Epoch.
pi()
Provides the value of Pi with eight decimals of precision.
pow(value,power)
Computes the power of a number value.
| Parameter | Description |
|---|---|
| value | Input value to compute the power of |
| power | The power to raise the value to; fractional and negative numbers are supported |
Example: pow(3, 2) means three to the power of two which results in 9.
random(lower,upper)
Generates a random decimal number from a continuously uniform distribution between provided upper and lower bounds.
| Parameter | Description |
|---|---|
| lower | Lower bound for random number (inclusive) |
| upper | Upper bound for random number (exclusive) |
remainder(dividend,divisor)
Computes the remainder of a division. For example, the remainder of 9 / 2.5 is 1.5. The remainder always takes the sign of the dividend.
| Parameter | Description |
|---|---|
| dividend | Dividend of the division |
| divisor | Divisor of the division |
round(value,precision)
Rounds decimal numbers to a specified number of decimals. Precision rounded down to the closest integer value.
| Parameter | Description |
|---|---|
| value | Value to round |
| precision | Number of decimals to round to (max 8). Decimals precision values are rounded down to nearest integer. |
sin(degrees)
Computes the sine of the provided number of degrees.
| Parameter | Description |
|---|---|
| degrees | Input in degrees |
sqrt(value)
Computes the square root of a number value.
| Parameter | Description |
|---|---|
| value | Input value to compute square root for |
tan(degrees)
Computes the tangent of the provided number of degrees.
| Parameter | Description |
|---|---|
| degrees | Input in degrees |
toDegrees(radians)
Converts an angle from radians to degrees.
| Parameter | Description |
|---|---|
| degrees | Input angle in radians |
toRadians(degrees)
Converts an angle from degrees to radians.
| Parameter | Description |
|---|---|
| degrees | Input angle in degrees |
truncateToHour(date)
Returns a new date that represents the start of the hour of the given date. Example, for February 4th, 2025 14:42:00 this will return February 4th, 2025 14:00:00. This function respects the time zone of the project. Note that dates are represented as milliseconds since Unix Epoch.
| Parameter | Description |
|---|---|
| date | Input date |
truncateToDay(date)
Returns a new date that represents the start of the day of the given date. Example, for February 4th, 2025 14:42:00 this will return February 4th, 2025 00:00:00. This function respects the time zone of the project. Note that dates are represented as milliseconds since Unix Epoch.
| Parameter | Description |
|---|---|
| date | Input date |
truncateToWeek(date)
Returns a new date that represents the start of the week of the given date. Example, for February 4th, 2025 14:42:00 this will return February 3rd, 2025 00:00:00. This function respects the time zone of the project. Note that dates are represented as milliseconds since Unix Epoch.
| Parameter | Description |
|---|---|
| date | Input date |
truncateToMonth(date)
Returns a new date that represents the start of the month of the given date. Example, for February 4th, 2025 14:42:00 this will return February 1st, 2025 00:00:00. This function respects the time zone of the project. Note that dates are represented as milliseconds since Unix Epoch.
| Parameter | Description |
|---|---|
| date | Input date |
Conditionals
The editor supports conditionals so you can vary the calculation based on the input values. Use if, then and else statements, and combine conditions with and or or.
if-then-else
If-then-else statements are used to allow conditional execution of statements. A condition needs to be stated after the if statement. If the said condition is true, the then value will be used. If the condition returns false the else value will be used.
if <condition> then <value1> else <value2>
checking for equality
A condition can check whether two values are the same or not with the operators == (equal to) and != (not equal to). This is supported for both numeric:
voltage.number == 230
and textual values:
soilType.text != "Peat moss"
comparing numbers
Numbers can also be compared with the operators > (greater than), >= (greater than or equal to), < (less than), and <= (less than or equal to):
temperature.number > 25
and
The and operator combines two conditions; it returns true only when both conditions are true. If either condition is false, the operator returns false.
The syntax can be seen below:
<condition1> and <condition2>
To illustrate how you can combine if, then and else statements with and, see the sample syntax below:
if <condition1> and <condition2> then <value1> else <value2>
or
The or operator combines two conditions; it returns true when at least one of them is true.
<condition1> or <condition2>
To illustrate how you can combine if, then and else statements with or, see the sample syntax below:
if <condition1> or <condition2> then <value1> else <value2>
hasValue
With a hasValue condition, you can check whether a metric or property has a value. By default, referencing a metric with no measurement terminates the calculation and produces no output. Use hasValue when you want to branch on the presence of a value instead:
setpoint = if hasValue(setpointManual.number)
then setpointManual.number
else setpointSchedule.number