Type conversion functions

Unsupported arguments:

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

Note

If the input value cannot be represented within the bounds of [Int64](/docs/sql-reference/data-types/int-uint), the result over or under flows.
This is not considered an error.
For example: `SELECT toInt64(9223372036854775808) == -9223372036854775808;`

Note

The function uses [rounding towards zero](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero), meaning it truncates fractional digits of numbers.

See also:

- [`toInt64OrZero`](#toInt64OrZero).
- [`toInt64OrNull`](#toInt64OrNull).
- [`toInt64OrDefault`](#toInt64OrDefault).

**Syntax**

```
toInt64(expr)
```

**Arguments**

- `expr` — Expression returning a number or a string representation of a number. Supported: values or string representations of type (U)Int\*, values of type Float\*. Unsupported: string representations of Float\* values including NaN and Inf, string representations of binary and hexadecimal values. [`Expression`](/docs/sql-reference/data-types/special-data-types/expression)

**Returned value**

Returns a 64-bit integer value. [`Int64`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
SELECT
    toInt64(-64),
    toInt64(-64.64),
    toInt64('-64')
FORMAT Vertical
```

```
Row 1:
──────
toInt64(-64):    -64
toInt64(-64.64): -64
toInt64('-64'):  -64
```

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

Introduced in: v21.11.0

Like [`toInt64`](#toInt64), this function converts an input value to a value of type [Int64](/docs/sql-reference/data-types/int-uint) but returns the default value in case of an error.
If no `default` value is passed then `0` is returned in case of an error.

**Syntax**

```
toInt64OrDefault(expr[, default])
```

**Arguments**

- `expr` — Expression returning a number or a string representation of a number. [`String`](/docs/sql-reference/data-types/string) or [`(U)Int*`](/docs/sql-reference/data-types/int-uint) or [`Float*`](/docs/sql-reference/data-types/float)
- `default` — Optional. The default value to return if parsing is unsuccessful. [`Int64`](/docs/sql-reference/data-types/int-uint)

**Returned value**

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

**Examples**

**Successful conversion**

```
SELECT toInt64OrDefault('-64', CAST('-1', 'Int64'))
```

```
-64
```

**Failed conversion**

```
SELECT toInt64OrDefault('abc', CAST('-1', 'Int64'))
```

```
-1
```

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

Introduced in: v1.1.0

Like [`toInt64`](#toInt64), this function converts an input value to a value of type [Int64](/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 toInt64OrNull('0xc0fe');`.

Note

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

See also:

- [`toInt64`](#toInt64).
- [`toInt64OrZero`](#toInt64OrZero).
- [`toInt64OrDefault`](#toInt64OrDefault).

**Syntax**

```
toInt64OrNull(x)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Usage example**

```
SELECT
    toInt64OrNull('-64'),
    toInt64OrNull('abc')
FORMAT Vertical
```

```
Row 1:
──────
toInt64OrNull('-64'): -64
toInt64OrNull('abc'): \N
```

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

Introduced in: v1.1.0

Converts an input value to type [Int64](/docs/sql-reference/data-types/int-uint) but returns `0` in case of an error.
Like [`toInt64`](#toInt64) but returns `0` instead of throwing an exception.

See also:

- [`toInt64`](#toInt64).
- [`toInt64OrNull`](#toInt64OrNull).
- [`toInt64OrDefault`](#toInt64OrDefault).

**Syntax**

```
toInt64OrZero(x)
```

**Arguments**

- `x` — Input value to convert. [`String`](/docs/sql-reference/data-types/string) or [`FixedString`](/docs/sql-reference/data-types/fixedstring) or [`Float*`](/docs/sql-reference/data-types/float) or [`Decimal`](/docs/sql-reference/data-types/decimal) or [`(U)Int*`](/docs/sql-reference/data-types/int-uint) or [`Date`](/docs/sql-reference/data-types/date) or [`DateTime`](/docs/sql-reference/data-types/datetime)

**Returned value**

Returns the converted input value, otherwise `0` if conversion fails. [`Int64`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
SELECT toInt64OrZero('123')
```

```
123
```

**Failed conversion returns zero**

```
SELECT toInt64OrZero('abc')
```

```
0
```

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

Introduced in: v1.1.0

Converts an input value to a value of type [`Int8`](/docs/sql-reference/data-types/int-uint).
Throws an exception in case of an error.

Supported arguments:

- Values or string representations of type (U)Int\*.
- Values of type Float\*.

Unsupported arguments:

- String representations of Float\* values, including `NaN` and `Inf`.
- String representations of binary and hexadecimal values, e.g. `SELECT toInt8('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.
For example: `SELECT toInt8(128) == -128;`.

Note

The function uses [rounding towards zero](https://en.wikipedia.org/wiki/Rounding#Rounding_towards_zero), meaning it truncates fractional digits of numbers.

See also:

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

**Syntax**

```
toInt8(expr)
```

**Arguments**

- `expr` — Expression returning a number or a string representation of a number. [`Expression`](/docs/sql-reference/data-types/special-data-types/expression)

**Returned value**

Returns an 8-bit integer value. [`Int8`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
SELECT
    toInt8(-8),
    toInt8(-8.8),
    toInt8('-8')
FORMAT Vertical
```

```
Row 1:
──────
toInt8(-8):   -8
toInt8(-8.8): -8
toInt8('-8'): -8
```

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

Introduced in: v21.11.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 the default value in case of an error.
If no `default` value is passed then `0` is returned in case of an error.

**Syntax**

```
toInt8OrDefault(expr[, default])
```

**Arguments**

- `expr` — Expression returning a number or a string representation of a number. [`String`](/docs/sql-reference/data-types/string) or [`(U)Int*`](/docs/sql-reference/data-types/int-uint) or [`Float*`](/docs/sql-reference/data-types/float)
- `default` — Optional. The default value to return if parsing is unsuccessful. [`Int8`](/docs/sql-reference/data-types/int-uint)

**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