# Interval

An Interval is a signed quantity associated with one unit. It represents a duration or calendar offset, rather than a timestamp.

Calendar months, quarters and years preserve their calendar meaning; they are not approximated as a fixed number of seconds.

## Syntax

```text
Interval
IntervalNanosecond | IntervalMicrosecond | IntervalMillisecond
IntervalSecond | IntervalMinute | IntervalHour | IntervalDay
IntervalWeek | IntervalMonth | IntervalQuarter | IntervalYear
```

The quantity must be an integer in the signed 64-bit range. A unit-specific declaration supplies the unit for numeric input. Bare `Interval` accepts a typed interval or complete quantity-and-unit text, such as `'3 hours'`.

## Constructing intervals

SQL interval literals and the one-argument constructors create typed values:

```text
INTERVAL quantity unit
to_interval_nanosecond(quantity)
to_interval_microsecond(quantity)
to_interval_millisecond(quantity)
to_interval_second(quantity)
to_interval_minute(quantity)
to_interval_hour(quantity)
to_interval_day(quantity)
to_interval_week(quantity)
to_interval_month(quantity)
to_interval_quarter(quantity)
to_interval_year(quantity)
```

## Arithmetic

Adding or subtracting intervals combines elapsed units exactly, or calendar units in months. Mixing the two categories is rejected. One Interval value cannot retain an arbitrary combination of symbolic calendar and elapsed fields.

Adding a calendar interval to a date clamps to a valid day at the end of the target month. Adding a subday interval to a Date produces a DateTime64. Timestamp calendar arithmetic preserves local time and rejects ambiguous or nonexistent local results.

## Examples

### Constructing values

```sql
SELECT to_interval_day(2), CAST('3 hours' AS Interval)
FORMAT csv;
```

```text
"2 day","3 hour"
```

### Adding a calendar month

The target February does not have a 31st day:

```sql
SELECT CAST('2024-01-31' AS Date) + INTERVAL 1 MONTH
FORMAT csv;
```

```text
"2024-02-29"
```

### Converting calendar units

```sql
SELECT CAST(to_interval_quarter(2) AS IntervalMonth)
FORMAT csv;
```

```text
"6 month"
```

See [date and time functions](https://coordinatordb.com/docs/reference/functions/regular-functions/date-time-functions) for additional calendar operations.