Time Functions

This page outlines the time-related operations you can perform using NetScript.

date time​

This function returns the absolute timestamp literal - date: yyyy-mm-dd time: hh:mm:ss.<milliseconds>

Function: <date> <time>

Data Type: timestamp

Example:

2022-07-15 11:46:35.123

2022-07-15 11:46:35.123

'N' time unit​

This function returns the time interval literal.

• N - Any numerical value.
• time unit - Any unit of time present in the timestamp (e.g., second, minute, hour, day, etc.)

Function: <N> <time unit>

Data Type: time interval

Example:

1 hour
4 days

Dec 31, 1969, 5:00:00 PM GMT-8
345600000

'N' time unit time metric​

This function returns the relative timestamp literal adjusted for the N, time unit, and time metric you select.

• N - Any numerical value.
• time unit - The unit of time you want to adjust for (e.g., second, minute, hour, day, etc.)
• time metric - Whether the timestamp is adjusted backward or forward. Must be set to ago or fromnow respectively.

Function: <N> <time unit> <time metric>

Data Type: timestamp

Example:

1 hour ago
4 days fromnow

2022-07-15 1:58:18.123
2022-07-19 12:58:18.123

direction 'N' time unit​

This function returns a list of times relative to the current timestamp.

• direction must be set to last or next.
• N - Any numerical value.

Function: <direction> <N> <time unit>

Data Type: array of timestamps

Example:

last 2 hours
next 4 days

Current timestamp: 2022-07-15 11:46:35.123
[2022-07-15 11:58:18.123, 2022-07-15 10:58:18.123][2022-07-16 12:58:18.123, 2022-07-17 12:58:18.123, 2022-07-18 12:58:18.123, 2022-07-19 12:58:18.123]

timestamp1 to timestamp2​

This function returns the amount of time between the first and second timestamps .

Function: timestamp1 to timestamp2

Data Type: time interval

Example:

2020-07-16 05:28:47 to 2020-07-21 05:28:47

5 days

timepoint + time interval​

This function returns the timepoint shifted forward by the time interval.

Function: timepoint + time interval

Data Type: timepoint

Example:

2024-07-15 1:58:18 + 1 hour

2024-07-15 2:58:18

timepoint - time interval​

This function returns the timepoint shifted backward by the time interval.

Function: timepoint - time interval

Data Type: timepoint

Example:

2022-07-15 1:58:18 - 1 hour

2022-07-15 12:58:18

time interval + time interval​

This function returns the sum of the selected time intervals.

Function: time interval

Data Type: timepoint

Example:

1 days + 3 days

4 days

time interval - time interval​

This function returns the difference of the selected time intervals.

Function: time interval

Data Type: timepoint

Example:

14 days - 6 days

8 days

extract_second​

This function returns the number of whole seconds since the start of the current minute.

Function: extract_second

Data Type: number

Example:

extract_second(2022-07-15 12:58:18.123)

18

extract_minute​

This function returns the number of whole minutes since the start of the current hour.

Function: extract_minute

Data Type: number

Example:

extract_minute(2022-07-15 12:58:18.123)

58

extract_hour​

This function returns the number of whole hours since the start of the current day.

Function: extract_hour

Data Type: number

Example:

extract_hour(2022-07-15 12:58:18.123)

12

extract_day_of_week​

This function returns the index of the day of the week. For example, Sunday is 1, and Saturday is 7.

Function: extract_day_of_week

Data Type: number

Example:

extract_day_of_week(2022-07-15 12:58:18.123)

6

extract_day_of_month​

This function returns the index of the day of the month. For example, the 1st of the month is 1.

Function: extract_day_of_month

Data Type: number

Example:

extract_day_of_month(2022-07-15 12:58:18.123)

15

extract_day_of_year​

This function returns the index of the day of the year. For example, the 1st of the year is 1.

Function: extract_day_of_year

Data Type: number

Example:

extract_day_of_year(2022-01-11 12:58:18.123)

11

extract_week​

This function returns the index of the full week of the year, where the week starts on Monday.

Function: extract_week

Data Type: number

Example:

extract_week(2022-01-02 02:30:00)

extract_week(2022-01-03 02:30:00)

52 - This date is a Sunday, so even though it is in the new year (2022), the week started in the previous year (2021), and was the 52nd week which started on Monday, Dec 27, 2021.
1 - This date is a Monday, so it is the first day of the first full week in the new year (2022).

extract_month​

This function returns the index of the month of the year. For example, January is 1.

Function: extract_month

Data Type: number

Example:

extract_month(2022-01-11 12:58:18.123)
extract_month(2022-04-01 12:58:18.123)

1
4

extract_quarter​

This function returns the index of the quarter of the year. For example, Q1 starts Jan 1 at 00:00:00, and Q2 starts April 1 at 00:00:00.

Function: extract_quarter

Data Type: number

Example:

2022-07-15 12:58:18.123

Q3

extract_year​

This function returns the current year.

Function: extract_year

Data Type: number

Example:

extract_year(2022-07-15 12:58:18.123)

2022

time_bucket([timestamp[, 'N' time unit]])​

• This function divides time into N time unit-sized buckets and returns the start time of the bucket in which the given timestamp falls, relative to the epoch (1970-01-01 00:00:00 UTC).
• If the 2nd argument is omitted, it defaults to the parameter $TIME_GRAIN.
• If the 1st argument is omitted, it defaults to time .

Function: time_bucket([timestamp[, <N> <time unit>]])

Data Type: timestamp

Example:

time_bucket(2022-07-15 12:58:18.123, 1 hour)

2022-07-15 12:00:00

convert_timezone​

This function converts a timestamp from one timezone to another. Time zone names are in the TZ database format.

Function: convert_timezone

Data Type: timestamp

Example:

econvert_timezone('Etc/UTC', 'America/Los_Angeles', 2023-01-01 00:00:00) 

2022-12-31 17:00:00

to_millis​

This function converts a time duration into an integer number of milliseconds.

Function: to_millis

Data Type: number

Example:

to_millis(2023-01-01 00:00:01 - 2023-01-01 00:00:00)

1000