Time functions

  • Updated

This page outlines the time-related operations you can perform using NetScript. Time-sensitive variables are assigned based on the UTC zone.

date time

Use this function to get an absolute timestamp in the format yyyy-mm-dd hh:mm:ss.<milliseconds>. 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

Use this function to define a time interval using a numerical value (N) and any unit of time present in the timestamp (for example, second, minute, hour, and day).

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 lets you modify a timestamp by a specified time in a particular direction.

  • N – Enter any numerical value to specify the time to adjust.
  • time unit – Choose the unit of time you want to adjust, such as seconds, minutes, hours, or days.
  • time metric – Decide whether to adjust the timestamp backward or forward. Use ago for backward adjustments and fromnow for forward adjustments.

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 – Choose last to look into the past or next to look into the future.
  • N – Enter any number to specify how many time units to list.
  • time unit – Select the unit of time, such as seconds, minutes, hours, or days.

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 10:46:35.123, 2022-07-15 09:46:35.123][2022-07-16 11:46:35.123, 2022-07-17 11:46:35.123, 2022-07-18 11:46:35.123, 2022-07-19 11:46:35.123]

timestamp1 - timestamp2

This function returns the duration between two timestamps.

Function

timestamp1 - timestamp2

Data type – time interval

Example

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

Result

5 days

timepoint + time interval

This function returns the time point 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 time point 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 + time interval

Data type – timepoint

Example

1 days + 3 days

Result

4 days

time interval – time interval

This function returns the difference between the selected time intervals.

Function

time interval – 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 from a given timestamp.

Function

extract_second

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 from a given timestamp.

Function

extract_minute

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 from a given timestamp.

Function

extract_hour

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 a given timestamp. 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)

Result

6

extract_day_of_month

This function returns the index of the day of the month for a given timestamp. For example, the first 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)

Result

15

extract_day_of_year

This function returns the index of the day of the year for a given timestamp. For example, the first day 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)

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

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, 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)

Result

1
4

extract_quarter

This function returns the index of the year's quarter from a given timestamp. For example, Q1 starts January 1 at 00:00:00, and Q2 starts April 1 at 00:00:00.

Function

extract_quarter

Data Type – number

Example

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

Result

Q3

extract_year

This function returns the current year from a given timestamp.

Function

extract_year

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 fixed-size intervals (buckets) and returns the interval's start time in which the given timestamp falls. The intervals are measured relative to the epoch (1970-01-01 00:00:00 UTC).

  • timestamp – (optional) The specific date and time to be evaluated. If omitted, the current time is used.
  • N time unit – (optional) The size of each time bucket, where N is a numerical value and time unit can be hours, minutes, and seconds. If omitted, it defaults to the parameter $TIME_GRAIN. The time unit must be a 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

You can use now if you want to get the current time. For example, for a date three months from today, the function is as follows:

time_bucket(now, 3 months)

convert_timezone

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

Function

convert_timezone

Data type – timestamp

Example

convert_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