Formula properties

A formula property calculates its value instead of storing one you type. Give a Book a daysToRead formula of daysBetween(started, finished), and every Book shows how long it took you, updated whenever either date changes.

Formula properties are read-only on Object pages. While a property has a formula, any value stored in it is ignored.

Add a formula

Formulas are set in the Type editor on the compact layout, which you get in the mobile app or in the web app on a narrow window. The desktop layout’s Object type settings show which properties have formulas, marked ƒ, but don’t include a formula editor.

1. Add the property that will hold the result, such as a Number named daysToRead (see Add a property).
2. On the compact layout, open the Type and choose Edit type.
3. On the property’s row, choose Formula.
4. Enter the expression and confirm it. To remove the formula, clear the field.
5. Check the result on a few Objects, including ones with empty values.

Write a formula

Refer to other properties by name. Names must be single words made of letters, digits, and underscores, so daysToRead and page_count work but Page count can’t be referenced. A formula can use any property the Type has, including inherited and Mixin properties.

daysBetween(today(), due)
if(done, "Finished", "Open")
round(pagesRead / pages * 100)
coalesce(nickname, name)

Kind	What is available
Arithmetic	+, -, *, /, %
Comparison and logic	==, !=, <, <=, >, >=, &&, ||, !, and condition ? a : b
Dates	today(), now(), daysBetween(from, to)
Text	len(text), upper(text), lower(text), trim(text), concat(a, b, ...)
Numbers	abs(n), round(n), min(a, b, ...), max(a, b, ...)
Choosing a value	if(condition, a, b); coalesce(a, b, ...) returns the first value that isn’t empty
Related Objects	rollup("relation", "aggregator", "property")

Text values go in single or double quotes. today() and now() return timestamps, so use them inside daysBetween rather than displaying them directly.

A formula is its own small language, not JavaScript, so it can’t run arbitrary code. If a formula has a mistake, the Object shows (formula error) in place of a value.

Combine values from linked Objects

rollup aggregates a property across the Objects in one of the current Object’s relations. All three arguments are quoted: the relation name, the aggregator (sum, count, avg, min, max, or latest), and the property name on the linked Objects.

For example, a Series Type with a books relation to Book can show its average rating with:

rollup("books", "avg", "rating")

The rolled-up property can’t itself be a formula, and a formula can’t read another formula property’s computed value.

Design formulas safely

• Keep calculations small and deterministic.
• Decide how empty inputs should behave; coalesce and if help.
• Match the output property’s kind to the result, such as Number for arithmetic and Text for labels.
• Renaming a property keeps its old name as an alias, so existing formulas keep working.

Formula property or workflow formula?

A formula property is recalculated every time the Object is read. A workflow’s formula action computes a value once, during one workflow run, and passes it to later steps. Use a property when the value belongs permanently in the schema, and a workflow formula for run-specific data.

Next: Aliases.