What is a Notion Formula?

Notion formulas are bits of code that can make your Notion databases much more useful.

Formulas in Notion are like a limited programming language. They’re written and used in Formula properties within Notion databases (learn more about databases with my complete beginner’s guide).

Formulas can take in data from all other database properties, process it using operators, functions, and other values and then output new data.

Using formulas, you can do things in your Notion databases that are otherwise impossible.

This site is a comprehensive reference for creating, using, and debugging Notion formulas.
You can read more about it – and how to use it – in the Reference Introduction.

Every formula operator, function, and data type has been fully documented with example code and one or more working example databases, complete with templates you can duplicate.

You’ll also find reference guides on things like operator precedence, data type conversion, debugging, and regular expressions.

A Formula Example

Let’s say you’re a sales manager with several existing clients. You want to make sure you check in with each client every three months.

Notion formulas will let you create a database view like this (assume “today” is August 18, 2022 – the day I wrote this guide):

View and duplicate this example:

Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.

A new tool that blends your everyday work apps into one. It’s the all-in-one workspace for you and your team

thomasfrank.notion.site

Not only is your Next Check-In date automatically calculated based on your Last Check-In, but the view is also grouped (using Notion’s grouping feature) so that you can easily see any check-ins that need to happen within the next seven days.

Two formulas power this database view: Next Check-In and Next 7 Days.

The Next Check-In formula looks at the date set in the Last Check-In property and calculates the next date by adding three months. To accomplish this, it uses the dateAdd function.

dateAdd(prop("Last Check-In"), 3, "months")
Code language: JavaScript (javascript)

The Next 7 Days formula is slightly more complex. Using the if function, it uses branching logic to output one of two different strings.

If the date displayed in Next Check-In is less than eight days away (from today’s date), then the formula outputs, “Next 7 Days”.

Otherwise, it outputs, “More than 7 Days Out”.

To determine how far out the Next Check-In date is, we use the dateBetween function as the first argument in our if-statement.

if(
    dateBetween(
        prop("Next Check-In"), 
        now(), 
        "days"
    ) < 8, 
    "Next 7 Days", 
    "More than 7 Days Out"
)
Code language: JavaScript (javascript)

Now that we have a formula which can output two different strings of text, we use them in this database view’s Group By setting:

Formula Terms

Throughout this reference, I’ll mention many different terms related to Notion formulas. Here are a few of the most important terms and what they mean.

Formula Components

I use the term “components” to collectively refer to the following tools that you have at your disposal when constructing formulas:

• Properties – these are the other properties that exist in your database.
• Built-ins
  • Operators: symbols that perform operations on 1-3 operands. Includes mathematical operators (such as add), Boolean operators (such as not), and the ternary operator (if).
  • Booleans: the values true and false.
• Functions – pre-defined formulas that you can use to accomplish complex things quickly. Examples include concat (combines lists) and dateAdd (adds x units of time to a date).

Data Types

Notion formulas work with – and output – one of seven different data types:

• String
• Number
• Boolean (Checkbox) – Notion refers to these as “Checkbox” values, but under the hood, they’re classic Boolean true/false values.
• Date
• List – these are also referred to as “arrays” in other programming languages.
• Person
• Page

Understanding data types is crucial for comfortably working with Notion formulas. Every property outputs a specific data type (except Formulas and Rollups, which can output several).

Additionally, every operator and function accepts specific data types in its argument(s). They also output data of a specific type – and that type is often different than the data types taken as inputs.

You can see an example of every property type within Notion referenced in a formula in this database:

Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.

A new tool that blends your everyday work apps into one. It’s the all-in-one workspace for you and your team

thomasfrank.notion.site

Data Type Example

Here’s an example using the dateAdd function:

dateAdd(now(), 5, "days")
Code language: JavaScript (javascript)

This function requires three arguments, which must be (in this order):

1. A date
2. A number
3. A string (this must also be one of the accepted units, such as “days” or “years”)

If the arguments are not passed data of the correct type, the formula will throw a “does not satisfy” error.

Good to know: Unlike many programming languages, Notion does not do automatic type conversion within formulas. You’ll need to provide data of the correct type within all function arguments.

The only exceptions to this are the test, replace, and replaceAll functions. These are advanced functions, so I won’t cover their details here.
You’ll also need to make sure the final output of your formula has only one data type.