Skip to main content

Date functions

The following list contains the functions that you can use to calculate and manipulate dates and time.


date_parse()#

Parses a string representation of a date using format, and returns the date string in the ISO 8601 standard YYYY-MM-DDThh:mm:ss[.SSS]±hh:mm. Otherwise, returns null if the string is unrecognized or, in some cases, contains illegal date values (e.g. 2015-02-31).

date_parse(string, [format])

Arguments#

string (String)
The date string to parse.
format (String)
(Optional) The parsing format. KelpQL uses the Moment.js library for date parsing. See supported parsing tokens for more details.

Returns#

(String)
The string with the parsed date in the ISO 8601 format YYYY-MM-DDThh:mm:ss[.SSS]±hh:mm.

Examples#

InputExpressionResult
"02/06/2021"
date_parse(@)
"2021-02-06T00:00:00.000+00:00"
"2 June 2021"
date_parse(@)
"2021-06-02T00:00:00.000+00:00"
"Set the date as 2021-06-02"
date_parse(  @,  'YYYY-MM-DD')
"2021-06-02T00:00:00.000+00:00"

date_format()#

Returns the date in the specified format. Returns Invalid date if the date string is unrecognized.

date_format(date, [format])

Arguments#

date (Any)
Any input containing the date.
format (String)
(Optional) The date format. Default is YYYY-MM-DDThh:mm:ssZ. KelpQL uses the Moment.js library for date formatting. See supported formatting tokens for more details.

Returns#

(String)
The formatted date.

Examples#

InputExpressionResult
"2 June 2021"
date_format(@)
"2021-06-02T00:00:00Z"
"The story begins in early 2020"
date_format(@, 'YYYY-MM-DD')
"2020-01-01"

date_add()#

Adds a specified interval to date.

date_add(date, interval)

Arguments#

date (Any)
Any input containing the date.
interval (Object)

The Object with the key of what datepart you want to add, and value is the amount you want to add. The following dateparts are supported. Shorthand also can be used as object key. You can use multiple different keys in the same object literal.

KeyShorthand
yearsy
quartersQ
monthsM
weeksw
daysd
hoursh
minutesm
secondss
millisecondsms

Returns#

(String)
The modified date in the format YYYY-MM-DDThh:mm:ss[.SSS]±hh:mm.

Examples#

InputExpressionResult
"2 June 2021"
date_add(@,  {days: 30})
"2021-07-02T00:00:00.000+00:00"
[["2021-06-02"], [-365]]
date_add([0][0], { days: [1][0] })
"2020-06-02T00:00:00.000+00:00"
"2 June 2021"
date_add(@,  {    d: 10    months: -2  })
"2021-04-12T00:00:00.000+00:00"

date_now()#

Returns the current date and time.

date_now()

Returns#

(String)
The current date and time in the format YYYY-MM-DDThh:mm:ss[.SSS]±hh:mm.

date_distance_in_words()#

Calculates the difference between two dates and returns a string in human readable form in English.

date_distance_in_words(startdate, enddate)

Arguments#

startdate (String)
The starting date.
enddate (String)
The end date.

Returns#

(String)
The resulting string.

Examples#

InputExpressionResult
["2 June 2021", "2021/07/02"]
date_distance_in_words([0], [1])
"a month ago"
"January 4, 1643"
date_distance_in_words(@, date_now())
"378 years ago"
  • date_parse()
  • date_format()
  • date_add()
  • date_now()
  • date_distance_in_words()