Type conversion functions

See also:

- [`toUInt64`](#toUInt64).
- [`toUInt64OrNull`](#toUInt64OrNull).
- [`toUInt64OrDefault`](#toUInt64OrDefault).

**Syntax**

```
toUInt64OrZero(x)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Usage example**

```
SELECT
    toUInt64OrZero('64'),
    toUInt64OrZero('abc')
FORMAT Vertical
```

```
Row 1:
──────
toUInt64OrZero('64'):  64
toUInt64OrZero('abc'): 0
```

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

Introduced in: v1.1.0

Converts an input value to a value of type [`UInt8`](/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 toUInt8('0xc0fe');`.

Note

If the input value cannot be represented within the bounds of [UInt8](/docs/sql-reference/data-types/int-uint), overflow or underflow of the result occurs.
This is not considered an error.
For example: `SELECT toUInt8(256) == 0;`.

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:

- [`toUInt8OrZero`](#toUInt8OrZero).
- [`toUInt8OrNull`](#toUInt8OrNull).
- [`toUInt8OrDefault`](#toUInt8OrDefault).

**Syntax**

```
toUInt8(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 unsigned integer value. [`UInt8`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
SELECT
    toUInt8(8),
    toUInt8(8.8),
    toUInt8('8')
FORMAT Vertical
```

```
Row 1:
──────
toUInt8(8):   8
toUInt8(8.8): 8
toUInt8('8'): 8
```

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

Introduced in: v21.11.0

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

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

**Returned value**

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

**Examples**

**Successful conversion**

```
SELECT toUInt8OrDefault('8', CAST('0', 'UInt8'))
```

```
8
```

**Failed conversion**

```
SELECT toUInt8OrDefault('abc', CAST('0', 'UInt8'))
```

```
0
```

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

Introduced in: v1.1.0

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

Supported arguments:

- String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return `NULL`):

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

Note

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

See also:

- [`toUInt8`](#toUInt8).
- [`toUInt8OrZero`](#toUInt8OrZero).
- [`toUInt8OrDefault`](#toUInt8OrDefault).

**Syntax**

```
toUInt8OrNull(x)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Usage example**

```
SELECT
    toUInt8OrNull('42'),
    toUInt8OrNull('abc')
FORMAT Vertical
```

```
Row 1:
──────
toUInt8OrNull('42'):  42
toUInt8OrNull('abc'): \N
```

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

Introduced in: v1.1.0

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

Supported arguments:

- String representations of (U)Int8/16/32/128/256.

Unsupported arguments (return `0`):

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

Note

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

See also:

- [`toUInt8`](#toUInt8).
- [`toUInt8OrNull`](#toUInt8OrNull).
- [`toUInt8OrDefault`](#toUInt8OrDefault).

**Syntax**

```
toUInt8OrZero(x)
```

**Arguments**

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

**Returned value**

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

**Examples**

**Usage example**

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

```
Row 1:
──────
toUInt8OrZero('-8'):  0
toUInt8OrZero('abc'): 0
```

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

Introduced in: v1.1.0

Converts a String value to a UUID value.

**Syntax**

```
toUUID(string)
```

**Arguments**

- `string` — UUID as a string. [`String`](/docs/sql-reference/data-types/string) or [`FixedString`](/docs/sql-reference/data-types/fixedstring)

**Returned value**

Returns a UUID from the string representation of the UUID. [`UUID`](/docs/sql-reference/data-types/uuid)

**Examples**

**Usage example**

```
SELECT toUUID('61f0c404-5cb3-11e7-907b-a6006ad3dba0') AS uuid
```

```
┌─────────────────────────────────uuid─┐
│ 61f0c404-5cb3-11e7-907b-a6006ad3dba0 │
└──────────────────────────────────────┘
```

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

Introduced in: v20.12.0

Converts an input value to a value of type [UUID](/docs/sql-reference/data-types/uuid) but returns zero UUID in case of an error.
Like [`toUUID`](/docs/sql-reference/functions/type-conversion-functions#toUUID) but returns zero UUID (`00000000-0000-0000-0000-000000000000`) instead of throwing an exception on conversion errors.

Supported arguments:

- String representations of UUID in standard format (8-4-4-4-12 hexadecimal digits).
- String representations of UUID without hyphens (32 hexadecimal digits).

Unsupported arguments (return zero UUID):

- Invalid string formats.
- Non-string types.

**Syntax**

```
toUUIDOrZero(x)
```

**Arguments**

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

**Returned value**

Returns a UUID value if successful, otherwise zero UUID (`00000000-0000-0000-0000-000000000000`). [`UUID`](/docs/sql-reference/data-types/uuid)

**Examples**

**Usage example**

```
SELECT
    toUUIDOrZero('550e8400-e29b-41d4-a716-446655440000') AS valid_uuid,
    toUUIDOrZero('invalid-uuid') AS invalid_uuid
```