Date Functions and Properties

In this Page

Dates function similarly to Javascript Date objects in which a Date represents the number of milliseconds since midnight January 1, 1970 UTC.

Timestamp formats may differ across different database or APIs. Migrating date information may have unintended results if those differences are not taken into consideration. Time zone settings between Cloudplex and Groundplex might differ since Cloudplex may be in UTC, while a Groundplex could be in a local time zone.

Comparing Dates

Dates can be compared using the relational operators (>, >=, <, <=, ==). For example:

Date.parse("2011-10-10T14:48:00.123-08:00") > Date.parse("2011-10-10T12:48:00.123-08:00") // true
 
// The following is true because a Date is a number of milliseconds since midnight January 1, 1970 UTC
Date.parse("2011-10-10T15:48:00.123-08:00") > 1318286880123


The following methods from JavaScript are implemented for Date objects according to local time unless noted otherwise.

now

Description

Returns the current datetime as YYYY-MM-DDTHH:mm:ss.SSS UTCThe results are of the date-time data type.

This is similar to the JavaScript now.

Syntax
Date.now()
Example

Expression: Date.now()

Result: 2017-02-21T21:34:22.025 UTC

parse

Description

Parses a string representation of a date, and returns it as YYYY-MM-DDTHH:mm:ss.SSS that matches the server's timezone. The results are of the date-time data type.

This is similar to the JavaScript parse.

Syntax
Date.parse(dateString)

This method has the following extensions from the standard:

  • parse(millisFromEpoch) - Return a date object that is initialized with the given number of milliseconds from the epoch. If the parameter to parse() is a number, it will be treated as the number of milliseconds from the epoch (Jan 1, 1970) and a new date object will be created and initialized with that value.
  • parse(dateStringformat) - Parse a date string using a custom format. The second argument is a format string using the same syntax as the Java SimpleDateFormat class.
  • parse(dateNumber, format) - Parse a number as a date using a custom format. The second argument is a format string using the same syntax as the Java SimpleDateFormat class. The number converts to a string and parsed using the given format.
Example

Expression: Date.parse(1445910469510)

