---
title: Time functions
slug: analytics/docs/time-functions
docTags: 
createdAt: 2026-07-20T15:44:20.088Z
---

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**

```auto
<date> <time>
```

**Data type** – timestamp

**Example**

```auto
2022-07-15 11:46:35.123
```

**Result**

```auto
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**

```auto
<N> <time unit>
```

**Data type** – time interval

**Example**

```auto
1 hour
4 days
```

**Result**

```auto
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**

```auto
<N> <time unit> <time metric>
```

**Data type** – timestamp

**Example**

```auto
1 hour ago
4 days fromnow
```

**Result**

```auto
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**

```auto
<direction> <N> <time unit>
```

**Data type** – array of timestamps

**Example**

```auto
last 2 hours
next 4 days
```

**Result**

```auto
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**

```auto
timestamp1 - timestamp2
```

**Data type** – time interval

**Example**

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

**Result**

```auto
5 days
```

## timepoint + time interval

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

**Function**

```auto
timepoint + time interval
```

**Data type** – timepoint

**Example**

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

**Result**

```auto
2024-07-15 2:58:18
```

## timepoint – time interval

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

**Function**

```auto
timepoint – time interval
```

**Data type** – timepoint

**Example**

```auto
2022-07-15 1:58:18 – 1 hour
```

**Result**

```auto
2022-07-15 12:58:18
```

## time interval + time interval

This function returns the sum of the selected time intervals.

**Function**

```auto
time interval + time interval
```

**Data type** – timepoint

**Example**

```auto
1 days + 3 days
```

**Result**

```auto
4 days
```

## time interval – time interval

This function returns the difference between the selected time intervals.

**Function**

```auto
time interval – time interval
```

**Data type** – timepoint

**Example**

```auto
14 days - 6 days
```

**Result**

```auto
8 days
```

## extract\_second

This function returns the number of whole seconds since the start of the current minute from a given timestamp.

**Function**

```auto
extract_second
```

**Data type** – number

**Example**

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

**Result**

```auto
18
```

## extract\_minute

This function returns the number of whole minutes since the start of the current hour from a given timestamp.

**Function**

```auto
extract_minute
```

**Data type** – number

**Example**

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

**Result**

```auto
58
```

## extract\_hour

This function returns the number of whole hours since the start of the current day from a given timestamp.

**Function**

```auto
extract_hour
```

**Data type** – number

**Example**

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

**Result**

```auto
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**

```auto
extract_day_of_week
```

**Data type** – number

**Example**

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

**Result**

```auto
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**

```auto
extract_day_of_month
```

**Data** **type** – number

**Example**

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

**Result**

```auto
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**

```auto
extract_day_of_year
```

**Data type** – number

**Example**

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

**Result**

```auto
11
```

## extract\_week

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

**Function**

```auto
extract_week
```

**Data type** – number

**Example**

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

**Result**

```auto
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**

```auto
extract_month
```

**Data type** – number

**Example**

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

**Result**

```auto
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**

```auto
extract_quarter
```

**Data Type** – number

**Example**

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

**Result**

```auto
Q3
```

## extract\_year

This function returns the current year from a given timestamp.

**Function**

```auto
extract_year
```

**Data type** – number

**Example**

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

**Result**

```auto
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**

```auto
time_bucket([timestamp[, <N> <time unit>]])
```

**Data Type** – timestamp

**Example**

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

**Result**

```auto
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:

```auto
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**

```auto
convert_timezone
```

**Data type** – timestamp

**Example**

```auto
convert_timezone('Etc/UTC', 'America/Los_Angeles', 2023-01-01 00:00:00) 
```

**Result**

```auto
2022-12-31 17:00:00
```

## to\_millis

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

**Function**

```auto
to_millis
```

**Data type** – number

**Example**

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

**Result**

```auto
1000
```