Time functions

Time functions return the decimal number for a particular time value, calculate the number of time units (days, months, years) between two dates, and allow to determine timestamps and timeframes, among others.

duration

Creates a duration from the given amount and time unit.

Syntax

duration(value, unit)
Parameters

Name Type Mandatory Default Constraints Description
value
long
yes
The numeric value for the duration.
unit
string
yes
The time unit of the duration.

Name	Type	Mandatory	Default	Constraints	Description
value	long	yes			The numeric value for the duration.
unit	string	yes			The time unit of the duration.

Example

1data record(value = 1000, unit = "ns"),
2     record(value = 60, unit = "s"),
3     record(value = 1000 * 60 * 60 * 24, unit = "ms"),
4     record(value = 24, unit = "h")
5| fieldsAdd duration(value, unit:unit)

Query result

value	unit	duration(value, unit)
`1,000`	`ns`	`1 µs`
`60`	`s`	`1 min`
`86,400,000`	`ms`	`1 D`
`24`	`h`	`1 D`

formatTimestamp

Formats a given timestamp according to a format string using a given pattern. Timestamps according to the ISO 8601 standard can be parsed and converted to the timestamp datatype. The function is using the Java DateTime Formatter and supports the consecutive formatting patterns and symbols.

Syntax

formatTimestamp(timestamp [, interval] [, format])
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
interval
duration
no
format
string
no

Name	Type	Mandatory
timestamp	timestamp	yes
interval	duration	no
format	string	no

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd formatted = formatTimestamp(timestamp, format:"MM-dd-YYYY"),
3            year      = formatTimestamp(timestamp, format:"Y"),
4            month     = formatTimestamp(timestamp, format:"M"),
5            week      = formatTimestamp(timestamp, format:"w"),
6            dayofWeek = formatTimestamp(timestamp, format:"E"),
7            hour      = formatTimestamp(timestamp, format:"H")

Query result

timestamp	formatted	year	month	week	dayofWeek	hour
`2019-08-01T13:30:00.000Z`	`08-01-2019`	`2019`	`8`	`31`	`Thu`	`13`

getDayOfMonth

Extracts the day of the month from a timestamp.

Syntax

