> For the complete documentation index, see [llms.txt](https://docs.ninox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ninox.com/ninox-scripting/automate-your-workflows/work-with-functions/numbers-and-math.md). # Numbers and math Numbers drive many Ninox apps. You use them for prices, quantities, ratings, durations, percentages, and all kinds of calculations.
Function (A-Z)Task
abs()Remove the sign from a number
acos()Calculate the arccosine of a number
asin()Calculate the arcsine of a number
atan()Calculate the arctangent of a number
atan2()Return the arctangent of a quotient
avg()Calculate the average of numeric values
ceil()Round a number up to the next integer
cos()Calculate the cosine of an angle
degrees()Convert radians to degrees
even()Check if a number is even
exp()Calculate the natural exponential function
floor()Round a number down to the next integer
ln()Calculate the natural logarithm
log()Calculate a logarithm with base 10 or another base
max()Return the highest or latest value
min()Return the lowest or earliest value
number()Convert a value to a number or return the ID from a choice field
numbers()Return IDs from a multiple choice field
odd()Check if a number is odd
pow()Raise a number to a power
random()Generate a random number between 0 and 1
radians()Convert degrees to radians
range()Build an array of consecutive numbers
round()Round a number to an integer or decimal place
sign()Return whether a number is negative, zero, or positive
sin()Calculate the sine of an angle
sqr()Square a number
sqrt()Take the square root of a number
sum()Add numeric values together
tan()Calculate the tangent of an angle
## Calculate averages, sums, minimums, and maximums Use `avg()`, `sum()`, `min()`, and `max()` to summarize numeric values from arrays, record selections, or computed lists. These functions are useful for totals, KPIs, date ranges, and quick checks in formula fields. ### Average values with `avg()` Use `avg()` to calculate the mathematical average of numeric values from an array or a table selection. `avg([number])` * `[number]`: an array of numbers, or a list of numeric field values `avg()` returns one numeric result for the values you pass in. You can use `avg()` with: * arrays of numbers * columns in table views that contain numeric values #### Let’s take a look at some examples: ```ninox avg([1, 2, 3, 4, 5, 6, 7, 8, 9]) ``` Calculates the average of the numbers 1 through 9.\ The script returns `5`.
``` avg((select invoices).total) ``` Takes all records from the "Invoices" table and calculates the average of the field "Total". ``` avg((select invoices).payment_duration) ``` Calculates the average payment duration across the selected invoices, if `payment_duration` is a numeric field. Tip: * Use `avg()` only with numeric values. ### Sum values with `sum()` Use `sum()` to add numeric values from an array or a table selection. Use it when you want to: * Total invoice amounts, budgets, or payments, or KPI fields. * Add up hours from related records. `sum([number])` * `[number]`: an array of numbers, or a list of numeric field values #### Let's take a look at some examples: ``` sum([1, 2, 3, 4, 5, 6, 7, 8, 9]) ``` Adds the numbers 1 through 9.\ The script returns `45`.
``` sum((select invoices).total) ``` Sums the field "Total" across all records in the table "Invoices".
``` sum((select invoices where year(date) = 2025).total) ``` Filters invoices to 2025 and sums only those totals. ### Find the lowest or earliest value with `min()` Use `min()` to return the lowest number or the earliest date or timestamp in a list. `min([any])` * `[any]`: an array of comparable values, typically numbers, dates, or timestamps `min()` returns one value from the list. The result keeps the same type as the values you pass in: * lowest value for numeric arrays * earliest value for date or timestamp arrays Use `min()` only with values that can be compared meaningfully, such as numbers or time-related values. #### Let’s take a look at some examples: ``` min([1, 21, 9, 35]) ``` Returns the lowest number in the list.\ The script returns `1`.
``` let currYear := year(now()); let myBirthdays := (select employees).date(currYear, month(birthday), day(birthday)); min(myBirthdays) ``` The first line stores the current year from `now()` in a variable. The second line builds a list of birthdays in that year. The last line returns the earliest date in the list. ### Find the highest or latest value with `max()` Use `max()` to return the highest number or the latest date or timestamp in a list. `max([any])` * `[any]`: an array of comparable values, typically numbers, dates, or timestamps `max()` returns one value from the list. The result keeps the same type as the values you pass in: * highest value for numeric arrays * latest value for date or timestamp arrays Use `max()` only with values that can be compared meaningfully, such as numbers or time-related values. #### Let’s take a look at some examples: ``` max([1, 21, 9, 35]) ``` Returns the highest number in the list.\ The script returns `35`.
``` let currYear := year(now()); let birthdays := (select employees).date(currYear, month(Birthday), day(Birthday)); max(birthdays) ``` The first line stores the current year from `now()` in a variable. The second line builds a list of birthdays in that year. The last line returns the latest date in the list. Tips: * Use `avg()` and `sum()` for numeric values only. * Use `min()` and `max()` for both numbers and time-based values. ## Round numbers up, down, or to a chosen precision Use these functions when you want cleaner output, whole numbers, or fixed decimal precision. ### Round up with `ceil()` Use `ceil()` to round a decimal number up to the next higher integer. Use it when you want to: * Round quantities, pages, or package counts up. * Remove decimals and always move to the next full number. `ceil(number)` * `number`: the value you want to round up If the input is already an integer, the value stays unchanged. #### Let’s take a look at some examples: ``` ceil(2.5) ``` Returns `3`. ``` ceil(12.00001) ``` Returns `13`. ``` ceil(27) ``` Returns `27`. Tips: * Use `ceil()` when partial values should count as the next whole unit. ### Round down with `floor()` Use `floor()` to round a decimal number down to the next lower integer. Use it when you want to: * Remove decimals without increasing the value. * Round durations, quantities, or scores down. `floor(number)` * `number`: the value you want to round down If the input is already an integer, the value stays unchanged. #### Let’s take a look at some examples: ``` floor(2.5) ``` Returns `2`. ``` floor(12.00001) ``` Returns `12`. ``` floor(27) ``` Returns `27`. Tips: * Use `floor()` when you need completed whole units only. ### Round to an integer or decimal place with `round()` Use `round()` to round a number to the nearest integer or to a chosen number of decimal places. Use it when you want to: * Show cleaner amounts in reports or forms. * Limit decimal places for prices, rates, or percentages. * Apply standard commercial rounding. `round(number)`\ `round(number, digits)` * `number`: the value you want to round * `digits`: the number of decimal places to keep `round()` uses standard commercial rounding: * `5` or more rounds up * `4` or less rounds down If you omit `digits`, Ninox rounds to the nearest integer. #### Let’s take a look at some examples: ``` round(2.5) ``` Returns `3`. ``` round(12.4987) ``` Returns `12`. ``` round(12.4887, 2) ``` Returns `12.49`. ``` round(12 / 7, 1) ``` Returns `1.7`. Tips: * Use `round(number)` when you want a whole number. * Use `round(number, digits)` when display precision matters. * Use `format()` after rounding when the result also needs a fixed visual format. ## Create random numbers and ranges Use `random()` to generate test values or percentages. Use `range()` to build arrays of consecutive numbers you can loop through or map over. ### Create random numbers with `random()` Use `random()` to generate a random number between `0` and `1`. Use it when you want to: * Generate values for passwords, check digits, or ID-like helpers. * Simulate percentages or probabilities. * Build non-linear test runs or quiz logic. The result is always: * Greater than or equal to `0` * Less than `1` #### Let’s take a look at some examples: ``` random() ``` Returns a random number between 0 and 1.\ Example result: `0.0817465303933449`.
``` floor(random() * 10) ``` Returns a whole number between `0` and `9`.
``` round(random() * 100, 2) ``` Returns a random number between 0 and 100 with two decimal places.\ If the randomly given number is 0.071249890 the result is `7.12`. ### Build arrays of numbers with `range()` Use `range()` to build an array of consecutive numbers. Use it when you want to: * Loop through months, days, or index positions. * Generate helper arrays for repeated calculations. When you pass only one parameter, Ninox starts at `0`.\ The start value is included. The end value is excluded. If `from` is greater than `to`, Ninox returns the numbers in reverse order. `range(to)`\ `range(from, to)`\ `range(from, to, step)` * `from`: the first number in the list * `to`: the point where Ninox stops * `step`: how much to add or subtract each time #### Let’s take a look at some examples: ``` range(7) ``` Creates the array `[0, 1, 2, 3, 4, 5, 6]`.
``` range(2, 7) ``` Creates the array `[2, 3, 4, 5, 6]`.
``` range(7, 2) ``` Creates the array `[7, 6, 5, 4, 3]`.
``` range(2, 9, 2) ``` Counts up in steps of 2.\ The result is `[2, 4, 6, 8]`. Tip: * The `to` value is not included. ## Convert values to numbers with `number()` and `numbers()` Use `number()` to convert one value to a number or return the internal ID of a value from a choice field. Use `numbers()` to return the internal IDs from multiple choice fields. ### Turn a value into a number with `number()` Use `number()` when a field type must become numeric before you calculate with it. Use it when you want to: * Turn imported text like `"1250"` into a usable amount. * Compare or calculate with values from choice fields, as the displayed values of choice fields are always text. * Convert date or duration values before advanced calculations. Depending on the input: * `text` that contains digits only become a number. * `Dates`, `timestamps`, `time intervals`, or `time` values become numeric values which represents milliseconds. * `choice fields` return the numeric ID of the selected option. `number(any)` * `any`: the value you want to convert to a number `number()` returns one numeric result. #### Let’s take a look at some examples: ``` number(today()) ``` Converts today’s date to a numeric Unix time value in milliseconds.
``` number("000075639") ``` Converts digit-only text into a number.\ The script returns `75639`.
``` number(priority) ``` If `priority` is a choice field, this returns the numeric value of the selected option. ``` number(appointment) ``` Converts the start of the appointment to a numeric Unix time value in milliseconds. ``` number(endof(appointment)) ``` Converts the end of the appointment to a numeric Unix time value in milliseconds. ``` number(quantity_as_text) * unit_price ``` Converts imported text in `quantity_as_text` before multiplying it with `unit_price`. ### Get IDs from multiple choice fields with `numbers()` Use `numbers()` to return the IDs of the selected values in a multiple choice field. Use it when you want to: * Reuse selected IDs in filtering logic. `numbers()` returns an array of numeric IDs. `numbers(multi)` #### Let’s take a look at some examples: Assume the multiple choice field `favorite_sports` has these selected items: * Basketball, ID `1` * Dancing, ID `3` * Sailing, ID `4` * Soccer, ID `5` ``` numbers(favorite_sports) ``` Returns the internal IDs of the selected items: `[1, 3, 4, 5]`.
``` let selectedSports := numbers(favorite_sports); contains(selectedSports, 3) ``` Checks whether the option with ID `3` is selected. Tips: * Use `number()` before math operations when the source value is still text. * Use `numbers()` when you need IDs for filtering or comparisons. * Do not confuse `number()` and `numbers()`. One converts a value. The other returns a list of IDs. ## Check if a number is even, odd, or its sign Use `even()`, `odd()`, and `sign()` to test simple number properties. These functions are useful in conditions, formatting rules, and branching logic. ### Check if a number is even with `even()` Use `even()` to check whether a number can be divided by `2` without a remainder. Use it when you want to: * Stripe rows in a table view. * Split records into alternating groups. * Trigger logic every second item in a loop. `even(number)` * `number`: the value you want to test `even()` returns a boolean value: * `true` if the number is even * `false` if the number is not even `0` counts as an even number. For decimal values, `even()` returns `true` only if the value is divisible by `2` without a remainder. #### Let’s take a look at some examples: ``` even(6) ``` Returns `true` because 6 is even. ``` even(7) ``` Returns `false` because 7 is not even. ``` even(10 + 12) ``` Returns `true` because the result is `22`, which is even. ``` even(0) ``` Returns `true` because `0` is even. ``` even(10.2) ``` Returns `false` because `10.2` is not divisible by `2` without a remainder. ``` if even(rec_id) then "lightgray" else "white" end ``` Uses `even()` in a condition to alternate row colors. ### Check if a number is odd with `odd()` Use `odd()` to check whether a number is not divisible by `2` without a remainder. Use it when you want to do the same like with `even()` but for odd numbers. `odd(number)` * `number`: the value you want to test `odd()` returns a boolean value: * `true` if the number is odd * `false` if the number is not odd `0` is even, so `odd(0)` returns `false`. For decimal values, `odd()` returns `true` when the value is not divisible by `2` without a remainder. #### Let’s take a look at some examples: ``` odd(5) ``` Returns `true` because 5 is odd. ``` odd(10) ``` Returns `false` because 10 is not odd. ``` odd(10 + 12) ``` Returns `false` because the result is `22`, which is even. ``` odd(0) ``` Returns `false` because `0` is even. ``` odd(10.2) ``` Returns `true` because `10.2` is not divisible by `2` without a remainder. ``` if odd(rec_id) then "▶" else "" end ``` Shows a marker for odd rows only. ### Get the sign of a number with `sign()` Use `sign()` to check whether a number is negative, zero, or positive. Use it when you want to: * Label balances as debit, zero, or credit. * Classify stock changes as incoming or outgoing. * Branch logic based on gain versus loss. `sign(number)` * `number`: the value you want to check `sign()` returns: * `-1` for negative values * `1` for zero and positive values #### Let’s take a look at some examples: ``` sign(-5) ``` Returns `-1` because `-5` is negative. ``` sign(0) ``` Returns `1` because `0` is treated as positive. ``` sign(12.7) ``` Returns `1` because `12.7` is positive. ``` if sign(balance) = -1 then "Overdrawn" else "In credit" end ``` Branches your logic based on whether the value is negative or not. Tips: * Use `sign()` when the direction of a value matters more than its size. * Remember: `0` is treated as positve and even number. ## Work with absolute values, powers, roots, and logarithms Use these functions for more advanced calculations with distances, growth, exponents, or ratios. * `abs()` removes the sign from a number. * `sqr()` and `sqrt()` square a number or take its square root. * `pow()` raises a number to any exponent. * `exp()` calculates the natural exponential function. * `ln()` and `log()` calculate logarithms. ### Get a positive value with `abs()` Use `abs()` when you need the size of a number but not its sign. It returns the absolute value of a number. Use it when you want to: * Show the distance between two numbers. * Compare deviations without caring which side is bigger. `abs(number)` * `number`: the numeric value you want without a sign `abs()` returns: * the same value for positive numbers * `0` for zero * the positive version of a negative number #### Let’s take a look at some examples: ``` abs(-9.3) ``` Removes the minus sign and returns `9.3`. ``` abs(9.3) ``` Leaves the value unchanged and returns `9.3`. ``` abs(0) ``` Returns `0`. ``` abs(actual_hours - planned_hours) ``` Returns the deviation between actual and planned hours as a positive number. ``` abs(income - cost) ``` Returns the difference as a positive value, even if costs are higher than income. ### Square a number with `sqr()` Use `sqr()` to multiply a number by itself. The result is always positive. `sqr(number)` * `number`: the value you want to square #### Let’s take a look at some examples: ``` sqr(3) ``` Calculates `3 * 3` and returns `9`. ``` sqr(-3) ``` Calculates `(-3) * (-3)` and returns `9`. ``` sqr(6 - 9) ``` First calculates `-3`. Then it squares the result and returns `9`. ### Take the square root with `sqrt()` Use `sqrt()` to calculate the square root of a positive number. If the input might be negative, convert it first. A common pattern is `sqrt()` with `abs()`. `sqrt(number)` * `number`: the value you want the square root of #### Let’s take a look at some examples: ``` sqrt(3) ``` Returns `1.7320508075688772`. ``` sqrt(9) ``` Returns `3`. ``` sqrt(-9) ``` Returns an invalid result because the input is negative. ``` sqrt(abs(9 - 13)) ``` First turns `-4` into `4`. Then it returns `2`. ### Raise a number to a power with `pow()` Use `pow()` to raise a base number to any exponent. Use it when you want to: * Build formulas where the exponent changes. `pow(base, exponent)` * `base`: the base number * `exponent`: the power to apply If you use a fractional exponent, `pow()` returns the matching root: * `0.5` returns the square root * `1 / 3` returns the cube root With fractional exponents, the result can be a close approximation instead of a perfectly rounded value. This is normal for floating-point calculations. #### Let’s take a look at some examples: ``` pow(4, 3) ``` Calculates `4` to the power of `3`.\ The result is `64`. ``` pow(64, 0.5) ``` Uses the exponent `0.5`, which is equivalent to the square root.\ The result is `8`. ``` pow(64, 1 / 3) ``` Calculates the cube root of `64`.\ The result can be `3.9999999999999996` instead of exactly `4` because of floating-point precision.\ In such cases combine `pow()` with `round()`. ``` pow(1.05, 12) ``` Calculates 12 periods of 5% compound growth. ### Use the natural exponential function with `exp()` Use `exp()` when you need Euler’s number `e` raised to a power. Use it when you want to: * Apply advanced scoring formulas. * Reverse calculations that use `ln()`. `exp(number)` * `number`: the exponent `exp()` calculates the natural exponential function with Euler’s number `e` as the base. #### Let’s take a look at some examples: ``` exp(1) ``` Calculates `e^1`.\ The result is `2.718281828459045`. ``` exp(0) ``` Returns `1`. ``` exp(5 - 2) ``` First calculates `3`. Then it returns `e^3`, which is `20.085536923187668`. ### Calculate the natural logarithm with `ln()` Use `ln()` to calculate the natural logarithm of a number. This is the logarithm to the base `e`. Use it when you want to: * Reverse a calculation that used `exp()`. * Compress very large ranges of values. * Use advanced formulas for growth or normalization. `ln(number)` * `number`: the value you want the logarithm of `ln()` returns one numeric result. For `ln()`: * Positive values return a real number. * `0` returns `-∞`. * Negative values are invalid. #### Let’s take a look at some examples: ``` ln(1) ``` Returns `0` because `e^0 = 1`. ``` ln(0) ``` Returns `-∞`. ``` ln(100) ``` Returns `4.605170185988092`. ``` ln(exp(3)) ``` Returns a value close to `3`. ### Calculate logarithms with other bases using `log()` Use `log()` when you need a logarithm with base `10` or another base. Use it when you want to: * Reduce large values to a smaller scale. * Work with formulas that use base 10 or custom bases. `log(number)`\ `log(number, number)` * first `number`: the value you want the logarithm of * second `number`: the base. If you skip it, Ninox uses base `10` For `log()`: * Positive values return a real number. * `0` returns `-∞`. * Negative values are invalid. #### Let’s take a look at some examples: ``` log(1) ``` Returns `0` with the default base `10`. ``` log(0) ``` Returns `-∞`. ``` log(3, 5) ``` Calculates the logarithm of `3` to base `5`.\ The result is `0.6826061944859853`. ``` log('Followers', 10) ``` Compresses large follower counts so they are easier to compare in a score. Tips: * Use `pow()` when the exponent is variable. * Use `exp()`, `ln()`, and `log()` only when your formula actually needs them. They are less common in everyday app logic. ## Calculate sine, cosine, and tangent Use these functions when you want to work with angles directly in trigonometric formulas. ### Calculate the cosine with `cos()` Use `cos()` to return the cosine of an angle in radians. Use it when you want to: * Convert an angle into a cosine value. * Reuse trigonometric values in calculations. `cos(number)` * `number`: the angle in radians `cos()` returns a number between `-1` and `1`. #### Let’s take a look at some examples: ``` cos(-0.25) ``` Returns `0.9689124217106447`. Tips: * `cos()` expects radians, not degrees. * Use `degrees()` or `radians()` when you need to convert angle units first. ### Calculate the sine with `sin()` Use `sin()` to return the sine of an angle. Use it when you want to: * Convert an angle into a sine value. `sin(number)` * `number`: the angle value `sin()` returns a number between `-1` and `1`. #### Let’s take a look at some examples: ``` sin(-0.25) ``` Returns `-0.24740395925452294`. ``` sin(1) ``` Returns `0.8414709848078965`. Tip: * Convert the input first if your source angle is stored in degrees. ### Calculate the tangent with `tan()` Use `tan()` to return the tangent of an angle. Use it when you want to: * Work with angle-based calculations from one value. `tan(number)` * `number`: the angle value #### Let’s take a look at some examples: ``` tan(1) ``` Returns `1.5574077246549023`. ``` tan(1.5) ``` Returns `14.101419947171719`. ``` tan(5) ``` Returns `-3.380515006246586`. Tip: * Convert the input first if your source angle is stored in degrees. ## Convert angles between radians and degrees Use these functions when your formula needs a different angle unit than the source value provides. ### Convert radians to degrees with `degrees()` Use `degrees()` to convert an angle from radians to degrees. Use it when you want to: * Prepare trigonometric output for people who expect degrees. * Convert results before further angle-based logic. `degrees(number)` * `number`: the angle in radians #### Let’s take a look at some examples: ``` degrees(3.141592653589793) ``` Returns `180`. Tips: * Use `degrees()` when the source value is already in radians. * This is especially useful after trigonometric calculations that return radian values. ### Convert degrees to radians with `radians()` Use `radians()` to convert an angle from degrees to radians. Use it when you want to: * Prepare degree values for trigonometric functions. * Standardize angle input before `sin()`, `cos()`, or `tan()`. `radians(number)` * `number`: the angle in degrees #### Let’s take a look at some examples: ``` radians(180) ``` Returns `3.141592653589793`. Tips: * Use `radians()` before `sin()`, `cos()`, and `tan()` when the input is stored in degrees. * Keep angle units consistent across the whole formula. ## Use inverse trigonometric functions Use these functions when you need to derive an angle from a numeric value or quotient. ### Calculate the arccosine with `acos()` Use `acos()` to return the arccosine of a number. Use it when you want to: * Convert a cosine value into an angle. * Work with geometry or angle-based formulas. `acos(number)` * `number`: the value for which you want the arccosine #### Let’s take a look at some examples: ``` acos(-0.25) ``` Returns `1.8234765819369754`. Tip: * Use `acos()` only with values from `-1` to `1`. Values outside that range do not return a valid result. ### Calculate the arcsine with `asin()` Use `asin()` to return the arcsine of a number. Use it when you want to: * Convert a sine value into an angle. * Build angle-based formulas from normalized values. `asin(number)` * `number`: the value for which you want the arcsine #### Let’s take a look at some examples: ``` asin(-0.25) ``` Returns `-0.25268025514207865`. ``` asin(1) ``` Returns `1.5707963267948966`. ``` asin(2) ``` Returns an invalid result because the input is outside the valid range. Tip: * Use `asin()` only with values from `-1` to `1`. If you are unsure about the range, check imported or calculated values first. ### Calculate the arctangent with `atan()` Use `atan()` to return the arctangent of a number. Use it when you want to: * Convert a tangent value into an angle. * Build geometry or direction formulas from a ratio. `atan(number)` * `number`: the value for which you want the arctangent #### Let’s take a look at some examples: ``` atan(15) ``` Returns `1.5042281630190728`. Tips: * Use `atan()` when you already have one numeric value or ratio. * Use `atan2()` when the quotient comes from two separate values. ### Return the arctangent of a quotient with `atan2()` Use `atan2()` to return the arctangent of the quotient of two numbers. Use it when you want to: * Calculate an angle from two values. * Avoid calculating the quotient first in a separate step. `atan2(number, number)` * first `number`: the numerator value * second `number`: the denominator value `atan2()` returns one number. #### Let’s take a look at some examples: ``` atan2(7, 4) ``` Returns `1.0516502125483738`. Tips: * Use `atan2()` when your formula starts with two separate values. * Use `atan()` when you already have the final quotient as one number. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ninox.com/ninox-scripting/automate-your-workflows/work-with-functions/numbers-and-math.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.