Type conversion functions

Introduced in: v1.1.0

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

**Syntax**

```
toIntervalYear(n)
```

**Arguments**

- `n` — Number of years. [`(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` years. [`Interval`](/docs/sql-reference/data-types/int-uint)

**Examples**

**Usage example**

```
WITH
    toDate('2024-06-15') AS date,
    toIntervalYear(1) AS interval_to_year
SELECT date + interval_to_year AS result
```

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

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

Introduced in: v18.12.0

Converts the input argument to the [LowCardinality](/docs/sql-reference/data-types/lowcardinality) version of same data type.

Tip

To convert from the `LowCardinality` data type to a regular data type, use the [CAST](#CAST) function.
For example: `CAST(x AS String)`.

**Syntax**

```
toLowCardinality(expr)
```

**Arguments**

- `expr` — Expression resulting in one of the supported data types. [`String`](/docs/sql-reference/data-types/string) or [`FixedString`](/docs/sql-reference/data-types/fixedstring) or [`Date`](/docs/sql-reference/data-types/date) or [`DateTime`](/docs/sql-reference/data-types/datetime) or [`(U)Int*`](/docs/sql-reference/data-types/int-uint) or [`Float*`](/docs/sql-reference/data-types/float)

**Returned value**

Returns the input value converted to the `LowCardinality` data type. [`LowCardinality`](/docs/sql-reference/data-types/lowcardinality)

**Examples**

**Usage example**

```
SELECT toLowCardinality('1')
```

```
┌─toLowCardinality('1')─┐
│ 1                     │
└───────────────────────┘
```

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

Introduced in: v1.1.0

Converts values to their string representation.
For DateTime arguments, the function can take a second String argument containing the name of the time zone.

**Syntax**

```
toString(value[, timezone])
```

**Arguments**

- `value` — Value to convert to string. [`Any`](/docs/sql-reference/data-types)
- `timezone` — Optional. Timezone name for DateTime conversion. [`String`](/docs/sql-reference/data-types/string)

**Returned value**

Returns a string representation of the input value. [`String`](/docs/sql-reference/data-types/string)

**Examples**

**Usage example**

```
SELECT
    now() AS ts,
    time_zone,
    toString(ts, time_zone) AS str_tz_datetime
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10
```

```
┌──────────────────ts─┬─time_zone─────────┬─str_tz_datetime─────┐
│ 2023-09-08 19:14:59 │ Europe/Amsterdam  │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Andorra    │ 2023-09-08 21:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Astrakhan  │ 2023-09-08 23:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Athens     │ 2023-09-08 22:14:59 │
│ 2023-09-08 19:14:59 │ Europe/Belfast    │ 2023-09-08 20:14:59 │
└─────────────────────┴───────────────────┴─────────────────────┘
```

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

Introduced in: v1.1.0

Accepts a [String](/docs/sql-reference/data-types/string) or [FixedString](/docs/sql-reference/data-types/fixedstring) argument and returns a String that contains a copy of the original string truncated at the first null byte.

Null bytes (\0) are considered as string terminators.
This function is useful for processing C-style strings or binary data where null bytes mark the end of meaningful content.

**Syntax**

```
toStringCutToZero(s)
```

**Arguments**

- `s` — String or FixedString to process. [`String`](/docs/sql-reference/data-types/string) or [`FixedString`](/docs/sql-reference/data-types/fixedstring)

**Returned value**

Returns a String containing the characters before the first null byte. [`String`](/docs/sql-reference/data-types/string)

**Examples**

**Usage example**

```
SELECT
    toStringCutToZero('hello'),
    toStringCutToZero('hello\0world')
```

```
┌─toStringCutToZero('hello')─┬─toStringCutToZero('hello\\0world')─┐
│ hello                      │ hello                             │
└────────────────────────────┴───────────────────────────────────┘
```

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

Introduced in: v1.1.0

Converts an input value to type [Time](/docs/sql-reference/data-types/time).
Supports conversion from String, FixedString, DateTime, or numeric types representing seconds since midnight.

**Syntax**

```
toTime(x)
```

**Arguments**

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

**Returned value**

Returns the converted value. [`Time`](/docs/sql-reference/data-types/time)

**Examples**

**String to Time conversion**

```
SELECT toTime('14:30:25')
```

```
14:30:25
```

**DateTime to Time conversion**

```
SELECT toTime(toDateTime('2025-04-15 14:30:25'))
```

```
14:30:25
```

**Integer to Time conversion**

```
SELECT toTime(52225)
```

```
14:30:25
```

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

Introduced in: v25.6.0

Converts an input value to type [Time64](/docs/sql-reference/data-types/time64).
Supports conversion from String, FixedString, DateTime64, or numeric types representing microseconds since midnight.
Provides microsecond precision for time values.

**Syntax**

```
toTime64(x)
```

**Arguments**

- `x` — Input value to convert. [`String`](/docs/sql-reference/data-types/string) or [`FixedString`](/docs/sql-reference/data-types/fixedstring) or [`DateTime64`](/docs/sql-reference/data-types/datetime64) or [`(U)Int*`](/docs/sql-reference/data-types/int-uint) or [`Float*`](/docs/sql-reference/data-types/float)

**Returned value**

Returns the converted input value with microsecond precision. [`Time64(6)`](/docs/sql-reference/data-types/time64)

**Examples**

**String to Time64 conversion**

```
SELECT toTime64('14:30:25.123456')
```

```
14:30:25.123456
```

**DateTime64 to Time64 conversion**

```
SELECT toTime64(toDateTime64('2025-04-15 14:30:25.123456', 6))
```

```
14:30:25.123456
```

**Integer to Time64 conversion**

```
SELECT toTime64(52225123456)
```

```
14:30:25.123456
```

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

Introduced in: v25.6.0

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

See also:

- [`toTime64`](#toTime64)
- [`toTime64OrZero`](#toTime64OrZero)

**Syntax**

```
toTime64OrNull(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 `NULL`. [`Time64`](/docs/sql-reference/data-types/time64) or [`NULL`](/docs/sql-reference/syntax#null)

**Examples**

**Usage example**

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

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

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