getDayOfMonth(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
The timestamp expression from which the day of the month will be extracted.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes			The timestamp expression from which the day of the month will be extracted.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd getDayOfMonth(timestamp)

Query result

timestamp	getDayOfMonth(timestamp)
`2019-08-01T13:30:00.000Z`	`1`

getDayOfWeek

Extracts the day of the week from a timestamp.

Syntax

getDayOfWeek(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
The timestamp expression from which the day of the week will be extracted.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes			The timestamp expression from which the day of the week will be extracted.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd getDayOfWeek(timestamp)

Query result

timestamp	getDayOfWeek(timestamp)
`2019-08-01T13:30:00.000Z`	`4`

getDayOfYear

Extracts the day of the year from a timestamp.

Syntax

getDayOfYear(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
The timestamp expression from which the day of the year will be extracted.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes			The timestamp expression from which the day of the year will be extracted.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd getDayOfYear(timestamp)

Query result

timestamp	getDayOfYear(timestamp)
`2019-08-01T13:30:00.000Z`	`213`

getHour

Extracts the hour from a timestamp.

Syntax

getHour(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
The timestamp expression from which the hour will be extracted.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes			The timestamp expression from which the hour will be extracted.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd getHour(timestamp)

Query result

timestamp	getHour(timestamp)
`2019-08-01T13:30:00.000Z`	`13`

getMinute

Extracts the minute from a timestamp.

Syntax

getMinute(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp expression
yes
The timestamp expression from which the minute will be extracted.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp expression	yes			The timestamp expression from which the minute will be extracted.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd getMinute(timestamp)

Query result

timestamp	getMinute(timestamp)
`2019-08-01T13:30:00.000Z`	`30`

getSecond

Extracts the second from a timestamp.

Syntax

getSecond(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
The timestamp expression from which the second will be extracted.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes			The timestamp expression from which the second will be extracted.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd getSecond(timestamp)

Query result

timestamp	getSecond(timestamp)
`2019-08-01T13:30:00.000Z`	`0`

getYear

Extracts the year from a timestamp.

Syntax

getYear(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
The timestamp expression from which the year will be extracted.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes			The timestamp expression from which the year will be extracted.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd getYear(timestamp)

Query result

timestamp	getYear(timestamp)
`2019-08-01T13:30:00.000Z`	`2,019`

getWeekOfYear

Extracts the week of the year from a timestamp.

Syntax

getWeekOfYear(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
The timestamp expression from which the week of the year will be extracted.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes			The timestamp expression from which the week of the year will be extracted.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd getWeekOfYear(timestamp)

Query result

timestamp	getWeekOfYear(timestamp)
`2019-08-01T13:30:00.000Z`	`31`

now

Returns the current time as a fixed timestamp of the query start.

Syntax

now()
Example
```
1data record()
2| fieldsAdd now()
```
Query result

now()
2023-11-16T08:38:38.360Z

now()
`2023-11-16T08:38:38.360Z`

timeframe

Creates a timeframe structure from the given start and end timestamps.

Syntax

formatTimestamp(timestamp [, interval] [, format])
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
Example
```
1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd timeframe(from:timestamp - 5m, to: timestamp)
```
Query result

timestamp timeframe(from:timestamp - 5m, to:timestamp)
2019-08-01T13:30:00.000Z
start: 2019-08-01T13:25:00.000Z
end: 2019-08-01T13:30:00.000Z

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes

timestamp	timeframe(from:timestamp - 5m, to:timestamp)
`2019-08-01T13:30:00.000Z`	start: `2019-08-01T13:25:00.000Z` end: `2019-08-01T13:30:00.000Z`

timestamp

Creates a timestamp using provided values in mandatory parameters.

Syntax

timestamp(year,month,day,hour,minute,second [, millis] [, micros] [,nanos])
Parameters

Name Type Mandatory Default Constraints Description
year
long
yes
month
long
yes
day
long
yes
hour
long
yes
minute
long
yes
second
long
yes
millis
long
no
micros
long
no
nanos
long
no

Name	Type	Mandatory
year	long	yes
month	long	yes
day	long	yes
hour	long	yes
minute	long	yes
second	long	yes
millis	long	no
micros	long	no
nanos	long	no

Example

1data record()
2| fieldsAdd timestamp(year:2019, month:8, day:1, hour:9, minute:30, second:0)

Query result

timestamp(2019, 8, 1, 9, 30, 0)
`2019-08-01T09:30:00.000Z`

timestampFromUnixMillis

Creates a timestamp from the given milliseconds since Unix epoch.

Syntax

timestampFromUnixMillis(millis)
Parameters

Name Type Mandatory Default Constraints Description
millis
long
yes
Milliseconds since unix start time.
Example
```
1data record(millis = 1564666200000)
2| fieldsAdd timestampFromUnixMillis(millis)
```
Query result

millis timestampFromUnixMillis(millis)
1,564,666,200,000
2019-08-01T13:30:00.000Z

Name	Type	Mandatory	Default	Constraints	Description
millis	long	yes			Milliseconds since unix start time.

millis	timestampFromUnixMillis(millis)
`1,564,666,200,000`	`2019-08-01T13:30:00.000Z`

timestampFromUnixNanos

Creates a timestamp from the given nanoseconds since Unix epoch.

Syntax

timestampFromUnixNanos(nanos)
Parameters

Name Type Mandatory Default Constraints Description
nanos
long
yes
Nanoseconds since unix start time.
Example
```
1data record(nanos = 1564666200000000000)
2| fieldsAdd timestampFromUnixNanos(nanos)
```
Query result

nanos timestampFromUnixNanos(nanos)
1,564,666,200,000,000,000
2019-08-01T13:30:00.000Z

Name	Type	Mandatory	Default	Constraints	Description
nanos	long	yes			Nanoseconds since unix start time.

nanos	timestampFromUnixNanos(nanos)
`1,564,666,200,000,000,000`	`2019-08-01T13:30:00.000Z`

timestampFromUnixSeconds

Creates a timestamp from the given seconds since Unix epoch.

Syntax

timestampFromUnixSeconds(seconds)
Parameters

Name Type Mandatory Default Constraints Description
seconds
long
yes
Seconds since unix start time.
Example
```
1data record(seconds = 1564666200)
2| fieldsAdd timestampFromUnixSeconds(seconds)
```
Query result

seconds timestampFromUnixSeconds(seconds)
1,564,666,200
2019-08-01T13:30:00.000Z

Name	Type	Mandatory	Default	Constraints	Description
seconds	long	yes			Seconds since unix start time.

seconds	timestampFromUnixSeconds(seconds)
`1,564,666,200`	`2019-08-01T13:30:00.000Z`

unixMillisFromTimestamp

Converts a timestamp into milliseconds since Unix epoch.

Syntax

unixMillisFromTimestamp(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
The timestamp expression which will be converted to milliseconds since Unix epoch.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes			The timestamp expression which will be converted to milliseconds since Unix epoch.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd unixMillisFromTimestamp(timestamp)

Query result

timestamp	unixMillisFromTimestamp(timestamp)
`2019-08-01T13:30:00.000Z`	`1,564,666,200,000`

unixNanosFromTimestamp

Converts a timestamp into nanoseconds since Unix epoch.

Syntax

unixNanosFromTimestamp(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
The timestamp expression which will be converted to nanoseconds since Unix epoch.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes			The timestamp expression which will be converted to nanoseconds since Unix epoch.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd unixNanosFromTimestamp(timestamp)

Query result

timestamp	unixNanosFromTimestamp(timestamp)
`2019-08-01T13:30:00.000Z`	`1,564,666,200,000,000,000`

unixSecondsFromTimestamp

Converts a timestamp into seconds since Unix epoch.

Syntax

unixSecondsFromTimestamp(expression)
Parameters

Name Type Mandatory Default Constraints Description
timestamp
timestamp
yes
The timestamp expression which will be converted to seconds since Unix epoch.

Name	Type	Mandatory	Default	Constraints	Description
timestamp	timestamp	yes			The timestamp expression which will be converted to seconds since Unix epoch.

Example

1data record(timestamp = toTimestamp("2019-08-01T09:30:00.000-0400"))
2| fieldsAdd unixSecondsFromTimestamp(timestamp)

Query result

timestamp	unixSecondsFromTimestamp(timestamp)
`2019-08-01T13:30:00.000Z`	`1,564,666,200`

Time functions

duration

formatTimestamp

getDayOfMonth

getDayOfWeek

getDayOfYear

getHour

getMinute

getSecond

getYear

getWeekOfYear

now

timeframe

timestamp

timestampFromUnixMillis

timestampFromUnixNanos

timestampFromUnixSeconds

unixMillisFromTimestamp

unixNanosFromTimestamp

unixSecondsFromTimestamp

Related topics