# TalendDate routine

The TalendDate routine contains several functions which allow you to carry out different kinds of operations and checks concerning the format of Date expressions.

Information noteWarning: These functions internally use the Java class [SimpleDateFormat](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html#number) except when the pattern is set to yyyy-MM-dd or yyyy-MM-dd HH:mm:ss, where there is no check for the format of the input date string in order to achieve better performance. You need to make sure the input date string matches the set pattern precisely when using either of these two patterns.

You can access these functions by double-clicking the TalendDate node under the system routines folder in the Repository tree view.

Functions of the TalendDate routineFunctions of the TalendDateTalendDate routine

| Function | Description | Syntax |
| --- | --- | --- |
| addDate | Adds n days, n months, n hours, n minutes or n seconds to a Java date<br>and returns the new date.<br><br>The Date format is: yyyy,<br>MM, dd,<br>HH, mm,<br>ss or SSS. | TalendDate.addDate("initial date string", ["date format - eg.:<br>yyyy/MM/dd"], integer n,"format of the part of the date to which n is to<br>be added - eg.:yyyy"). |
| compareDate | Compares all or part of two dates according to the format specified.<br>Returns 0 if the dates are identical,<br>-1 if the first date is earlier and<br>1 if the second date is earlier.<br><br>The pattern parameter specifies the date format, for<br>example, "yyyy-mm-dd". | TalendDate.compareDate(Date date1, Date date2,[String<br>pattern]) |
| diffDate | Returns the difference between two dates in terms of years, months, days,<br>hours, minutes, seconds, or milliseconds according to the comparison<br>parameter specified.<br><br>The dateType parameter specifies the date part to be<br>compared. The valid values are: "yyyy",<br>"MM", "dd", "HH",<br>"mm", "ss", "SSS". The<br>default value is "dd".<br><br>The ignoreDST parameter specifies if DST needs to be taken<br>into consideration. | TalendDate.diffDate(Date date1, Date date2,[String<br>dateType],[boolean ignoreDST])<br><br>For example, TalendDate.diffDate(TalendDate.parseDate("yyyy-MM-dd",<br>"2022-12-01"), TalendDate.parseDate("yyyy-MM-dd", "2022-10-02"),<br>"MM") returns 2. |
| diffDateFloor | Returns the difference between two dates in terms of years or months<br>according to the comparison parameter specified. The value is rounded down<br>to the nearest integer.<br><br>The dateType parameter specifies the date part to be<br>compared. The valid values are: "yyyy",<br>"MM". | TalendDate.diffDateFloor(Date date1, Date date2, String<br>dateType)<br><br>For example,<br>TalendDate.diffDateFloor(TalendDate.parseDate("yyyy-MM-dd",<br>"2022-12-01"), TalendDate.parseDate("yyyy-MM-dd", "2022-10-02"),<br>"MM") returns 1. |
| diffDateIgnoreDST | Returns the difference between two dates in terms of days, months or years<br>according to the comparison parameter specified, ignoring the DST.<br><br>The dateType parameter specifies the format of the date<br>part to be compared, for example, "yyyy". | TalendDate.diffDateIgnoreDST(Date1(), Date2(),[String<br>dateType]) |
| formatDate | Returns a date string which corresponds to the format specified. | TalendDate.formatDate("date format - eg.: yyyy-MM-dd<br>HH:mm:ss", Date() to be formatted) |
| formatDateInTimeZone | Formats a date into the specified format date/time string under the given<br>timezone. | TalendDate.formatDateInTimeZone(String datePattern, Date tate,<br>String TimeZoneID) |
| formatDateInUTC | Formats a date into the specified format date/time string under the UTC<br>timezone. | TalendDate.formatDateInUTC(String datePattern, Date tate, String<br>TimeZoneID) |
| formatDateLocale | Changes a date into a date/hour string according to the format used<br>in the target country. | TalendDate.formatDateLocale("format target", java.util.Date date,<br>"language or country code") |
| formatDatetimeoffset | Formats date to MSSQL 2008 type datetimeoffset ISO 8601 string with local<br>time zone format string: yyyy-MM-dd HH:mm:ss.SSSXXX (JDK7 support it). | TalendDate.formatDatetimeoffset(Date date) |
| getCurrentDate | Returns the current date. No entry parameter is required. | TalendDate.getCurrentDate() |
| getDate | Returns the current date and hour in the format specified (optional).<br>This string can contain fixed character strings or variables linked<br>to the date. By default, the string is returned in the format of<br>DD/MM/CCYY. | TalendDate.getDate("Format of the string - ex:<br>CCYY-MM-DD") |
| getFirstDayOfMonth | Changes the date of an event to the first day of the current month<br>and returns the new date. | TalendDate.getFirstDayMonth(Date) |
| getLastDayOfMonth | Changes the date of an event to the last day of the current month and<br>returns the new date. | TalendDate.getLastDayMonth(Date) |
| getPartOfDate | Returns part of a date according to the format specified. This string<br>can contain fixed character strings or variables linked to the<br>date. | TalendDate.getPartOfDate("String indicating the part of the<br>date to be retrieved, "String in the format of the date to be<br>parsed") |
| getRandomDate | Returns a random date, in the ISO format. | TalendDate.getRandomDate("format date of the character<br>string", String minDate, String maxDate) |
| isDate | Checks whether the date string corresponds to the format specified.<br>Returns the boolean value true or false according to the<br>outcome. | TalendDate.isDate(Date() to be checked, String<br>pattern, [boolean<br>ignoreTimeZone])<br><br>where, pattern specifies the format of the date to be<br>checked. For example, yyyy-MM-dd HH:mm:ss. |
| isDateStrict | Tests string value as a date with right pattern using strict rules. This<br>validation uses Java 8 time tools. The range of time-zone offsets is<br>restricted to -18:00 to 18:00 inclusive. Returns a boolean value indicating<br>whether the stringDate is a date string with a right pattern. | TalendDate.isDateStrict(String stringDate, String pattern) |
| parseDate | Changes a string into a Date. Returns a date in the specified format. | TalendDate.parseDate("format date of the string to be parsed",<br>"string in the format of the date to be parsed",["boolean about whether<br>parsing is set to be lenient, that is to say, accepting the heuristic<br>match with the format"]) |
| parseDateInUTC | changes a string into a Date in UTC. Returns a date in the UTC<br>format.<br><br><ul>Available in:<li>Big Data</li><li>Big Data Platform</li><li>Cloud Big Data</li><li>Cloud Big Data Platform</li><li>Cloud Data Fabric</li><li>Data Fabric</li><li>Qlik Cloud Enterprise Edition</li><li>Qlik Talend Cloud Enterprise Edition</li><li>Qlik Talend Cloud Premium Edition</li><li>Real-Time Big Data Platform</li></ul><br><br>In a Big Data Job running in a<br>production environment, as multiple machines are involved from different<br>time zones, you need always use this routine to guarantee the correct output<br>of date/time parsing. | TalendDate.parseDateInUTC("format date of the string to be parsed",<br>"string in the format of the date to be parsed", ["boolean about whether<br>parsing is set to be lenient, that is to say, accepting the heuristic<br>match with the format"]) |
| parseDateLocale | Parses a string according to a specified format and extracts the date.<br>Returns the date according to the local format specified. | TalendDate.parseDateLocale("date format of the string to be<br>parsed", "String in the format of the date to be parsed", "code<br>corresponding to the country or language") |
| setDate | Modifies part of a date according to the part and value of the date<br>specified and the format specified. | TalendDate.setDate(Date, whole n, "format of the part of the<br>date to be modified - eg.:yyyy") |
| TO\_CHAR | Converts a date to a character string. | TalendDate.TO\_CHAR(date[,format])<br><br><ul> <li> <span>date</span>: the date value you want to convert to a character									string.</li> <li> <span>format</span>: the string which defines the format of the return									value.</li> </ul> |
| TO\_DATE | Converts a character string to a Date/Time datatype. | TalendDate.TO\_DATE(string[, format])<br><br><ul> <li> <span>string</span>: the string you want to convert to a Date/Time									datatype.</li> <li> <span>format</span>: the format string that matches the part of the										<span>string</span> argument. If not specified, the										<span>string</span> value must be in the date format										<span>MM/dd/yyyy HH:mm:ss.SSS</span>.</li> </ul><br><br>For example, TalendDate.TO\_DATE("04/24/2017<br>13:55:42.123") will return Mon Apr 24 13:55:42<br>CST 2017. |
| ADD\_TO\_DATE | Adds a specified amount to one part of a datetime value, and returns<br>a date in the same format as the date you pass to the function. | TalendDate.ADD\_TO\_DATE(date, format, amount)<br><br><ul> <li> <span>date</span>: the date value you want to change.</li> <li> <span>format</span>: the format string specifying the portion of the date value									you want to change.<ul> <li>Valid format strings for year: <span>Y</span>,												<span>YY</span>, <span>YYY</span>, and												<span>YYYY</span>.</li> <li>Valid format strings for month: <span>MONTH</span>,												<span>MM</span>, and <span>MON</span>.</li> <li>Valid format strings for day: <span>D</span>,												<span>DD</span>, <span>DDD</span>,												<span>DAY</span>, and <span>DY</span>.</li> <li>Valid format strings for hour: <span>HH</span>,												<span>HH12</span>, and											<span>HH24</span>.</li> <li>Valid format string for minute:											<span>MI</span>.</li> <li>Valid format string for second: <span>SS</span>.</li> <li>Valid format string for millisecond:											<span>MS</span>.</li> </ul> </li> <li> <span>amount</span>: the integer value specifying the amount of years, months,									days, hours, and so on by which you want to change the date									value.</li> </ul><br><br>For example,<br><br>if TalendDate.getCurrentDate() returns Mon<br>Apr 24 14:26:03 CST 2017,<br><br><br>TalendDate.ADD\_TO\_DATE(TalendDate.getCurrentDate(), "YY",<br>1) will return Tue Apr 24 14:26:03 CST<br>2018. |

Information noteWarning:

Although "yyyy" and "YYYY" in the date format return the same year number in most cases, "YYYY" may not work as expected when used:

* at the first week of a year if the year does not start by the first day of the week.
* at the last week of a year if the year does not end by the last day of the week.

For example, when calculating what date it is 3 days before January 2, 2016, the code below would return a wrong date:

```
System.out.println(TalendDate.formatDate("YYYY-MM-dd", TalendDate.addDate(TalendDate.TO_DATE("01/02/2016 08:10:30.123"), -3, "dd")));
```

while the following code would work as expected:

```
System.out.println(TalendDate.formatDate("yyyy-MM-dd", TalendDate.addDate(TalendDate.TO_DATE("01/02/2016 08:10:30.123"), -3, "dd")));
```

Therefore, you should typically use "yyyy", which represents calendar year.

## Formatting a Date

The formatDate routine is easy to use, along with a tJava component:

```
System.out.println(TalendDate.formatDate("dd-MM-yyyy", new Date()));
```

The current date is initialized according to the pattern specified by the new Date() Java function and is displayed in the Run view:

![The result is 2010-02-25 17:28:07 in the Run view.](https://help.qlik.com/talend/en-US/studio-user-guide/Resources/images/routines14_b.png)

## Checking a Date

It is easy to use the isDate routine, along with a tJava component to check if a date expression is in the format specified:

```
System.out.println(TalendDate.isDate("2010-02-09 00:00:00",
               "yyyy-MM-dd HH:mm:ss"));
```

A boolean is returned in the Run view:

![The result is "true" in the Run view.](https://help.qlik.com/talend/en-US/studio-user-guide/Resources/images/routines14_c.png)

## Comparing Dates

It is easy to use the compareDate routine, along with a tJava component to compare two dates, for example, to check if a date is identical to, earlier than, or later than a specific date, according to the format specified. This routine takes two parameters (the two dates) and returns one of the following three values.

* -1: the first date is earlier than the second date.
* 0: the first date is identical to the second date.
* 1: the first date is later than the second date.

The following gives an example of using this routine.

```
System.out.println(TalendDate.compareDate(TalendDate.parseDate("yyyy-MM-dd", "2015/11/24"), TalendDate.parseDate("yyyy-MM-dd", "2025/11/24")));
```

This example compares the two dates: 2015/11/24 and 2025/11/24 and returns the value -1 in the Run view, indicating that the first date is earlier than the second date.

![The result is -1 in the Run view.](https://help.qlik.com/talend/en-US/studio-user-guide/Resources/images/routines14_d.png)

## Configuring a Date

It is easy to use the setDate routine, along with a tJava component to change the year of the current date, for example:

```
System.out.println(TalendDate.formatDate("yyyy/MM/dd HH:mm:ss",new Date()));
                  System.out.println(TalendDate.setDate(new Date(),2011,"yyyy"));
```

The current date, followed by the new date are displayed in the Run view:

![The result is 2010/02/26 18:03:14 and then Sat Feb 26 18:03:14 CET 2011 in the Run view.](https://help.qlik.com/talend/en-US/studio-user-guide/Resources/images/routines14_e.png)

## Parsing a Date

It is easy to use the parseDate routine, along with a tJava component to change a date string from one format into another date format, for example:

```
System.out.println(TalendDate.parseDate("yyyy-MM-dd HH:mm:ss",
                  "1979/10/20 19:00:59"));
```

The string is changed and returned in the date format:

![The result is Sat Oct 20 19:00:59 CET 1979 in the Run view.](https://help.qlik.com/talend/en-US/studio-user-guide/Resources/images/routines14_f.png)

## Retrieving part of a Date

It is easy to use the getPartOfDate routine, along with a tJava component to retrieve part of a date, for example:

```
Date D=TalendDate.parseDate("dd-MM-yyyy HH:mm:ss", "13-10-2010 12:23:45");
               System.out.println(D.toString());
               System.out.println(TalendDate.getPartOfDate("DAY_OF_MONTH", D));
               System.out.println(TalendDate.getPartOfDate("MONTH", D));
               System.out.println(TalendDate.getPartOfDate("YEAR", D));
               System.out.println(TalendDate.getPartOfDate("DAY_OF_YEAR", D));
               System.out.println(TalendDate.getPartOfDate("DAY_OF_WEEK", D));
```

In this example, the day of month (DAY\_OF\_MONTH), the month (MONTH), the year (YEAR), the day number of the year (DAY\_OF\_YEAR) and the day number of the week (DAY\_OF\_WEEK) are returned in the Run view. All the returned data are numeric data types.

![The result is Wed Oct 13 12:23:45 CEST 2010, and then 13, 9, 2010, 286, and 4 in the Run view.](https://help.qlik.com/talend/en-US/studio-user-guide/Resources/images/routinesGetPartOfDateresult.png)

Information noteNote: In the Run view, the date string referring to the months (MONTH) starts with 0 and ends with 11: 0 corresponds to January, 11 corresponds to December.

## Formatting the Current Date

It is easy to use the getDate routine, along with a tJava component, to retrieve and format the current date according to a specified format, for example:

```
System.out.println(TalendDate.getDate("CCYY-MM-DD"));
```

The current date is returned in the specified format (optional):

![The result is 2010-03-02 in the Run view.](https://help.qlik.com/talend/en-US/studio-user-guide/Resources/images/routines14_g.png)