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:
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:
| Function | Example | Output |
|---|---|---|
| start | start(prop("Date")) | August 18, 2022 |
| end | end(prop("Date")) | August 25, 2022 |
| now | now() | August 18, 2022 2:10 PM |
| fromTimestamp | fromTimestamp(1656012840000) | June 23, 2022 1:34 PM |
| dateAdd | dateAdd(now(),3,"months") | November 18, 2022 2:11 PM |
| dateSubtract | dateSubtract(now(),3,"months") | May 18, 2022 2:11 PM |
| dateRange | dateRange(now(), prop("Date")) | August 17, 2023 11:19 AM → August 25, 2023 |
| parseDate | parseDate("2023-01-01") | January 1, 2023 |
Time Zones and Dates in Notion
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:
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.
A Note about formatDate()
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.