Time Functions

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

Note: Time-sensitive variables are assigned based on UTC timezone.

date time

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

note

Milliseconds are optional.

Function: <date> <time>

Data Type: timestamp

Example:

2022-07-15 11:46:35.123

Result:

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

Result:

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

Result:

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

Result:

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

Result:

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

Result:

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

Result:

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

Result:

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

Result:

8 days

extract_second

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

Function: extract_second or extractsecond

Data Type: number

Example:

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

Result:

18

extract_minute

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

Function: extract_minute or extractminute

Data Type: number

Example:

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

Result:

58

extract_hour

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

Function: extract_hour or extracthour

Data Type: number

Example:

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

Result:

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 or extractdayofweek

Data Type: number

Example:

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

Result:

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 or extractdayofmonth

Data Type: number

Example:

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

Result:

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 or extractdayofyear

Data Type: number

Example:

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

Result:

11

extract_week

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

Function: extract_week or extractweek

Data Type: number

Example:

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

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

Result:

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 or extractmonth

Data Type: number

Example:

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

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

Result:

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 or extractquarter

Data Type: number

Example:

2022-07-15 12:58:18.123

Result:

Q3

extract_year

This function returns the current year.

Function: extract_year or extractyear

Data Type: number

Example:

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

Result:

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.

note

Time unit must be day or smaller.

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

Data Type: timestamp

Example:

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

Result:

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) 

Result:

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)

Result:

1000