Date (Data Type)

Learn about the Date data type in Notion formulas.

Notion formulas can work with and output date objects, which are a special data type.

They’re different than strings, as they can be manipulated with date functions such as dateAdd and dateSubtract.

Underneath the hood, Notion’s date object consists of three parts:

  • Start date
  • End date (optional)
  • Time zone

You can learn more about how dates are formatted under the hood at the Notion API’s property value reference for dates:

Property values
A property value defines the identifier, type, and value of a page property in a page object. It’s used when retrieving and updating pages, ex: Create and Update pages. All property values Each page property value object contains the following keys. In addition, it contains a key corresponding with …
developers.notion.com

The following Notion property types output (or can output) date objects:

  • Date
  • Created time
  • Edited time
  • Rollup (if set to rollup a property outputting a date object, and not set to “show original”)
  • Formula (if the formula is outputting a date object)

Within a Notion formula, the following functions output single date objects:

FunctionExampleOutput
startstart(prop("Date"))August 18, 2022
endend(prop("Date"))August 25, 2022
nownow()August 18, 2022 2:10 PM
fromTimestampfromTimestamp(1656012840000)June 23, 2022 1:34 PM
dateAdddateAdd(now(),3,"months")November 18, 2022 2:11 PM
dateSubtractdateSubtract(now(),3,"months")May 18, 2022 2:11 PM
dateRangedateRange(now(), prop("Date"))August 17, 2023 11:19 AM → August 25, 2023
parseDateparseDate("2023-01-01")January 1, 2023

Notion sets it time zone automatically based on the system’s time zone.

Depending on the property and/or formula function that is outputting the date object, you can get different results.

The diagram below shows the same Notion database viewed from two different time zones (this was accomplished by setting my system time to a different time zone, then refreshing the page). You can also view the diagram full-screen on Whimsical.

View and duplicate an example database with all of these date objects:

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

Date properties with set times always display those times in the time zone in which they were set.

If you don’t specify a time zone manually, then the time zone won’t show for you when you’re in that time zone; however, users in other time zones will see the time zone displayed along with the date.

Note how the second row does not display (MDT) at first. When the system time zone is changed, that row now displays (MDT), and the set time (8:00am) is not changed to reflect the system’s new time zone.

This behavior is reflected in the Date (Formula) property, which simply referenced the Date property: prop("Date").

However, things are different when dates are derived from a timestamp. The date objects created from the fromTimestamp function – as well as the now function – are always displayed in the local time zone’s time. In these instances, this behavior cannot be changed, and an alternate time zone cannot be specified.

It’s important to note that the formatDate function takes a date object as its main argument and outputs a string value.

For this reason, you cannot pass the output of formatDate() to date functions such as dateAdd.

It is also very difficult to perform date comparisons using the output of formatDate(). While equality comparisons work well:

formatDate(now(), "MMM DD YYYY") == formatDate(prop("Date"), "MMM DD YYYY")
Code language: JavaScript (javascript)

…it is much more difficult to perform “earlier than” or “later than” comparisons.

Therefore, it is recommended to use functions such as timestamp, date, month, year, etc. to make these kinds of comparisons.

About the Author

My name is Thomas Frank, and I'm a Notion-certified writer, YouTuber, and template creator. I've been using Notion since 2018 to organize my personal life and to run my business and YouTube channel. In addition to this formula reference, I've created a free Notion course for beginners and several productivity-focused Notion templates. If you'd like to connect, follow me on Twitter.

🤔 Have an UB Question?

Fill out the form below and I’ll answer as soon as I can! ~Thomas

🤔 Have a Question?

Fill out the form below and I’ll answer as soon as I can! ~Thomas