Functions for string replacement

[Edit this page](https://github.com/ClickHouse/ClickHouse/tree/master/docs/en/sql-reference/functions/string-replace-functions.md)

[General strings functions](/docs/sql-reference/functions/string-functions) and [functions for searching in strings](/docs/sql-reference/functions/string-search-functions) are described separately.

Note

The documentation below is generated from the `system.functions` system table.

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

Introduced in: v20.1.0

Format the `pattern` string with the values (strings, integers, etc.) listed in the arguments, similar to formatting in Python.
The pattern string can contain replacement fields surrounded by curly braces `{}`.
Anything not contained in braces is considered literal text and copied verbatim into the output.
Literal brace character can be escaped by two braces: `{{` and `}}`.
Field names can be numbers (starting from zero) or empty (then they are implicitly given monotonically increasing numbers).

**Syntax**

```
format(pattern, s0[, s1, ...])
```

**Arguments**

- `pattern` — The format string containing placeholders. [`String`](/docs/sql-reference/data-types/string)
- `s0[, s1, ...]` — One or more values to substitute into the pattern. [`Any`](/docs/sql-reference/data-types)

**Returned value**

Returns a formatted string. [`String`](/docs/sql-reference/data-types/string)

**Examples**

**Numbered placeholders**

```
SELECT format('{1} {0} {1}', 'World', 'Hello')
```

```
┌─format('{1} {0} {1}', 'World', 'Hello')─┐
│ Hello World Hello                       │
└─────────────────────────────────────────┘
```

**Implicit numbering**

```
SELECT format('{} {}', 'Hello', 'World')
```

```
┌─format('{} {}', 'Hello', 'World')─┐
│ Hello World                       │
└───────────────────────────────────┘
```

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

Introduced in: v24.9.0

Replaces part of the string `input` with another string `replace`, starting at the 1-based index `offset`.

**Syntax**

```
overlay(s, replace, offset[, length])
```

**Arguments**

- `s` — The input string. [`String`](/docs/sql-reference/data-types/string)
- `replace` — The replacement string [`const String`](/docs/sql-reference/data-types/string)
- `offset` — An integer type `Int` (1-based). If `offset` is negative, it is counted from the end of the string `s`. [`Int`](/docs/sql-reference/data-types/int-uint)
- `length` — Optional. An integer type `Int`. `length` specifies the length of the snippet within the input string `s` to be replaced. If `length` is not specified, the number of bytes removed from `s` equals the length of `replace`; otherwise `length` bytes are removed. [`Int`](/docs/sql-reference/data-types/int-uint)

**Returned value**

Returns a string with replacement. [`String`](/docs/sql-reference/data-types/string)

**Examples**

**Basic replacement**

```
SELECT overlay('My father is from Mexico.', 'mother', 4) AS res;
```

```
┌─res──────────────────────┐
│ My mother is from Mexico.│
└──────────────────────────┘
```

**Replacement with length**

```
SELECT overlay('My father is from Mexico.', 'dad', 4, 6) AS res;
```

```
┌─res───────────────────┐
│ My dad is from Mexico.│
└───────────────────────┘
```

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

Introduced in: v24.9.0

Replace part of the string `s` with another string `replace`, starting at the 1-based index `offset`.
Assumes that the string contains valid UTF-8 encoded text.
If this assumption is violated, no exception is thrown and the result is undefined.

**Syntax**

```
overlayUTF8(s, replace, offset[, length])
```

**Arguments**

- `s` — The input string. [`String`](/docs/sql-reference/data-types/string)
- `replace` — The replacement string. [`const String`](/docs/sql-reference/data-types/string)
- `offset` — An integer type `Int` (1-based). If `offset` is negative, it is counted from the end of the input string `s`. [`(U)Int*`](/docs/sql-reference/data-types/int-uint)
- `length` — Optional. Specifies the length of the snippet within the input string `s` to be replaced. If `length` is not specified, the number of characters removed from `s` equals the length of `replace`, otherwise `length` characters are removed. [`(U)Int*`](/docs/sql-reference/data-types/int-uint)

**Returned value**

Returns a string with replacement. [`String`](/docs/sql-reference/data-types/string)

**Examples**

**UTF-8 replacement**

```
SELECT overlayUTF8('Mein Vater ist aus Österreich.', 'der Türkei', 20) AS res;
```

```
┌─res───────────────────────────┐
│ Mein Vater ist aus der Türkei.│
└───────────────────────────────┘
```

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

Introduced in: v24.8.0

The `printf` function formats the given string with the values (strings, integers, floating-points etc.) listed in the arguments, similar to printf function in C++.
The format string can contain format specifiers starting with `%` character.
Anything not contained in `%` and the following format specifier is considered literal text and copied verbatim into the output.
Literal `%` character can be escaped by `%%`.
The format string can be either a constant or a column expression, allowing different format patterns per row.

**Syntax**

```
printf(format[, sub1, sub2, ...])
```

**Arguments**

- `format` — The format string with `%` specifiers. [`String`](/docs/sql-reference/data-types/string)
- `sub1, sub2, ...` — Optional. Zero or more values to substitute into the format string. [`Any`](/docs/sql-reference/data-types)

**Returned value**

Returns a formatted string. [`String`](/docs/sql-reference/data-types/string)

**Examples**

**C++-style formatting**

```
SELECT printf('%%%s %s %d', 'Hello', 'World', 2024);
```

```
┌─printf('%%%s %s %d', 'Hello', 'World', 2024)─┐
│ %Hello World 2024                            │
└──────────────────────────────────────────────┘
```

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

Introduced in: v20.1.0

Adds a backslash before these characters with special meaning in regular expressions: `\0`, `\\`, `|`, `(`, `)`, `^`, `$`, `.`, `[`, `]`, `?`, `*`, `+`, `{`, `:`, `-`.
This implementation slightly differs from re2::RE2::QuoteMeta.
It escapes zero byte as `\0` instead of `\x00` and it escapes only required characters.

**Syntax**

```
regexpQuoteMeta(s)
```

**Arguments**

- `s` — The input string containing characters to be escaped for regex. [`String`](/docs/sql-reference/data-types/string)

**Returned value**

Returns a string with regex special characters escaped. [`String`](/docs/sql-reference/data-types/string)

**Examples**

**Escape regex special characters**

```
SELECT regexpQuoteMeta('Hello. [World]? (Yes)*') AS res
```

```
┌─res───────────────────────────┐
│ Hello\. \[World\]\? \(Yes\)\* │
└───────────────────────────────┘
```

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

Introduced in: v1.1.0

Replaces all occurrences of the substring `pattern` in `haystack` by the `replacement` string.

**Syntax**

```
replaceAll(haystack, pattern, replacement)
```

**Aliases**: `replace`

**Arguments**

- `haystack` — The input string to search in. [`String`](/docs/sql-reference/data-types/string)
- `pattern` — The substring to find and replace. [`const String`](/docs/sql-reference/data-types/string)
- `replacement` — The string to replace the pattern with. [`const String`](/docs/sql-reference/data-types/string)

**Returned value**

Returns a string with all occurrences of pattern replaced. [`String`](/docs/sql-reference/data-types/string)

**Examples**

**Replace all occurrences**

```
SELECT replaceAll('Hello, Hello world', 'Hello', 'Hi') AS res;
```

```
┌─res──────────┐
│ Hi, Hi world │
└──────────────┘
```

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

Introduced in: v1.1.0

Replaces the first occurrence of the substring `pattern` in `haystack` by the `replacement` string.

**Syntax**

```
replaceOne(haystack, pattern, replacement)
```

**Arguments**