Functions for working with dates and times

**Examples**

**Usage example**

```
SELECT toQuarter(toDateTime('2023-04-21 10:20:30'))
```

```
┌─toQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│                                            2 │
└──────────────────────────────────────────────┘
```

## toRelativeDayNum[​](#toRelativeDayNum "Direct link to toRelativeDayNum")

Introduced in: v1.1.0

Converts a date or date with time to the number of days elapsed since a certain fixed point in the past.
The exact point in time is an implementation detail, and therefore this function is not intended to be used standalone.
The main purpose of the function is to calculate the difference in days between two dates or dates with time, e.g., `toRelativeDayNum(dt1) - toRelativeDayNum(dt2)`.

**Syntax**

```
toRelativeDayNum(date)
```

**Arguments**

- `date` — Date or date with time. [`Date`](/docs/sql-reference/data-types/date) or [`DateTime`](/docs/sql-reference/data-types/datetime) or [`DateTime64`](/docs/sql-reference/data-types/datetime64)

**Returned value**

Returns the number of days from a fixed reference point in the past. [`UInt32`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Get relative day numbers**

```
SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))
```

```
┌─minus(toRela⋯3-01-01')))─┐
│                       90 │
└──────────────────────────┘
```

## toRelativeHourNum[​](#toRelativeHourNum "Direct link to toRelativeHourNum")

Introduced in: v1.1.0

Converts a date or date with time to the number of hours elapsed since a certain fixed point in the past.
The exact point in time is an implementation detail, and therefore this function is not intended to be used standalone.
The main purpose of the function is to calculate the difference in hours between two dates or dates with time, e.g., `toRelativeHourNum(dt1) - toRelativeHourNum(dt2)`.

**Syntax**

```
toRelativeHourNum(date)
```

**Arguments**

- `date` — Date or date with time. [`Date`](/docs/sql-reference/data-types/date) or [`DateTime`](/docs/sql-reference/data-types/datetime) or [`DateTime64`](/docs/sql-reference/data-types/datetime64)

**Returned value**

Returns the number of hours from a fixed reference point in the past. [`UInt32`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Get relative hour numbers**

```
SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference
```

```
┌─hours_difference─┐
│               12 │
└──────────────────┘
```

## toRelativeMinuteNum[​](#toRelativeMinuteNum "Direct link to toRelativeMinuteNum")

Introduced in: v1.1.0

Converts a date or date with time to the number of minutes elapsed since a certain fixed point in the past.
The exact point in time is an implementation detail, and therefore this function is not intended to be used standalone.
The main purpose of the function is to calculate the difference in minutes between two dates or dates with time, e.g., `toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2)`.

**Syntax**

```
toRelativeMinuteNum(date)
```

**Arguments**

- `date` — Date or date with time. [`Date`](/docs/sql-reference/data-types/date) or [`DateTime`](/docs/sql-reference/data-types/datetime) or [`DateTime64`](/docs/sql-reference/data-types/datetime64)

**Returned value**

Returns the number of minutes from a fixed reference point in the past. [`UInt32`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Get relative minute numbers**

```
SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference
```

```
┌─minutes_difference─┐
│                 30 │
└────────────────────┘
```

## toRelativeMonthNum[​](#toRelativeMonthNum "Direct link to toRelativeMonthNum")

Introduced in: v1.1.0

Converts a date or date with time to the number of months elapsed since a certain fixed point in the past.
The exact point in time is an implementation detail, and therefore this function is not intended to be used standalone.
The main purpose of the function is to calculate the difference in months between two dates or dates with time, e.g., `toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2)`.

**Syntax**

```
toRelativeMonthNum(date)
```

**Arguments**

- `date` — Date or date with time. [`Date`](/docs/sql-reference/data-types/date) or [`DateTime`](/docs/sql-reference/data-types/datetime) or [`DateTime64`](/docs/sql-reference/data-types/datetime64)

**Returned value**

Returns the number of months from a fixed reference point in the past. [`UInt32`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Get relative month numbers**

```
SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference
```

```
┌─months_difference─┐
│                 3 │
└───────────────────┘
```

## toRelativeQuarterNum[​](#toRelativeQuarterNum "Direct link to toRelativeQuarterNum")

Introduced in: v1.1.0

Converts a date or date with time to the number of quarters elapsed since a certain fixed point in the past.
The exact point in time is an implementation detail, and therefore this function is not intended to be used standalone.
The main purpose of the function is to calculate the difference in quarters between two dates or dates with time, e.g., `toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2)`.

**Syntax**

```
toRelativeQuarterNum(date)
```

**Arguments**

- `date` — Date or date with time. [`Date`](/docs/sql-reference/data-types/date) or [`DateTime`](/docs/sql-reference/data-types/datetime) or [`DateTime64`](/docs/sql-reference/data-types/datetime64)

**Returned value**

Returns the number of quarters from a fixed reference point in the past. [`UInt32`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Get relative quarter numbers**

```
SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference
```

```
┌─quarters_difference─┐
│                   1 │
└─────────────────────┘
```

## toRelativeSecondNum[​](#toRelativeSecondNum "Direct link to toRelativeSecondNum")

Introduced in: v1.1.0

Converts a date or date with time to the number of seconds elapsed since a certain fixed point in the past.
The exact point in time is an implementation detail, and therefore this function is not intended to be used standalone.
The main purpose of the function is to calculate the difference in seconds between two dates or dates with time, e.g., `toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2)`.

**Syntax**

```
toRelativeSecondNum(date)
```

**Arguments**

- `date` — Date or date with time. [`Date`](/docs/sql-reference/data-types/date) or [`DateTime`](/docs/sql-reference/data-types/datetime) or [`DateTime64`](/docs/sql-reference/data-types/datetime64)

**Returned value**

Returns the number of seconds from a fixed reference point in the past. [`UInt32`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Get relative second numbers**

```
SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference
```

```
┌─seconds_difference─┐
│                 60 │
└────────────────────┘
```

## toRelativeWeekNum[​](#toRelativeWeekNum "Direct link to toRelativeWeekNum")

Introduced in: v1.1.0

Converts a date or date with time to the number of weeks elapsed since a certain fixed point in the past.
The exact point in time is an implementation detail, and therefore this function is not intended to be used standalone.
The main purpose of the function is to calculate the difference in weeks between two dates or dates with time, e.g., `toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2)`.

**Syntax**

```
toRelativeWeekNum(date)
```

**Arguments**

- `date` — Date or date with time. [`Date`](/docs/sql-reference/data-types/date) or [`DateTime`](/docs/sql-reference/data-types/datetime) or [`DateTime64`](/docs/sql-reference/data-types/datetime64)

**Returned value**

Returns the number of weeks from a fixed reference point in the past. [`UInt32`](/docs/sql-reference/data-types/int-uint)

**Examples**