Dates are a common element in many data sources. If a field contains recognizable dates, it will have a date or date time data type. When date fields are used in the viz they get a special set of functionality, including an automatic date hierarchy drill down, date-specific filter options, and specialized date formatting options.
Date functions allow you to manipulate dates in your data source.
Date Functions
Date functions sometimes reference date-specific elements, including the date_part argument, the optional [start_of_week] parameter, and date literals (#). These are covered in more detail at the end of this topic.
There are several other topics that might be of interest but aren't part of date functions:
- Format how a date is displayed in a viz: Custom Date Formats
- Set default date properties: Date Properties for a Data Source
- Work with fiscal dates: Fiscal Dates
- Use the ISO-8601 calendar: ISO-8601 Week-Based Calendar
DATE
Type conversion function that changes string and number expressions into dates, as long as they are in a recognizable format.
| Syntax |
DATE(expression)
|
| Output | Date |
| Definition | Returns a date given a number, string, or date expression. |
| Example |
DATE([Employee Start Date]) DATE("September 22, 2018")
DATE("9/22/2018")
DATE(#2018-09-22 14:52#) |
| Notes |
Unlike DATEPARSE, there is no need to provide a pattern as DATE automatically recognizes many standard date formats. If DATE does not recognize the input, however, try using DATEPARSE and specifying the format. MAKEDATE is another similar function, but MAKEDATE requires the input of numeric values for year, month, and day. |
DATEADD
Adds a specified number of date parts (months, days, etc) to the starting date.
| Syntax |
DATEADD(date_part, interval, date)
|
| Output | Date |
| Definition | Returns the specified date with the specified number interval added to the specified date_part of that date. For example, adding three months or 12 days to a starting date. |
| Example |
Push out all due dates by one week DATEADD('week', 1, [due date])
Add 280 days to the date February 20, 2021 DATEADD('day', 280, #2/20/21#) = #November 27, 2021#
|
| Notes | Supports ISO 8601 dates. |
DATEDIFF
Returns the number of date parts (weeks, years, etc) between two dates.
| Syntax |
DATEDIFF(date_part, date1, date2, [start_of_week])
|
| Output | Integer |
| Definition | Returns the difference between date1 and date2 expressed in units of date_part. For example, subtracting the dates someone entered and left a band to see how long they were in the band. |
| Example |
Number of days between March 25, 1986 and February 20, 2021 DATEDIFF('day', #3/25/1986#, #2/20/2021#) = 12,751
How many months someone was in a band DATEDIFF('month', [date joined band], [date left band])
|
| Notes | Supports ISO 8601 dates. |
DATENAME
Returns the name of the specified date part as a discrete string.
| Syntax |
DATENAME(date_part, date, [start_of_week])
|
| Output | String |
| Definition | Returns date_part of date as a string. |
| Example |
DATENAME('year', #3/25/1986#) = "1986"
DATENAME('month', #1986-03-25#) = "March"
|
| Notes |
Supports ISO 8601 dates. A very similar calculation is DATEPART, which returns the value of the specified date part as a continuous integer. DATEPART can be faster because it is a numerical operation. By changing the attributes of the calculation’s result (dimension or measure, continuous or discrete) and the date formatting, the results of DATEPART and DATENAME can be formatted to be identical. An inverse function is DATEPARSE, which takes a string value and formats it as a date. |
DATEPARSE
Returns specifically formatted strings as dates.
| Syntax |
DATEPARSE(date_format, [date_string])
|
| Output | Date |
| Definition | The date_format argument will describe how the [string] field is arranged. Because of the variety of ways the string field can be ordered, the date_format must match exactly. For a full explanation, see Convert a Field to a Date Field. |
| Example |
DATEPARSE('yyyy-MM-dd', "1986-03-25") = #March 25, 1986#
|
| Notes |
DATE is a similar function that automatically recognizes many standard date formats. DATEPARSE may be a better option if DATE does not recognize the input pattern. MAKEDATE is another similar function, but MAKEDATE requires the input of numeric values for year, month, and day. Inverse functions, which take dates apart and return the value of their parts, are DATEPART (integer output) and DATENAME (string output). |
| Database limitations |
DATEPARSE is available through the following connectors: non-legacy Excel and text file connections, Amazon EMR Hadoop Hive, Cloudera Hadoop, Google Sheets, Hortonworks Hadoop Hive, MapR Hadoop Hive, MySQL, Oracle, PostgreSQL, and Tableau extracts. Some formats may not be available for all connections. DATEPARSE is not supported on Hive variants. Only Denodo, Drill, and Snowflake are supported. |
DATEPART
Returns the name of the specified date part as an integer.
| Syntax |
DATEPART(date_part, date, [start_of_week])
|
| Output | Integer |
| Definition | Returns date_part of date as an integer. |
| Example |
DATEPART('year', #1986-03-25#) = 1986
DATEPART('month', #1986-03-25#) = 3
|
| Notes |
Supports ISO 8601 dates. A very similar calculation is DATENAME, which returns the name of the specified date part as a discrete string. DATEPART can be faster because it is a numerical operation. By changing the attributes of the field (dimension or measure, continuous or discrete) and the date formatting, the results of DATEPART and DATENAME can be formatted to be identical. An inverse function is DATEPARSE, which takes a string value and formats it as a date. |
DATETRUNC
This function can be thought of as date rounding. It takes a specific date and returns a version of that date at the desired specificity. Because every date must have a value for day, month, quarter, and year, DATETRUNC sets the values as the lowest value for each date part up to the date part specified. Refer to the example for more information.
| Syntax |
DATETRUNC(date_part, date, [start_of_week])
|
| Output | Date |
| Definition | Truncates the date to the accuracy specified by the date_part. This function returns a new date. For example, when you truncate a date that is in the middle of the month at the month level, this function returns the first day of the month. |
| Example |
DATETRUNC(‘day’, #9/22/2018#) = #9/22/2018# DATETRUNC(‘week’, #9/22/2018#) = #9/16/2018# (the sunday of the week containing 9/22/2018) DATETRUNC(‘iso-week’, #9/22/2018#) = #9/17/2018# (the monday of the week containing 9/22/2018) DATETRUNC(month, #9/22/2018#) = #9/1/2018# (the first day of the month containing 9/22/2018) DATETRUNC(quarter, #9/22/2018#) = #7/1/2018# (the first day of the quarter containing 9/22/2018) DATETRUNC(‘week’, #9/22/2018#) = #1/1/2018# (the first day of the year containing 9/22/2018) Note: For week and iso-week, the |
| Notes |
Supports ISO 8601 dates. You would not use DATETRUNC to, for example, stop showing the time for a datetime field in a viz. If you want to truncate the display of a date rather than round its accuracy, adjust the formatting. For example, |
DAY
Returns the day of the month (1-31) as an integer.
| Syntax |
DAY(date)
|
| Output | Integer |
| Definition | Returns the day of the given date as an integer. |
| Example |
Day(#September 22, 2018#) = 22 |
| Notes | See also WEEK, MONTH, QUARTER, YEAR, and the ISO equivalents |
ISDATE
Checks if the string is a valid date format.
| Syntax |
ISDATE(string)
|
| Output | Boolean |
| Definition | Returns true if a given string is a valid date. |
| Example |
ISDATE(09/22/2018) = true ISDATE(22SEP18) = false |
| Notes | The required argument must be a string. ISDATE cannot be used for a field with a date data type—the calculation will return an error. |
MAKEDATE
| Syntax |
MAKEDATE(year, month, day)
|
| Output | Date |
| Definition | Returns a date value constructed from the specified year, month, and date. |
| Example |
MAKEDATE(1986,3,25) = #1986-03-25#
Note that incorrectly entered values will be adjusted into a date, such as
|
| Notes |
Available for Tableau Data Extracts. Check for availability in other data sources. MAKEDATE requires numerical inputs for the parts of a date. If your data is a string that should be a date, try the DATE function. DATE automatically recognizes many standard date formats. If DATE does not recognize the input try using DATEPARSE. |
MAKEDATETIME
| Syntax |
MAKEDATETIME(date, time)
|
| Output | Datetime |
| Definition | Returns a datetime that combines a date and a time. The date can be a date, datetime, or a string type. The time must be a datetime. |
| Example |
MAKEDATETIME("1899-12-30", #07:59:00#) = #12/30/1899 7:59:00 AM#
MAKEDATETIME([Date], [Time]) = #1/1/2001 6:00:00 AM# |
| Notes |
This function is available only for MySQL-compatible connections (which for Tableau are MySQL and Amazon Aurora). MAKETIME is a similar function available for Tableau Data Extracts and some other data sources. |
MAKETIME
| Syntax |
MAKETIME(hour, minute, second)
|
| Output | Datetime |
| Definition | Returns a date value constructed from the specified hour, minute, and second. |
| Example |
MAKETIME(14, 52, 40) = #1/1/1899 14:52:40# |
| Notes |
Because Tableau does not support a time data type, only date time, the output is a a datetime. The date portion of the field will be 1/1/1899. Similar function to MAKEDATETIME, which is only available for MYSQL-compatible connections. |
MAX
| Syntax |
MAX(expression) or MAX(expr1, expr2) |
| Output | Date (see notes) |
| Definition | MAX is usually applied to numbers but also works on dates. Returns the maximum (most recent) of a date field or two dates. |
| Example |
MAX(#Sept 22, 2018#, #Feb 20, 2021#) = #Feb 20, 2021# MAX([Ship date]) |
| Notes |
Returns Null if any argument is Null. |
MIN
| Syntax |
MIN(expression) or MIN(expr1, expr2) |
| Output | Date (see notes) |
| Definition | MIN is usually applied to numbers but also works on dates. Returns the minimum (earliest) of a date field or two dates. |
| Example |
MIN(#Sept 22, 2018#, #Feb 20, 2021#) = #Sept 22, 2018# MIN(Ship date]) |
| Notes |
Returns Null if any argument is Null. |
MONTH
| Syntax |
MONTH(date)
|
| Output | Integer |
| Definition | Returns the month of the given date as an integer. |
| Example |
MONTH(#1986-03-25#) = 3 |
| Notes | See also DAY, WEEK, QUARTER, YEAR, and the ISO equivalents. |
NOW
| Syntax |
NOW()
|
| Output | Datetime |
| Definition | Returns the current local system date and time. |
| Example |
NOW() = 1986-03-25 1:08:21 PM |
| Notes |
NOW does not take an argument. See also TODAY, a similar calculation that returns a date instead of a datetime. If the data source is a live connection, the system date and time could be in another timezone. For more information on how to address this, see the Knowledge Base. |
QUARTER
| Syntax |
QUARTER(date)
|
| Output | Integer |
| Definition | Returns the quarter of the given date as an integer. |
| Example |
QUARTER(#1986-03-25#) = 1 |
| Notes | See also DAY, WEEK, MONTH, YEAR, and the ISO equivalents. |
TODAY
| Syntax |
TODAY()
|
| Output | Date |
| Definition | Returns the current local system date. |
| Example |
TODAY() = 1986-03-25 |
| Notes |
TODAY does not take an argument. See also NOW, a similar calculation that returns a datetime instead of a date. If the data source is a live connection, the system date could be in another timezone. For more information on how to address this, see the Knowledge Base. |
WEEK
| Syntax |
WEEK(date)
|
| Output | Integer |
| Definition | Returns the week of the given date as an integer. |
| Example |
WEEK(#1986-03-25#) = 13 |
| Notes | See also DAY, MONTH, QUARTER, YEAR, and the ISO equivalents. |
YEAR
| Syntax |
YEAR(date)
|
| Output | Integer |
| Definition | Returns the year of the given date as an integer. |
| Example |
YEAR(#1986-03-25#) = 1,986 |
| Notes | See also DAY, WEEK, MONTH, QUARTER, and the ISO equivalents. |
ISOQUARTER
| Syntax |
ISOQUARTER(date)
|
| Output | Integer |
| Definition | Returns the ISO8601 week-based quarter of a given date as an integer. |
| Example |
ISOQUARTER(#1986-03-25#) = 1 |
| Notes | See also ISOWEEK, ISOWEEKDAY, ISOYEAR, and the non-ISO equivalents. |
ISOWEEK
| Syntax |
ISOWEEK(date)
|
| Output | Integer |
| Definition | Returns the ISO8601 week-based week of a given date as an integer. |
| Example |
ISOWEEK(#1986-03-25#) = 13 |
| Notes | See also ISOWEEKDAY, ISOQUARTER, ISOYEAR, and the non-ISO equivalents. |
ISOWEEKDAY
| Syntax |
ISOWEEKDAY(date)
|
| Output | Integer |
| Definition | Returns the ISO8601 week-based weekday of a given date as an integer. |
| Example |
ISOWEEKDAY(#1986-03-25#) = 2 |
| Notes | See also ISOWEEK, ISOQUARTER, ISOYEAR, and the non-ISO equivalents |
ISOYEAR
| Syntax |
ISOYEAR(date)
|
| Output | Integer |
| Definition | Returns the ISO8601 week-based year of a given date as an integer. |
| Example |
ISOYEAR(#1986-03-25#) = 1,986 |
| Notes | See also ISOWEEK, ISOWEEKDAY, ISOQUARTER, and the non-ISO equivalents. |
The date_part argument
Many date functions in Tableau take the argument date_part, which is a string constant that tells the function what part of a date to consider, such as day, week, quarter, etc.
The valid date_part values that you can use are:
| date_part | Values |
|---|---|
'year'
|
Four-digit year |
'quarter'
|
1-4 |
'month'
|
1-12 or "January", "February", and so on |
'dayofyear'
|
Day of the year; Jan 1 is 1, Feb 1 is 32, and so on |
'day'
|
1-31 |
'weekday'
|
1-7 or "Sunday", "Monday", and so on |
'week'
|
1-52 |
'hour'
|
0-23 |
'minute'
|
0-59 |
'second'
|
0-60 |
'iso-year'
|
Four-digit ISO 8601 year |
'iso-quarter'
|
1-4 |
'iso-week'
|
1-52, start of week is always Monday |
'iso-weekday'
|
1-7, start of week is always Monday |
The [start_of_week] parameter
Some functions have the optional parameter [start_of_week]. The start_of_week parameter can be used to specify what day is considered the first day of the week, such as "Sunday" or "Monday". If it is omitted, the start of week is determined by the data source. See Date Properties for a Data Source.
For the examples below, 22 September is a Sunday and 24 September is a Tuesday. The DATEDIFF function is being used to calculate the weeks between these dates.
DATEDIFF('week', #2013-09-22#, #2013-09-24#, 'monday') = 1
- Because start_of_week is 'monday', these dates are in different weeks.
DATEDIFF('week', #2013-09-22#, #2013-09-24#, 'sunday') = 0
- Because start_of_week is 'sunday', these dates are in the same week.
The date literal (#)
Examples often use the pound symbol (#) with date expressions. This is the date literal, similar to using quotes for text strings, and it tells Tableau that the value inside the symbols is a date.
Without the date literals, dates may be interpreted as various other data types. For example:
| Format | Data Type | Value |
| 'March 25, 1986' | String | 'March 25, 1986' |
| #3/25/1986# | Date | #3/25/1986# |
| 03/25/1986 | Floating decimal | 0.00006042 |
| 1986-03-25 | Integer | 1,958 |
| March 25, 1986 | invalid |
For more information, see Literal expression syntax
Create a date calculation
Practice creating a date calculation using the Superstore sample data source.
- In Tableau Desktop, connect to the Sample-Superstore saved data source, which comes with Tableau.
- Open a worksheet.
- From the Data pane, under Dimensions, drag Order Date to the Rows shelf.
-
On the Rows shelf, click the plus icon (+) on the YEAR(Order Date) field.
QUARTER(Order Date) is added to the Rows shelf and the view updates.
-
On the Rows shelf, click the plus icon (+) on the QUARTER(Order Date) field to drill down to MONTH(Order Date).
- Select Analysis > Create Calculated Field.
- In the calculation editor that opens, do the following:
- Name the calculated field, Quarter Date.
-
Enter the following formula:
DATETRUNC('quarter', [Order Date]) -
When finished, click OK.
The new date calculated field appears under Dimensions in the Data pane. Just like your other fields, you can use it in one or more visualizations.
- From the Data pane, under Dimensions, drag Quarter Date to the Rows shelf and place it to the right of MONTH(Order Date). The visualization updates with year values. This is because Tableau rolls date data up to the highest level of detail.
- On the Rows shelf, right-click YEAR(Quarter Date) and select Exact Date.
-
On the Rows shelf, right-click YEAR(Quarter Date) again and select Discrete.
The visualization updates with the exact quarter date for each row in the table.
