# Duration

Functions and constants for working with duration-related data.

This page contains built-in functions and constants for converting between numeric and [duration](/docs/reference/query-language/language-primitives/data-types/durations.md) data.

> [!NOTE]
> Since version 3.0.0, the `::from::` functions (e.g. `duration::from::millis()`) now use underscores (e.g. `duration::from_millis()`) to better match the intent of the function and method syntax.

## Duration functions

<table>
  <thead>
    <tr>
      <th scope="col">Function</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationdays"><code>duration::days()</code></a></td>
      <td scope="row" data-label="Description">Counts how many days fit in a duration</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationhours"><code>duration::hours()</code></a></td>
      <td scope="row" data-label="Description">Counts how many hours fit in a duration</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationmicros"><code>duration::micros()</code></a></td>
      <td scope="row" data-label="Description">Counts how many microseconds fit in a duration</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationmillis"><code>duration::millis()</code></a></td>
      <td scope="row" data-label="Description">Counts how many milliseconds fit in a duration</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationmins"><code>duration::mins()</code></a></td>
      <td scope="row" data-label="Description">Counts how many minutes fit in a duration</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationnanos"><code>duration::nanos()</code></a></td>
      <td scope="row" data-label="Description">Counts how many nanoseconds fit in a duration</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationsecs"><code>duration::secs()</code></a></td>
      <td scope="row" data-label="Description">Counts how many seconds fit in a duration</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationweeks"><code>duration::weeks()</code></a></td>
      <td scope="row" data-label="Description">Counts how many weeks fit in a duration</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationyears"><code>duration::years()</code></a></td>
      <td scope="row" data-label="Description">Counts how many years fit in a duration</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationfrom_days"><code>duration::from_days()</code></a></td>
      <td scope="row" data-label="Description">Converts a numeric amount of days into a duration that represents days</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationfrom_hours"><code>duration::from_hours()</code></a></td>
      <td scope="row" data-label="Description">Converts a numeric amount of hours into a duration that represents hours</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationfrom_micros"><code>duration::from_micros()</code></a></td>
      <td scope="row" data-label="Description">Converts a numeric amount of microseconds into a duration that represents microseconds</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationfrom_millis"><code>duration::from_millis()</code></a></td>
      <td scope="row" data-label="Description">Converts a numeric amount of milliseconds into a duration that represents milliseconds</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationfrom_mins"><code>duration::from_mins()</code></a></td>
      <td scope="row" data-label="Description">Converts a numeric amount of minutes into a duration that represents minutes</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationfrom_nanos"><code>duration::from_nanos()</code></a></td>
      <td scope="row" data-label="Description">Converts a numeric amount of nanoseconds into a duration that represents nanoseconds</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationfrom_secs"><code>duration::from_secs()</code></a></td>
      <td scope="row" data-label="Description">Converts a numeric amount of seconds into a duration that represents seconds</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#durationfrom_weeks"><code>duration::from_weeks()</code></a></td>
      <td scope="row" data-label="Description">Converts a numeric amount of weeks into a duration that represents weeks</td>
    </tr>
  </tbody>
</table>

## Duration constants

<table>
  <thead>
    <tr>
      <th scope="col">Constant</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td scope="row" data-label="Constant"><a href="#durationmax"><code>duration::max</code></a></td>
      <td scope="row" data-label="Description">Constant representing the greatest possible duration</td>
    </tr>
  </tbody>
</table>

## `duration::days`

The `duration::days` function counts how many days fit into a duration.

```surql title="API DEFINITION"
duration::days(duration) -> number
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::days(3w);

-- 21
```

<br />

## `duration::hours`

The `duration::hours` function counts how many hours fit into a duration.

```surql title="API DEFINITION"
duration::hours(duration) -> number
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::hours(3w);

-- 504
```

<br />

## `duration::max`

_(since v2.3.0)_

The `duration::max` constant represents the greatest possible duration that can be used.

```surql title="API DEFINITION"
duration::max -> duration
```

Some examples of the constant in use:

```surql
duration::max;

duration::max + 1ns;

100y IN 0ns..duration::max
```

```surql title="Output"
-------- Query 1 --------

584942417355y3w5d7h15s999ms999µs999ns

-------- Query 2 --------
'Failed to compute: "584942417355y3w5d7h15s999ms999µs999ns + 1ns", as the operation results in an arithmetic overflow.'

-------- Query 3 --------
true
```

