> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Interval

Functions for building intervals, reading the years, months, days, hours, minutes and seconds of an interval, and normalising intervals with interval::justify_hours, justify_days and justify_interval.

_(since v4.0.0)_

This page contains built-in functions for working with [interval](/docs/reference/query-language/language-primitives/data-types/dates-and-times.md) values. An interval holds three separate parts: whole months, whole days, and a time part in microseconds. The functions below build an interval, read its parts, and move amounts between the parts.

## Interval 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="#intervalmake"><code>interval::make()</code></a></td>
      <td scope="row" data-label="Description">Builds an interval from years, months, weeks, days, hours, minutes and seconds</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#intervalyears"><code>interval::years()</code></a></td>
      <td scope="row" data-label="Description">Returns the whole years in the months part of an interval</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#intervalmonths"><code>interval::months()</code></a></td>
      <td scope="row" data-label="Description">Returns the months left over after the whole years</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#intervaldays"><code>interval::days()</code></a></td>
      <td scope="row" data-label="Description">Returns the days part of an interval</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#intervalhours"><code>interval::hours()</code></a></td>
      <td scope="row" data-label="Description">Returns the whole hours in the time part of an interval</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#intervalmins"><code>interval::mins()</code></a></td>
      <td scope="row" data-label="Description">Returns the minutes left over after the whole hours</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#intervalsecs"><code>interval::secs()</code></a></td>
      <td scope="row" data-label="Description">Returns the seconds left over after the whole minutes, with their fraction</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#intervalmicros"><code>interval::micros()</code></a></td>
      <td scope="row" data-label="Description">Returns the seconds left over after the whole minutes, in microseconds</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#intervaljustify_hours"><code>interval::justify_hours()</code></a></td>
      <td scope="row" data-label="Description">Moves each whole 24 hours of the time part into the days part</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#intervaljustify_days"><code>interval::justify_days()</code></a></td>
      <td scope="row" data-label="Description">Moves each whole 30 days of the days part into the months part</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#intervaljustify_interval"><code>interval::justify_interval()</code></a></td>
      <td scope="row" data-label="Description">Applies both justifications and gives every part the same sign</td>
    </tr>
  </tbody>
</table>

## `interval::make`

The `interval::make` function builds an interval from years, months, weeks, days, hours, minutes and seconds. Every argument is optional and defaults to `0`.

```surql title="API DEFINITION"
interval::make(option<number>, option<number>, option<number>, option<number>, option<number>, option<number>, option<number>) -> interval
```

The arguments, in order, are years, months, weeks, days, hours, minutes and seconds. Years and months make up the months part, weeks and days make up the days part, and hours, minutes and seconds make up the time part.

```surql
interval::make(1, 2, 1, 3, 4, 5, 6.5);
```

```surql title="Output"
interval'P1Y2M10DT4H5M6.5S'
```

Years, months, weeks and days must be whole numbers. Hours, minutes and seconds can have a fraction, which is rounded to the nearest microsecond.

```surql
interval::make(0, 0, 0, 0, 1.5);
//- interval'PT1H30M'

interval::make(0.5);
//- 'Incorrect arguments for function interval::make(). The years must be an integer.'
```

To build an interval with a fraction of a day, give the time as hours instead, as in `interval::make(0, 0, 0, 1, 12)` for one and a half days.

<br />

## `interval::years`

The `interval::years` function returns the number of whole years in the months part of an interval.

```surql title="API DEFINITION"
interval::years(interval) -> int
```

The following example shows this function, and its output:

```surql
interval::years(interval'3 years 14 mons');
```

```surql title="Output"
4
```

<br />

## `interval::months`

The `interval::months` function returns the months in the months part of an interval that are left over after the whole years, from `0` to `11` for a positive interval.

```surql title="API DEFINITION"
interval::months(interval) -> int
```

The following example shows this function, and its output:

```surql
interval::months(interval'3 years 14 mons');
```

```surql title="Output"
2
```

<br />

## `interval::days`

The `interval::days` function returns the days part of an interval. The days part is separate from the months part, so a month is not counted as days.

```surql title="API DEFINITION"
interval::days(interval) -> int
```

The following example shows this function, and its output:

```surql
interval::days(interval'1 mon 5 days');
```

```surql title="Output"
5
```

<br />

## `interval::hours`

The `interval::hours` function returns the number of whole hours in the time part of an interval. The time part is not limited to 24 hours.

```surql title="API DEFINITION"
interval::hours(interval) -> int
```

The following example shows this function, and its output:

```surql
interval::hours(interval'50:30:15.5');
```

```surql title="Output"
50
```

<br />

## `interval::mins`

The `interval::mins` function returns the minutes in the time part of an interval that are left over after the whole hours.

```surql title="API DEFINITION"
interval::mins(interval) -> int
```

The following example shows this function, and its output:

```surql
interval::mins(interval'50:30:15.5');
```

```surql title="Output"
30
```

<br />

## `interval::secs`

The `interval::secs` function returns the seconds in the time part of an interval that are left over after the whole minutes, as a decimal that keeps the fraction of a second.

```surql title="API DEFINITION"
interval::secs(interval) -> decimal
```

The following example shows this function, and its output:

```surql
interval::secs(interval'50:30:15.5');
```

```surql title="Output"
15.5dec
```

<br />

## `interval::micros`

The `interval::micros` function returns the seconds in the time part of an interval that are left over after the whole minutes, in microseconds.

```surql title="API DEFINITION"
interval::micros(interval) -> int
```

The following example shows this function, and its output:

```surql
interval::micros(interval'50:30:15.5');
```

```surql title="Output"
15500000
```

<br />

## `interval::justify_hours`

The `interval::justify_hours` function moves each whole 24 hours of the time part into the days part.

```surql title="API DEFINITION"
interval::justify_hours(interval) -> interval
```

The following example shows this function, and its output:

```surql
interval::justify_hours(interval'1 day 50:00:00');
```

```surql title="Output"
interval'P3DT2H'
```

<br />

## `interval::justify_days`

The `interval::justify_days` function moves each whole 30 days of the days part into the months part.

```surql title="API DEFINITION"
interval::justify_days(interval) -> interval
```

The following example shows this function, and its output:

```surql
interval::justify_days(interval'45 days 02:00:00');
```

```surql title="Output"
interval'P1M15DT2H'
```

<br />

## `interval::justify_interval`

The `interval::justify_interval` function applies `interval::justify_hours` and then `interval::justify_days`, and then makes the signs of the parts agree, so that an interval does not mix a positive part with a negative one.

```surql title="API DEFINITION"
interval::justify_interval(interval) -> interval
```

The following example shows this function, and its output:

```surql
interval::justify_interval(interval'45 days 50:00:00');
//- interval'P1M17DT2H'

interval::justify_interval(interval'1 mon -1 day');
//- interval'P29D'

interval::justify_interval(interval'1 day -02:00:00');
//- interval'PT22H'
```

The justified interval is equal to the original under the [interval comparison](/docs/reference/query-language/language-primitives/data-types/dates-and-times.md#comparison-and-ordering), which already counts a month as 30 days and a day as 24 hours. It changes how the interval is stored and displayed, and how it behaves in date arithmetic, where one month and 30 days give different results.

<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
interval::justify_hours(interval'1 day 50:00:00');

-- Method chaining syntax
interval'1 day 50:00:00'.justify_hours();
```

```surql title="Output"
interval'P3DT2H'
```

The method form is available for every function on this page except `interval::make`, which does not take an interval.