Result: 2015-10-27T01:47:49.510 (in the server's timezone)


Expression: Date.parse("2011 10 30", "yyyy MM dd")

Result: 2011-10-30T00:00:00.000 (in the server's timezone)


Expression: Date.parse ($['System Modstamp'],"MM/dd/yyyy'T'HH:mm:ss.SSS'Z'")

Result: 2015-04-15T13:23:10.000 (in the server's timezone)


Expression: Date.parse(20160923, “yyyyMMdd”)

Result: 2016-09-23T00:00:00.000 (in the server's timezone)

UTC

Description

Returns the date/time in universal time. The results are of the date-time data type.

This is similar to the JavaScript UTC.

Syntax
Date.UTC(year, month, [day, hour, minute, second, millisecond])

where:

  • year is a year after 1900.
  • month is an integer between 0 and 11 representing the month.
  • day is an optional integer between 1 and 31 representing the day of the month.
  • hour is an optional integer between 0 and 23 representing the hours.
  • minute is an optional integer between 0 and 59 representing the minutes.
  • second is an optional integer between 0 and 59 representing the seconds.
  • millisecond is an optional integer between 0 and 999 representing the milliseconds.
Example

Expression: Date.UTC(2015, 7, 20, 13, 23, 12, 34)

Result: 2015-08-20T13:23:12.034 UTC

LocalDateTime.parse()

DescriptionReturns the date in local time.
Syntax
LocalDateTime.parse(_Input_Date)
Example

Expression: LocalDateTime.parse("2011-10-31")

Result: 2011-10-31T00:00:00.000

LocalDate.parse()

DescriptionReturns the date in local time.
Syntax
LocalDate.parse(_Input_Date)
Example

Expression: LocalDate.parse("2011/10/31")

Result: 2011-10-31

LocalTime.parse()

DescriptionReturns the date in local time.
Syntax
LocalTime.parse(_Input_Time)
Example

Expression: LocalTime.parse("23:42:00")

Result: 23:42:00.000

Getter Methods

getDate

Description

Returns the day of the month for the specified date as an integer between 1 and 31.

This is similar to the JavaScript getDate

Syntax
dateobject.getDate()
Example

Expression: Date.parse("2014-09-22").getDate()

Result: 22

getDay

Description

Returns the day of the week for the specified date as an integer, where 0 represents Sunday.

This is similar to the JavaScript getDay 

Syntax
dateobject.getDay()
Example

Expression: Date.parse("2014-09-22").getDay() 

Result: 1 (indicating Monday)

getFullYear

DescriptionThis is similar to the JavaScript getFullYear - returns the year of the specified date as an integer.
Syntax
dateobject.getFullYear()
Example

Expression: Date.now().getFullYear()

Result: 2017

getHours

DescriptionThis is similar to the JavaScript getHours - returns the hour for the specified date as an integer between 0 and 23.
Syntax
dateobject.getHours()
Example

Expression: Date.now().getHours()

Result: 21

getMilliseconds

Description

This is similar to the JavaScript getMilliseconds - returns the milliseconds in the specified date as an integer.

Syntax
dateobject.getMilliseconds()
Example

Expression: Date.now().getMilliseconds()

Result: 125

getMinutes

DescriptionThis is similar to the JavaScript getMinutes - returns the minutes in the specified date.
Syntax
dateobject.getMinutes()
Example

Expression: Date.now().getMinutes()

Result: 34

getMonth

DescriptionReturns the month in the specified date as an integer between 1 (January) and 12 (December). This is different from the JavaScript getMonth in that this returns months starting from 1 instead of 0.
Syntax
dateobject.getMonth()
Example

ExpressionDate.parse("2019-03-04T17:32:53.077 UTC").getMonth()

Result: 3

getMonthfromZero

DescriptionReturns the month in the specified date as an integer between 0 (January) and 11 (December). Unlike getMonth, this expression is similar to the JavaScript getMonth.
Syntax
dateobject.getMonthFromZero()
Example

ExpressionDate.parse("2019-03-04T17:32:53.077 UTC").getMonthFromZero()

Result: 2

getUTCMonthfromZero

DescriptionReturns the month according to UTC in the specified date as an integer between 0 (January) and 11 (December). This expression is similar to the JavaScript getUTCMonth.
Syntax
dateobject.getUTCMonthfromZero()
Example

ExpressionDate.parse("2019-03-04T17:32:53.077 UTC").getUTCMonthFromZero()

Result: 11, 0

getSeconds

DescriptionThis is similar to the JavaScript getSeconds - returns the seconds in the specified date as an integer between 0 and 59.
Syntax
dateobject.getSeconds()
Example

Expression: Date.now().getSeconds()

Result: 22

getTime

DescriptionThis is similar to the JavaScript getTime - returns the numeric value corresponding to the time for the specified date according to universal time as the number of milliseconds since 1 January 1970 00:00:00 UTC (epoch time). 
Syntax
dateobject.getTime()
Example

Expression: Date.now().getTime()

Result: 1487712862069

getUTCDate

Description

Converts the specified time to its corresponding UTC time

Syntax
dateobject.getUTCDate()
Example

Expression: Date.parse("2019-03-04T17:32:53.077").getUTCDate()

Result: 4

getUTCFullYear

Description

Retrieves the year component from the specified date, according to UTC. Values range from 1000 to 9999

Syntax
dateobject.getUTCFullYear()
Example

Expression: Date.parse("2019-03-04T17:32:53.077").getUTCFullYear()

Result: 2019

getUTCMonth

Description

Retrieves the month component from the specified time, according to UTC. Values range from 1 (January) to 12 (December).

Syntax
dateobject.getUTCMonth()
Example

Expression: Date.parse("2019-03-04T17:32:53.077").getUTCMonth()

Result: 3

getUTCDay

Description

Returns the day of the week for the specified date, according to UTC. Values range from 0 (Sunday) to 6 (Saturday).

Syntax
dateobject.getUTCDay()
Example

Expression: Date.parse("2019-03-04T17:32:53.077").getUTCDay()

Result: 1 (Monday)

getUTCHours

Description

Returns the hour component from the specified date, according to UTC. Values range from 0 to 23.

Syntax
dateobject.getUTCHours()
Example

Expression: Date.parse("2019-03-04T17:32:53.077").getUTCHours()

Result: 17

getUTCMinutes

Description

Returns the minute component from the specified date, according to UTC. Values range from 0 to 59.

Syntax
dateobject.getUTCMinutes()
Example

Expression: Date.parse("2019-03-04T17:32:53.077").getUTCMinutes()

Result: 32

getUTCSeconds

Description

Returns the second component from the specified date, according to UTC. Values range from 0 to 59.

Syntax
dateobject.getUTCSeconds()
Example

Expression: Date.parse("2019-03-04T17:32:53.077").getUTCSeconds()

Result: 53

getUTCMilliseconds

Description

Returns the millisecond component from the specified date, according to UTC. Values range from 0 to 999.

Syntax
dateobject.getUTCMilliseconds()
Example

Expression: Date.parse("2019-03-04T17:32:53.077").getUTCMilliseconds()

Result: 77

getTimezoneOffset

Description

Returns the time difference (in minutes) between the specified time and the UTC time.

Syntax
dateobject.getTimezoneOffset()
Example

Expression: Date.parse("2019-03-04T17:32:53.077").getTimezoneOffset()

Result: 0

Conversion Getter Methods

toString

Description

Returns a string representing the specified Date object.

This is similar to the JavaScript toString.

Syntax
dateobject.toString()
Example

Expression: Date.parse("2014-09-22").toString()

Result: 2014-09-22T00:00:00.000Z

toLocaleString

Description

Returns a string with a language-sensitive representation of the date and time. You can specify the formatting conventions of a given language that should be used and customize the behavior of the function. See Database Date Types for compatible date-related formats when data comes from a database.

The argument to this method is an object containing the following options that control the format of the returned string:

  • format: Describes the format of the returned string. See the Joda DateTimeFormat documentation for the full details.
  • timeZone: Specifies the target time zone. Use the Canonical ID value from Joda-Time.
  • locale: Specifies the language tag.  

This is similar to the JavaScript toLocaleString.

Syntax
dateobject.toLocaleString()
Example

Expressions

Date.now().toLocaleString({"locale":"ar-EG"})

Date.now().toLocaleString({"locale":"fa-IR"})

Date.now().toLocaleString({"locale":"en-US"})

Result: 

toLocaleDateString

Description

Returns a string with a language sensitive representation of the date portion of this date. See Database Date Types for compatible date-related formats when data comes from a database.

The argument to this method is an object containing the following options that control the format of the returned string:

  • format - Describes the format of the returned string. See the Joda DateTimeFormat documentation for the full details.
  • timeZone - Specifies the target time zone. Use the Canonical ID value from Joda-Time.
  • locale: Specifies the language tag.

Earlier versions of this method would accept a JSON-encoded string as the options object. However, due to the performance impact of parsing this string, it is recommended that an object literal be used to pass the options instead. If your Pipeline passes a string argument, a warning will be raised during execution.

This is similar to the JavaScript toLocaleDateString.

Syntax
dateobject.toLocaleDateString()
Example

Expression: Date.now().toLocaleDateString()

Result: 2014-09-22


Expression: Date.now().toLocaleDateString({"format":"MM-dd-yyyy"})

Result: 09-22-2014


Expression

Date.now().toLocaleDateString({"locale":"ar-EG"})

Date.now().toLocaleDateString({"locale":"fa-IR"})

Date.now().toLocaleDateString({"locale":"en-US"})


Result

toLocaleDateTimeString

Description

Returns a string with a language sensitive representation of the time portion of this date. See Database Date Types for compatible date-related formats when data comes from a database.

The argument to this method is an object containing the following options that control the format of the returned string:

  • format: Describes the format of the returned string. See the Joda DateTimeFormat documentation for the full details.
  • timeZone: Specifies the target time zone. Use the Canonical ID value from Joda-Time.
  • locale: Specifies the language tag.

Earlier versions of this method would accept a JSON-encoded string as the options object. However, due to the performance impact of parsing this string, it is recommended that an object literal be used to pass the options instead. If your pipeline passes a string argument, a warning will be raised during execution.

This is similar to the JavaScript toLocaleDateTimeString.

Syntax
dateobject.toLocaleDateTimeString()
Example

Expression: Date.parse("2014-09-22").toLocaleDateTimeString()

Result: 2014-09-22T00:00:00.000


Expression:

Date.parse("2016-03-17T16:23:59.825").toLocaleDateTimeString({"timeZone":"US/Eastern", "format":"yyyy-MM-dd HH:mm"})

Result: 2016-03-17 04:23 PM

For the {"timeZone":"zoneValue"} option, you can use the Canonical ID value from Joda-Time.


Expression

Date.now().toLocaleDateTimeString({"locale":"ar-EG"})

Date.now().toLocaleDateTimeString({"locale":"fa-IR"})

Date.now().toLocaleDateTimeString({"locale":"en-US"})

Result


toLocaleTimeString

Description

Returns a string with a language sensitive representation of the time portion of this date. See Database Date Types for compatible date-related formats when data comes from a database.

The argument to this method is an object containing the following options that control the format of the returned string:

  • format - Describes the format of the returned string. See the Joda DateTimeFormat documentation for the full details.
  • timeZone - Specifies the target time zone. Use the Canonical ID value from Joda-Time.
  • locale: Specifies the language tag.

Earlier versions of this method would accept a JSON-encoded string as the options object. However, due to the performance impact of parsing this string, it is recommended that an object literal be used to pass the options instead. If your pipeline passes a string argument, a warning will be raised during execution.

This is similar to the JavaScript toLocaleTimeString.

Date objects do not support the standard setter methods since they are immutable. Instead, you can use the methods described in the next section to produce a new Date object after adding, subtracting, or replacing one of the fields in the object.



Syntax
dateObject.toLocaleTimeString()


Example

Expression: Date.parse("2014-09-22").toLocaleTimeString()

Result: 00:00:00.000


Expression

Date.now().toLocaleTimeString({"locale":"ar-EG"})

Date.now().toLocaleTimeString({"locale":"fa-IR"})

Date.now().toLocaleTimeString({"locale":"en-US"})

Result



Date Class Extensions

In addition to the above methods, Date objects implement the following methods from the Joda-Time Java library. "Plus" items increase the indicated datetime element by the specified value, "minus" items subtract by the specified value, and "with" replaces the existing data with the specified value.

toLocaleDateString

Description

Format the date using the given format as described in an object.

Syntax
$datetime.toLocaleDateString(format)
Example

Expression: 'JS_SomeFile' + Date.now().toLocaleDateTimeString({"format":"yyyyMMddhhmmss"}) + '.json'

Result: JS_SomeFile20171106112401.json

plus

Description

Returns a copy of this datetime with the specified duration added. 

This is similar to the JavaScript plus.

Syntax
$datetime.plus(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

Expression: Date.now().plus(2)

Result: 2017-11-06T21:48:11.954 UTC 

(last digit increased by 2)


Expression: Date.now().plus(20)

Result2017-11-06T21:48:11.972 UTC

(second to last digit increased by 2)


Expression: Date.now().plus(2000)

Result2017-11-06T21:48:13.952 UTC

(fourth digit from the end increased by 2)

plusDays

Description

Returns a copy of this datetime plus the specified number of days. 

This is similar to the JavaScript plusDays.

Syntax
$datetime.plusDays(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

Expression: Date.now().plusDays(2)

Result: 2017-11-08T21:48:11.952 UTC

(day value increased by 2)

plusHours

Description

Returns a copy of this datetime plus the specified number of hours. 

This is similar to the JavaScript plusHours.

Syntax
$datetime.plusHours(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

Expression: Date.now().plusHours(2)

Result: 2017-11-06T23:48:11.952 UTC

(hour increased by 2)

plusMillis

Description

Returns a copy of this datetime plus the specified number of milliseconds.

This is similar to the JavaScript plusMillis.

Syntax
$datetime.plusMillis(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().plusMillis(2)

Result2017-11-06T21:48:11.954 UTC

(milliseconds increased by 2)

plusMinutes

Description

Returns a copy of this datetime plus the specified number of minutes. 

This is similar to the JavaScript plusMinutes.

Syntax
$datetime.plusMinutes(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().plusMinutes(2)

Result2017-11-06T21:50:11.952 UTC

(minutes increased by 2)

plusMonths

Description

Returns a copy of this datetime plus the specified number of months.

This is similar to the JavaScript plusMonths.

Syntax
$datetime.plusMonths(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().plusMonths(2)

Result2018-01-06T21:48:11.952 UTC

(date increased by 2 months)

plusSeconds

Description

Returns a copy of this datetime plus the specified number of seconds. 

This is similar to the JavaScript plusSeconds.

Syntax
$datetime.plusSeconds(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().plusSeconds(2)

Result2017-11-06T21:48:13.952 UTC

(time increased by 2 seconds)

plusWeeks

Description

Returns a copy of this datetime plus the specified number of weeks. 

This is similar to the JavaScript plusWeeks.

Syntax
$datetime.plusWeeks(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().plusWeeks(2)

Result2017-11-20T21:48:11.952 UTC

(date increased by 2 weeks)

plusYears

Description

Returns a copy of this datetime plus the specified number of years. 

This is similar to the JavaScript plusYears.

Syntax
$datetime.plusYears(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().plusYears(2)

Result2019-11-06T21:48:11.952 UTC

(year increased by 2)

minus

Description

Returns a copy of this datetime with the specified duration subtracted. 

This is similar to the JavaScript minus.

Syntax
$datetime.minus(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().minus(2)

Result2017-11-06T21:48:11.950 UTC

minusDays

Description

Returns a copy of this datetime minus the specified number of days. 

This is similar to the JavaScript minusDays.

Syntax
$datetime.minusDays(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().minusDays(2)

Result2017-11-04T21:48:11.952 UTC

(day reduced by 2)

minusHours

Description

Returns a copy of this datetime minus the specified number of hours. 

This is similar to the JavaScript minusHours.

Syntax
$datetime.minusHours(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().minusHours(2)

Result2017-11-06T19:48:11.952 UTC

(hours reduced by 2)

minusMillis

Description

Returns a copy of this datetime minus the specified number of milliseconds. 

This is similar to the JavaScript minusMillis.

Syntax
$datetime.minusMillis(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().minusMillis(2)

Result2017-11-06T21:48:11.950 UTC

(milliseconds reduced by 2)

minusMinutes

Description

Returns a copy of this datetime minus the specified number of minutes. 

This is similar to the JavaScript minusMinutes.

Syntax
$datetime.minusMinutes(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().minusMinutes(2)

Result2017-11-06T21:46:11.952 UTC

(minutes reduced by 2)

minusMonths

Description

Returns a copy of this datetime minus the specified number of months.

This is similar to the JavaScript minusMonths.

Syntax
$datetime.minusMonths(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().minusMonths(2)

Result2017-09-06T21:48:11.952 UTC

(months reduced by 2)

minusSeconds

Description

Returns a copy of this datetime minus the specified number of seconds. 

This is similar to the JavaScript minusSeconds.

Syntax
$datetime.minusSeconds(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().minusSeconds(2)

Result2017-11-06T21:48:09.952 UTC


minusWeeks

Description

Returns a copy of this datetime minus the specified number of weeks.

This is similar to the JavaScript minusWeeks.

Syntax
$datetime.minusWeeks(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().minusWeeks(2)

Result2017-10-23T21:48:11.952 UTC

(date decreased by 2 weeks)

minusYears

Description

Returns a copy of this datetime minus the specified number of years.

This is similar to the JavaScript minusYears.

Syntax
$datetime.minusYears(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().minusYears(2)

Result2015-11-06T21:48:11.952 UTC

(year reduced by 2)

withDayOfMonth

Description

Returns a copy of this datetime with the day of the month field specified.

This is similar to the JavaScript withDayOfMonth.

Syntax
$datetime.withDayOfMonth(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().withDayOfMonth(4)

Result2017-11-04T21:48:11.952 UTC

(day changed to 4)

withDayOfYear

Description

Returns a copy of this datetime with the day of the year field specified

This is similar to the JavaScript withDayOfYear.

Syntax
$datetime.withDayOfYear(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().withDayOfYear(4)

Result2017-01-04T21:48:11.952 UTC

(date changed to 01-04 since it is the 4th day of the year)

withHourOfDay

Description

Returns a copy of this datetime with the hour of day field specified

This is similar to the JavaScript withHourOfDay

Syntax
$datetime.withHourOfDay(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().withHourOfDay(4)

Result2017-11-06T04:48:11.952 UTC

(hours changed to 4)

withMillisOfSecond

Description

Returns a copy of this datetime with the millis of second field specified.

This is similar to the JavaScript withMillisOfSecond.

Syntax
$datetime.withMillisOfSecond(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().withMillisOfSecond(4)

Result2017-11-06T21:48:11.004 UTC

(milliseconds changed to 4)

withMinuteOfHour

Description

Returns a copy of this datetime with the minute of hour specified.

This is similar to the JavaScript withMinuteOfHour.

Syntax
$datetime.withMinuteOfHour(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().withMinuteOfHour(4)

Result2017-11-06T21:04:11.952 UTC

(minutes changed to 4)

withMonthOfYear

Description

Returns a copy of this datetime with the month of year field specified.

This is similar to the JavaScript withMonthOfYear.

Syntax
$datetime.withMonthOfYear(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().withMonthOfYear(4)

Result2017-04-06T21:48:11.952 UTC

(month changed to 4)

withSecondOfMinute

Description

Returns a copy of this datetime with the second of minute field specified. 

This is similar to the JavaScript withSecondOfMinute.

Syntax
$datetime.withSecondOfMinute(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

ExpressionDate.now().withSecondOfMinute(4)

Result2017-11-06T21:48:04.952 UTC

(seconds changed to 4)

withYear

Description

Returns a copy of this datetime with the year field specified.

This is similar to the JavaScript withYear.

Syntax
$datetime.withYear(value)
Example

If Date.now() is 2017-11-06T21:48:11.952 UTC

Expression: $Date.now().withYear(1995)

Result1995-11-06T21:48:11.952 UTC

(year changed to 1995)



See Also

Video Tutorial: Working with Dates in a Mapper Snap