Date functions

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

Input	Expression	Result
"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

Input	Expression	Result
"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.

Key	Shorthand
years	y
quarters	Q
months	M
weeks	w
days	d
hours	h
minutes	m
seconds	s
milliseconds	ms

Returns

(String)

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

Examples

Input	Expression	Result
"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

Input	Expression	Result
["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"