Intro to formulas

Notion formulas can perform calculations on your existing database properties and help give you better understanding of your data.

To start writing a formula, add a formula property to your Notion database:

1. Click the ••• menu on your database

2. Select Properties and click + Add a property

3. Select Formula

4. Click Edit and begin writing your formula

Notion’s formula syntax might look familiar if you’ve done any programming before! You’ll choose functions (which accomplish different tasks) and inputs (data to manipulate). An output (the result) will be computed and displayed in the new formula property for every row in your database.

For example, in this formula: dateSubtract(prop("Date"), 14, "days")

• The function is dateSubtract()

• dateSubtract() takes in a date, number, and then a unit text, which can be "days", "hours", etc.

• The inputs are Date (property), 14 (number), and "days" (unit of time).

• The output will be a date representing 14 days before your Date property

Notion’s formula editor contains several helper features to assist in writing formulas.

• The editor automatically provides suggestions of functions or properties based on what's in your formula.

  • You can navigate this suggestions panel with up & down arrows and use Enter to accept a suggestion.

• Long formulas will wrap once you’ve exceeded the width of the editor, but you can also use Shift + Enter to create a new line!

  • To navigate between lines, you can use alt/option + up/down.

• If you open the formula editor from a database row, you'll see a live preview of the result of the formula for that row.

  • Note that the result preview will not display line breaks, which can be added using "\n" in the formula, e.g. "Hello" + "\n" + "World"

• The editor will display errors and highlight the erroneous code, so you can better identify the source of issues.

Formulas can manipulate and return different data types. Other property types are supported but their data type will be converted.

Text

• For example, "Hello world"

Number

• For example, 1, -2.5

• Can be displayed using the formatting options of the Formula property (e.g. as a percentage, currency, or with a ring or bar).

Date

• Displays as a date with time (like August 29, 2023 1:33 PM) and can be reformatted to text using the dateFormat() function.

• Dates can be date ranges, which can be constructed using the dateRange() function.

• Dates cannot store seconds or milliseconds.

People

• You can use name() or email() to retrieve data off any People types.

• Displays as people’s names with their photos.

Booleans

• Can be true or false.

• Displays as a filled or unfilled checkbox.

Pages

• Represents Notion pages, like relations.

• You can retrieve the properties of a given Notion page by using . on them!

• Displays as a rich page link with the page's icon.

Lists (or arrays)

• Lists can hold items of any type, including more lists. Multi-select, People, Relation, and most Rollup properties will return list values.

• You can use list functions like at(), filter(), map() to manipulate lists.

• Use the includes() function to check whether these values contain a specific value instead of equality checks.

  • Example: prop("Tags").includes("Movie")

• List items display comma-separated for texts, numbers, and dates. For people, checkboxes, and pages, they display space-separated.

Empty

• The empty value is not displayed in the output of a formula property, but can be used in the computations themselves.

• You can check for emptyness on any piece of data with the empty() function.

• For example, toNumber("") or parseDate("Not a date") will return Empty.