Type conversion functions

**Returned value**

Returns a value of type Int8 if successful, otherwise returns the default value if passed, or 0 if not. [`Int8`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Successful conversion**

```
SELECT toInt8OrDefault('-8', CAST('-1', 'Int8'))
```

```
-8
```

**Failed conversion**

```
SELECT toInt8OrDefault('abc', CAST('-1', 'Int8'))
```

```
-1
```

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

Introduced in: v1.1.0

Like [`toInt8`](#toInt8), this function converts an input value to a value of type [Int8](/docs/sql-reference/data-types/int-uint) but returns `NULL` in case of an error.

Supported arguments:

- String representations of (U)Int\*.

Unsupported arguments (return `NULL`):

- String representations of Float\* values, including `NaN` and `Inf`.
- String representations of binary and hexadecimal values, e.g. `SELECT toInt8OrNull('0xc0fe');`.

Note

If the input value cannot be represented within the bounds of [Int8](/docs/sql-reference/data-types/int-uint), overflow or underflow of the result occurs.
This is not considered an error.

See also:

- [`toInt8`](#toInt8).
- [`toInt8OrZero`](#toInt8OrZero).
- [`toInt8OrDefault`](#toInt8OrDefault).

**Syntax**

```
toInt8OrNull(x)
```

**Arguments**

- `x` — A String representation of a number. [`String`](/docs/sql-reference/data-types/string)

**Returned value**

Returns a value of type Int8, otherwise `NULL` if the conversion is unsuccessful. [`Int8`](/docs/sql-reference/data-types/int-uint) or [`NULL`](/docs/sql-reference/syntax#null)

**Examples**

**Usage example**

```
SELECT
    toInt8OrNull('-8'),
    toInt8OrNull('abc')
FORMAT Vertical
```

```
Row 1:
──────
toInt8OrNull('-8'):  -8
toInt8OrNull('abc'): \N
```

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

Introduced in: v1.1.0

Like [`toInt8`](#toInt8), this function converts an input value to a value of type [Int8](/docs/sql-reference/data-types/int-uint) but returns `0` in case of an error.

Supported arguments:

- String representations of (U)Int\*.

Unsupported arguments (return `0`):

- String representations of Float\* values, including `NaN` and `Inf`.
- String representations of binary and hexadecimal values, e.g. `SELECT toInt8OrZero('0xc0fe');`.

Note

If the input value cannot be represented within the bounds of [Int8](/docs/sql-reference/data-types/int-uint), overflow or underflow of the result occurs.
This is not considered an error.

See also:

- [`toInt8`](#toInt8).
- [`toInt8OrNull`](#toInt8OrNull).
- [`toInt8OrDefault`](#toInt8OrDefault).

**Syntax**

```
toInt8OrZero(x)
```

**Arguments**

- `x` — A String representation of a number. [`String`](/docs/sql-reference/data-types/string)

**Returned value**

Returns a value of type Int8, otherwise `0` if the conversion is unsuccessful. [`Int8`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
SELECT
    toInt8OrZero('8'),
    toInt8OrZero('abc')
FORMAT Vertical
```

```
Row 1:
──────
toInt8OrZero('8'): 8
toInt8OrZero('abc'): 0
```

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

Introduced in: v25.4.0

Creates an Interval value from a numeric value and a unit string.

This function provides a unified way to create intervals of different types (seconds, minutes, hours, days, weeks, months, quarters, years)
from a single function by specifying the unit as a string argument. The unit string is case-insensitive.

This is equivalent to calling type-specific functions like `toIntervalSecond`, `toIntervalMinute`, `toIntervalDay`, etc.,
but allows the unit to be specified dynamically as a string parameter.

**Syntax**

```
toInterval(value, unit)
```

**Arguments**

- `value` — The numeric value representing the number of units. Can be any numeric type. [`Int8`](/docs/sql-reference/data-types/int-uint) or [`Int16`](/docs/sql-reference/data-types/int-uint) or [`Int32`](/docs/sql-reference/data-types/int-uint) or [`Int64`](/docs/sql-reference/data-types/int-uint) or [`UInt8`](/docs/sql-reference/data-types/int-uint) or [`UInt16`](/docs/sql-reference/data-types/int-uint) or [`UInt32`](/docs/sql-reference/data-types/int-uint) or [`UInt64`](/docs/sql-reference/data-types/int-uint) or [`Float32`](/docs/sql-reference/data-types/float) or [`Float64`](/docs/sql-reference/data-types/float)
- `unit` — The unit of time. Must be a constant string. Valid values: 'nanosecond', 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day', 'week', 'month', 'quarter', 'year'. [`String`](/docs/sql-reference/data-types/string)

**Returned value**

Returns an Interval value of the specified type. The result type depends on the unit: IntervalNanosecond, IntervalMicrosecond, IntervalMillisecond, IntervalSecond, IntervalMinute, IntervalHour, IntervalDay, IntervalWeek, IntervalMonth, IntervalQuarter, or IntervalYear. [`Interval`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Create intervals with different units**

```
SELECT
    toInterval(5, 'second') AS seconds,
    toInterval(3, 'day') AS days,
    toInterval(2, 'month') AS months
```

```
┌─seconds─┬─days─┬─months─┐
│ 5       │ 3    │ 2      │
└─────────┴──────┴────────┘
```

**Use intervals in date arithmetic**

```
SELECT
    now() AS current_time,
    now() + toInterval(1, 'hour') AS one_hour_later,
    now() - toInterval(7, 'day') AS week_ago
```

```
┌─────────current_time─┬──one_hour_later─────┬────────────week_ago─┐
│ 2025-01-04 10:30:00  │ 2025-01-04 11:30:00 │ 2024-12-28 10:30:00 │
└──────────────────────┴─────────────────────┴─────────────────────┘
```

**Dynamic interval creation**

```
SELECT toDate('2025-01-01') + toInterval(number, 'day') AS dates
FROM numbers(5)
```

```
┌──────dates─┐
│ 2025-01-01 │
│ 2025-01-02 │
│ 2025-01-03 │
│ 2025-01-04 │
│ 2025-01-05 │
└────────────┘
```

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

Introduced in: v1.1.0

Returns an interval of `n` days of data type [`IntervalDay`](/docs/sql-reference/data-types/special-data-types/interval).

**Syntax**

```
toIntervalDay(n)
```

**Arguments**

- `n` — Number of days. Integer numbers or string representations thereof, and float numbers. [`(U)Int*`](/docs/sql-reference/data-types/int-uint) or [`Float*`](/docs/sql-reference/data-types/float) or [`String`](/docs/sql-reference/data-types/string)

**Returned value**

Returns an interval of `n` days. [`Interval`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
WITH
    toDate('2025-06-15') AS date,
    toIntervalDay(5) AS interval_to_days
SELECT date + interval_to_days AS result
```

```
┌─────result─┐
│ 2025-06-20 │
└────────────┘
```

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

Introduced in: v1.1.0

Returns an interval of `n` hours of data type [`IntervalHour`](/docs/sql-reference/data-types/special-data-types/interval).

**Syntax**

```
toIntervalHour(n)
```

**Arguments**

- `n` — Number of hours. Integer numbers or string representations thereof, and float numbers. [`Int*`](/docs/sql-reference/data-types/int-uint) or [`UInt*`](/docs/sql-reference/data-types/int-uint) or [`Float*`](/docs/sql-reference/data-types/float) or [`String`](/docs/sql-reference/data-types/string)

**Returned value**

Returns an interval of `n` hours. [`Interval`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
WITH
    toDate('2025-06-15') AS date,
    toIntervalHour(12) AS interval_to_hours
SELECT date + interval_to_hours AS result
```

```
┌──────────────result─┐
│ 2025-06-15 12:00:00 │
└─────────────────────┘
```

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

Introduced in: v22.6.0

Returns an interval of `n` microseconds of data type [`IntervalMicrosecond`](/docs/sql-reference/data-types/special-data-types/interval).

**Syntax**

```
toIntervalMicrosecond(n)
```

**Arguments**

- `n` — Number of microseconds. [`(U)Int*`](/docs/sql-reference/data-types/int-uint) or [`Float*`](/docs/sql-reference/data-types/float) or [`String`](/docs/sql-reference/data-types/string)

**Returned value**