Notion Formula Syntax

Notion formulas are not written in any previously established programming or scripting language.

They’re written in “Notion Formula Syntax” – however, you’ll find that syntax is very similar to the syntax used within Microsoft Excel/Google Sheets formulas.

You’ll likely also see some similarities to Javascript syntax, though Notion Formula Syntax is far simpler.

Good to know: Notion formulas must be entered into the formula editor as a one-line formula without line breaks or indentation.
Refer to my guide on writing complex formulas to see how you can remove these elements before pasting your formulas from a text editor into Notion’s editor.

In Notion formulas, parentheses () are used to open and close functions:

abs(-20) // Output: 20

Commas , are used to separate arguments in functions:

add(34,8) // Output: 42

Quotation marks " are used to:

1. Denote strings
2. Reference property names within the prop() function

// Assume the value of the Name property is "Luffy"
concat("Monkey D. ", prop("Name")) // Output: Monkey D. Luffy

As in most programming languages, the plus sign + can be used for both numeric addition and string concatenation:

38 + 4 // Output: 42

"Monkey" + "D. " + "Luffy" // Output: Monkey D. Luffy

There are several other operators, which perform calculations on one or more operands.

Most operators are binary operators, which means they work on two operands:

10 / 2 // Output: 5

(4 + 5) == 9 // Output: true

9 < 8 // Output: false

The unary operators (unaryPlus and unaryMinus) operate on a single operand:

-(-10) // Output: 10

+"42" // Output: 42 (string converted to a number)

The ternary operator (? and :) operates on three operands, and can be substituted for the if function:

42 > 25 ? "Yes" : "No" // Output: Yes

if( 42 > 25, "Yes", "No") // Output: Yes

When performing mathematical operations, operators follow standard mathematical order of operations.

Refer to the operator precedence guide (which also defines precedence for Boolean operators) for more detail, and remember that you can always use parentheses () to specify the order you want:

4 + 8 / 4 - 2^2 // Output: 2
4 + (8 / 4) - (2^2) // Output: 2

(4 + 8) / (4 - 2) ^ 2 // Output: 3
👇 // simplified
(12) / (4) // Output: 3

Notion’s formula editor includes many functions, which are reusable blocks of code that you can call.

Functions accept one or more arguments, operate on the data of those arguments using internal logic, and output a result.

Arguments must be of the correct data type; otherwise, your formula will throw an error.

// function_name(argument_1, argument_2)

divide(10,2) // Output: 5

// Note that spaces between arguments are optional, but
// commas are required.
concat("My", " ", "Chemical", " ","Romance") 
// Output: My Chemical Romance

Functions can accept other functions as arguments. The inner-most functions are executed first, and their output is used as the argument value for the function that contains them.

Good to know: Since arguments are strict about data types (as mentioned above), it can be useful to pass a function as an argument that converts data to the correct type.
Note the use of the format function in Example 2 below. It converts the numeric output of the add and multiply functions to string output, which is required by the concat function.
Learn more about this concept in my guide on converting data types.

/* Example 1 */
// Compressed
divide(add(8,2), subtract(5,3)) // Output: 5

// Expanded
divide(
    add(8,2),
    subtract(5,3)
)

---

/* Example 2 */
// Compressed
if(equal(add(8,4),multiply(3,4)),concat(format(add(8,4))," and ",format(multiply(3,4))," are equal!"),concat(format(add(8,4))," and ",format(multiply(3,4))," are not equal!"))

// Expanded
if(
    equal(
        add(8,4),
        multiply(3,4)
    ),
    concat(
        format(
            add(8,4)
        ),
        " and ",
        format(
            multiply(3,4)
        ),
        " are equal!"
    ),
    concat(
        format(
            add(8,4)
        ),
        " and ",
        format(
            multiply(3,4)
        ),
        " are not equal!"
    )
)

Example 2 in the above code block also demonstrates a significant limitation of Notion formulas. Formulas cannot internally define variables. Only properties can be used as variables.

Notion formulas also do not support:

• Loops (for, while, etc.)
• Recursion
• Arrays
• Objects
• Custom, reusable functions

You will not find yourself using curly braces {} or brackets [] in Notion formulas.

Advanced tip: Since Notion doesn’t support these common programming features, you’ll find that many complex formulas use regular expressions to do a lot of the heavy lifting.
Additionally, you’ll learn to start thinking bigger than a single formula. Many complex tasks will require multiple formula properties, “helper” properties that store variables, etc.

Now that you have an overall understanding of how Notion formula syntax works, you should be able to fully understand the details and examples provided for each constant, operator, and function.