Type conversion functions

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

Introduced in: v25.6.0

Converts an input value to a value of type Time64 but returns `00:00:00.000` in case of an error.
Like [`toTime64`](#toTime64) but returns `00:00:00.000` instead of throwing an exception on conversion errors.

**Syntax**

```
toTime64OrZero(x)
```

**Arguments**

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

**Returned value**

Returns a Time64 value if successful, otherwise `00:00:00.000`. [`Time64`](/docs/sql-reference/data-types/time64)

**Examples**

**Usage example**

```
SELECT toTime64OrZero('12:30:45.123'), toTime64OrZero('invalid')
```

```
┌─toTime64OrZero('12:30:45.123')─┬─toTime64OrZero('invalid')─┐
│                   12:30:45.123 │             00:00:00.000 │
└────────────────────────────────┴──────────────────────────┘
```

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

Introduced in: v1.1.0

Converts an input value to a value of type Time but returns `NULL` in case of an error.
Like [`toTime`](#toTime) but returns `NULL` instead of throwing an exception on conversion errors.

See also:

- [`toTime`](#toTime)
- [`toTimeOrZero`](#toTimeOrZero)

**Syntax**

```
toTimeOrNull(x)
```

**Arguments**

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

**Returned value**

Returns a Time value if successful, otherwise `NULL`. [`Time`](/docs/sql-reference/data-types/time) or [`NULL`](/docs/sql-reference/syntax#null)

**Examples**

**Usage example**

```
SELECT toTimeOrNull('12:30:45'), toTimeOrNull('invalid')
```

```
┌─toTimeOrNull('12:30:45')─┬─toTimeOrNull('invalid')─┐
│                 12:30:45 │                    ᴺᵁᴸᴸ │
└──────────────────────────┴─────────────────────────┘
```

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

Introduced in: v1.1.0

Converts an input value to a value of type Time but returns `00:00:00` in case of an error.
Like toTime but returns `00:00:00` instead of throwing an exception on conversion errors.

**Syntax**

```
toTimeOrZero(x)
```

**Arguments**

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

**Returned value**

Returns a Time value if successful, otherwise `00:00:00`. [`Time`](/docs/sql-reference/data-types/time)

**Examples**

**Usage example**

```
SELECT toTimeOrZero('12:30:45'), toTimeOrZero('invalid')
```

```
┌─toTimeOrZero('12:30:45')─┬─toTimeOrZero('invalid')─┐
│                 12:30:45 │                00:00:00 │
└──────────────────────────┴─────────────────────────┘
```

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

Introduced in: v1.1.0

Converts an input value to a value of type [`UInt128`](/docs/sql-reference/functions/type-conversion-functions#toUInt128).
Throws an exception in case of an error.
The function uses rounding towards zero, meaning it truncates fractional digits of numbers.

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 toUInt128('0xc0fe');`.

Note

If the input value cannot be represented within the bounds of UInt128, the result over or under flows.
This is not considered an error.

See also:

- [`toUInt128OrZero`](#toUInt128OrZero).
- [`toUInt128OrNull`](#toUInt128OrNull).
- [`toUInt128OrDefault`](#toUInt128OrDefault).

**Syntax**

```
toUInt128(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 a 128-bit unsigned integer value. [`UInt128`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
SELECT
    toUInt128(128),
    toUInt128(128.8),
    toUInt128('128')
FORMAT Vertical
```

```
Row 1:
──────
toUInt128(128):   128
toUInt128(128.8): 128
toUInt128('128'): 128
```

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

Introduced in: v21.11.0

Like [`toUInt128`](#toUInt128), this function converts an input value to a value of type [`UInt128`](/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**

```
toUInt128OrDefault(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. [`UInt128`](/docs/sql-reference/data-types/int-uint)

**Returned value**

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

**Examples**

**Successful conversion**

```
SELECT toUInt128OrDefault('128', CAST('0', 'UInt128'))
```

```
128
```

**Failed conversion**

```
SELECT toUInt128OrDefault('abc', CAST('0', 'UInt128'))
```

```
0
```

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

Introduced in: v21.6.0

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

Note

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

See also:

- [`toUInt128`](#toUInt128).
- [`toUInt128OrZero`](#toUInt128OrZero).
- [`toUInt128OrDefault`](#toUInt128OrDefault).

**Syntax**

```
toUInt128OrNull(x)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Usage example**

```
SELECT
    toUInt128OrNull('128'),
    toUInt128OrNull('abc')
FORMAT Vertical
```

```
Row 1:
──────
toUInt128OrNull('128'): 128
toUInt128OrNull('abc'): \N
```

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

Introduced in: v1.1.0

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

Note

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

See also:

- [`toUInt128`](#toUInt128).
- [`toUInt128OrNull`](#toUInt128OrNull).
- [`toUInt128OrDefault`](#toUInt128OrDefault).

**Syntax**

```
toUInt128OrZero(x)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Usage example**

```
SELECT
    toUInt128OrZero('128'),
    toUInt128OrZero('abc')
FORMAT Vertical
```

```
Row 1:
──────
toUInt128OrZero('128'): 128
toUInt128OrZero('abc'): 0
```