<br />

## `duration::micros`

The `duration::micros` function counts how many microseconds fit into a duration.

```surql title="API DEFINITION"
duration::micros(duration) -> number
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::micros(3w);

-- 1814400000000
```

<br />

## `duration::millis`

The `duration::millis` function counts how many milliseconds fit into a duration.

```surql title="API DEFINITION"
duration::millis(duration) -> number
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::millis(3w);

-- 1814400000
```

<br />

## `duration::mins`

The `duration::mins` function counts how many minutes fit into a duration.

```surql title="API DEFINITION"
duration::mins(duration) -> number
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::mins(3w);

-- 30240
```

<br />

## `duration::nanos`

The `duration::nanos` function counts how many nanoseconds fit into a duration.

```surql title="API DEFINITION"
duration::nanos(duration) -> number
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::nanos(3w);

-- 1814400000000000
```

<br />

## `duration::secs`

The `duration::secs` function counts how many seconds fit into a duration.

```surql title="API DEFINITION"
duration::secs(duration) -> number
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::secs(3w);

-- 1814400
```

<br />

## `duration::weeks`

The `duration::weeks` function counts how many weeks fit into a duration.

```surql title="API DEFINITION"
duration::weeks(duration) -> number
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::weeks(3w);

-- 3
```

<br />

## `duration::years`

The `duration::years` function counts how many years fit into a duration.

```surql title="API DEFINITION"
duration::years(duration) -> number
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::years(300w);

-- 5
```

<br />

## `duration::from_days`

The `duration::from_days` function counts how many years fit into a duration. The argument must be non-negative; negative values return an error.

```surql title="API DEFINITION"
duration::from_days(number) -> duration
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::from_days(3);

-- 3d
```

<br />

## `duration::from_hours`

The `duration::from_hours` function converts a numeric amount of hours into a duration that represents hours. The argument must be non-negative; negative values return an error.

```surql title="API DEFINITION"
duration::from_hours(number) -> duration
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::from_hours(3);

-- 3h
```

<br />

## `duration::from_micros`

The `duration::from_micros` function converts a numeric amount of microseconds into a duration that represents microseconds. The argument must be non-negative; negative values return an error.

```surql title="API DEFINITION"
duration::from_micros(number) -> duration
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::from_micros(3);

-- 3μs
```

<br />

## `duration::from_millis`

The `duration::from_millis` function converts a numeric amount of milliseconds into a duration that represents milliseconds. The argument must be non-negative; negative values return an error.

```surql title="API DEFINITION"
duration::from_millis(number) -> duration
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::from_millis(3);

-- 3ms
```

<br />

## `duration::from_mins`

The `duration::from_mins` function converts a numeric amount of minutes into a duration that represents minutes. The argument must be non-negative; negative values return an error.

```surql title="API DEFINITION"
duration::from_mins(number) -> duration
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::from_mins(3);

-- 3m
```

<br />

## `duration::from_nanos`

The `duration::from_nanos` function converts a numeric amount of nanoseconds into a duration that represents nanoseconds. The argument must be non-negative; negative values return an error.

```surql title="API DEFINITION"
duration::from_nanos(number) -> duration
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::from_nanos(3);

-- 3ns
```

<br />

## `duration::from_secs`

The `duration::from_secs` function converts a numeric amount of seconds into a duration that represents seconds. The argument must be non-negative; negative values return an error.

```surql title="API DEFINITION"
duration::from_secs(number) -> duration
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::from_secs(3);

-- 3s
```

<br />

## `duration::from_weeks`

The `duration::from_weeks` function converts a numeric amount of weeks into a duration that represents weeks. The argument must be non-negative; negative values return an error.

```surql title="API DEFINITION"
duration::from_weeks(number) -> duration
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN duration::from_weeks(3);

-- 3w
```

<br /><br />

## Method chaining

Method chaining allows functions to be called using the `.` dot operator on a value of a certain type instead of the full path of the function followed by the value.

```surql
-- Traditional syntax
duration::mins(2d6h);

-- Method chaining syntax
2d6h.mins();
```

```surql title="Response"
3240
```

This is particularly useful for readability when a function is called multiple times.

```surql
-- Traditional syntax
duration::mins(duration::from_millis(98734234));

-- Method chaining syntax
duration::from_millis(98734234).mins();
```

```surql title="Response"
1645
```