> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-3a82795f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Документация по функциям замены строк

# Функции замены строк

[Общие функции для работы со строками](/ru/reference/functions/regular-functions/string-functions) и [функции поиска в строках](/ru/reference/functions/regular-functions/string-search-functions) описаны отдельно.

<Note>
  Приведённая ниже документация сгенерирована из системной таблицы `system.functions`.
</Note>

{/*AUTOGENERATED_START*/}

<div id="format">
  ## format
</div>

Добавленный в: v20.1.0

Форматирует строку `pattern` значениями (строками, целыми числами и т. д.), перечисленными в аргументах, аналогично форматированию в Python.
Строка шаблона может содержать поля подстановки, заключённые в фигурные скобки `{}`.
Всё, что не заключено в скобки, считается буквальным текстом и копируется в выходную строку без изменений.
Буквальные символы фигурных скобок можно экранировать двойными скобками: `{{` и `}}`.
Именами полей могут быть числа (начиная с нуля) или пустые значения (в этом случае им неявно присваиваются последовательно возрастающие номера).

**Синтаксис**

```sql theme={null}
format(pattern, s0[, s1, ...])
```

**Аргументы**

* `pattern` — Строка форматирования, содержащая плейсхолдеры. [`String`](/ru/reference/data-types/string)
* `s0[, s1, ...]` — Одно или несколько значений для подстановки в шаблон. [`Any`](/ru/reference/data-types)

**Возвращаемое значение**

Возвращает отформатированную строку. [`String`](/ru/reference/data-types/string)

**Примеры**

**Нумерованные плейсхолдеры**

```sql title=Query theme={null}
SELECT format('{1} {0} {1}', 'World', 'Hello')
```

```response title=Response theme={null}
┌─format('{1} {0} {1}', 'World', 'Hello')─┐
│ Hello World Hello                       │
└─────────────────────────────────────────┘
```

**Неявная нумерация**

```sql title=Query theme={null}
SELECT format('{} {}', 'Hello', 'World')
```

```response title=Response theme={null}
┌─format('{} {}', 'Hello', 'World')─┐
│ Hello World                       │
└───────────────────────────────────┘
```

<div id="overlay">
  ## overlay
</div>

Добавленный в: v24.9.0

Заменяет часть строки `input` на другую строку `replace`, начиная с индекса `offset` (нумерация с 1).

**Синтаксис**

```sql theme={null}
overlay(s, replace, offset[, length])
```

**Аргументы**

* `s` — Входная строка. [`String`](/ru/reference/data-types/string)
* `replace` — Строка замены. [`const String`](/ru/reference/data-types/string)
* `offset` — Целочисленный тип `Int` (нумерация с 1). Если `offset` отрицательный, отсчёт ведётся от конца строки `s`. [`Int`](/ru/reference/data-types/int-uint)
* `length` — Необязательно. Целочисленный тип `Int`. `length` задаёт длину фрагмента во входной строке `s`, который нужно заменить. Если `length` не указана, количество байтов, удаляемых из `s`, равно длине `replace`; в противном случае удаляется `length` байтов. [`Int`](/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает строку с выполненной заменой. [`String`](/ru/reference/data-types/string)

**Примеры**

**Простая замена**

```sql title=Query theme={null}
SELECT overlay('My father is from Mexico.', 'mother', 4) AS res;
```

```response title=Response theme={null}
┌─res──────────────────────┐
│ My mother is from Mexico.│
└──────────────────────────┘
```

**Замена с указанием длины**

```sql title=Query theme={null}
SELECT overlay('My father is from Mexico.', 'dad', 4, 6) AS res;
```

```response title=Response theme={null}
┌─res───────────────────┐
│ My dad is from Mexico.│
└───────────────────────┘
```

<div id="overlayUTF8">
  ## overlayUTF8
</div>

Добавленный в: v24.9.0

Заменяет часть строки `s` на другую строку `replace`, начиная с индекса `offset`, отсчитываемого от 1.
Предполагается, что строка содержит корректный текст в кодировке UTF-8.
Если это предположение нарушено, исключение не генерируется, а результат не определён.

**Синтаксис**

```sql theme={null}
overlayUTF8(s, replace, offset[, length])
```

**Аргументы**

* `s` — Входная строка. [`String`](/ru/reference/data-types/string)
* `replace` — Строка замены. [`const String`](/ru/reference/data-types/string)
* `offset` — Целочисленный тип `Int` (нумерация начинается с 1). Если `offset` отрицательный, отсчёт ведётся от конца входной строки `s`. [`(U)Int*`](/ru/reference/data-types/int-uint)
* `length` — Необязательный параметр. Задаёт длину фрагмента входной строки `s`, который нужно заменить. Если `length` не указан, количество символов, удаляемых из `s`, равно длине `replace`; в противном случае удаляется `length` символов. [`(U)Int*`](/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает строку с заменённым фрагментом. [`String`](/ru/reference/data-types/string)

**Примеры**

**Замена UTF-8**

```sql title=Query theme={null}
SELECT overlayUTF8('Mein Vater ist aus Österreich.', 'der Türkei', 20) AS res;
```

```response title=Response theme={null}
┌─res───────────────────────────┐
│ Mein Vater ist aus der Türkei.│
└───────────────────────────────┘
```

<div id="printf">
  ## printf
</div>

Добавленный в: v24.8.0

Функция `printf` форматирует заданную строку значениями (строками, целыми числами, числами с плавающей точкой и т. д.), перечисленными в аргументах, аналогично функции `printf` в C++.
Строка формата может содержать спецификаторы формата, начинающиеся с символа `%`.
Всё, что не является `%` и следующим за ним спецификатором формата, считается литеральным текстом и копируется в результат как есть.
Литеральный символ `%` можно экранировать с помощью `%%`.
Строка формата может быть как константой, так и выражением столбца, что позволяет использовать разные шаблоны формата для каждой строки.

**Синтаксис**

```sql theme={null}
printf(format[, sub1, sub2, ...])
```

**Аргументы**

* `format` — Строка формата со спецификаторами `%`. [`String`](/ru/reference/data-types/string)
* `sub1, sub2, ...` — Необязательный параметр. Одно или несколько значений для подстановки в строку формата. [`Any`](/ru/reference/data-types)

**Возвращаемое значение**

Возвращает отформатированную строку. [`String`](/ru/reference/data-types/string)

**Примеры**

**Форматирование в стиле C++**

```sql title=Query theme={null}
SELECT printf('%%%s %s %d', 'Hello', 'World', 2024);
```

```response title=Response theme={null}
┌─printf('%%%s %s %d', 'Hello', 'World', 2024)─┐
│ %Hello World 2024                            │
└──────────────────────────────────────────────┘
```

<div id="regexpQuoteMeta">
  ## regexpQuoteMeta
</div>

Добавленный в: v20.1.0

Добавляет обратную косую черту перед следующими символами, имеющими специальное значение в регулярных выражениях: `\0`, `\\`, `|`, `(`, `)`, `^`, `$`, `.`, `[`, `]`, `?`, `*`, `+`, `{`, `:`, `-`.
Эта реализация немного отличается от re2::RE2::QuoteMeta.
Нулевой байт экранируется как `\0` вместо `\x00`, при этом экранируются только необходимые символы.

**Синтаксис**

```sql theme={null}
regexpQuoteMeta(s)
```

**Аргументы**

* `s` — Входная строка, содержащая символы, которые нужно экранировать в регулярном выражении. [`String`](/ru/reference/data-types/string)

**Возвращаемое значение**

Возвращает строку, в которой экранированы специальные символы регулярного выражения. [`String`](/ru/reference/data-types/string)

**Примеры**

**Экранирование специальных символов регулярного выражения**

```sql title=Query theme={null}
SELECT regexpQuoteMeta('Hello. [World]? (Yes)*') AS res
```

```response title=Response theme={null}
┌─res───────────────────────────┐
│ Hello\. \[World\]\? \(Yes\)\* │
└───────────────────────────────┘
```

<div id="replaceAll">
  ## replaceAll
</div>

Добавленный в: v1.1.0

Заменяет все вхождения шаблона регулярного выражения `pattern` в строке `haystack` на строку `replacement`.

**Синтаксис**

```sql theme={null}
replaceAll(haystack, pattern, replacement)
```

**Псевдонимы**: `replace`

**Аргументы**

* `haystack` — Входная строка, в которой выполняется поиск. [`String`](/ru/reference/data-types/string)
* `pattern` — Шаблон регулярного выражения, который нужно найти и заменить. [`const String`](/ru/reference/data-types/string)
* `replacement` — Строка, которой заменяется найденная подстрока. [`const String`](/ru/reference/data-types/string)

**Возвращаемое значение**

Возвращает строку, в которой заменены все вхождения шаблона регулярного выражения. [`String`](/ru/reference/data-types/string)

**Примеры**

**Заменить все вхождения**

```sql title=Query theme={null}
SELECT replaceAll('Hello, Hello world', 'Hello', 'Hi') AS res;
```

```response title=Response theme={null}
┌─res──────────┐
│ Hi, Hi world │
└──────────────┘
```

<div id="replaceOne">
  ## replaceOne
</div>

Добавленный в: v1.1.0

Заменяет первое вхождение подстроки `pattern` в строке `haystack` на строку `replacement`.

**Синтаксис**

```sql theme={null}
replaceOne(haystack, pattern, replacement)
```

**Аргументы**

* `haystack` — Входная строка, в которой выполняется поиск. [`String`](/ru/reference/data-types/string)
* `pattern` — Шаблон регулярного выражения, который нужно найти и заменить. [`const String`](/ru/reference/data-types/string)
* `replacement` — Строка, на которую заменяется найденный фрагмент. [`const String`](/ru/reference/data-types/string)

**Возвращаемое значение**

Возвращает строку, в которой заменено первое совпадение с шаблоном регулярного выражения. [`String`](/ru/reference/data-types/string)

**Примеры**

**Замена первого вхождения**

```sql title=Query theme={null}
SELECT replaceOne('Hello, Hello world', 'Hello', 'Hi') AS res;
```

```response title=Response theme={null}
┌─res─────────────┐
│ Hi, Hello world │
└─────────────────┘
```

<div id="replaceRegexpAll">
  ## replaceRegexpAll
</div>

Добавленный в: v1.1.0

Как и `replaceRegexpOne`, но заменяет все вхождения шаблона регулярного выражения.
В качестве исключения: если регулярное выражение сработало на пустой подстроке, замена выполняется не более одного раза.

**Синтаксис**

```sql theme={null}
replaceRegexpAll(haystack, pattern, replacement)
```

**Псевдонимы**: `REGEXP_REPLACE`

**Аргументы**

* `haystack` — Входная строка, в которой выполняется поиск. [`String`](/ru/reference/data-types/string)
* `pattern` — Шаблон регулярного выражения, который нужно найти. [`const String`](/ru/reference/data-types/string)
* `replacement` — Строка, которой заменяется шаблон регулярного выражения; может содержать подстановки. [`const String`](/ru/reference/data-types/string)

**Возвращаемое значение**

Возвращает строку, в которой заменены все совпадения с регулярным выражением. [`String`](/ru/reference/data-types/string)

**Примеры**

**Заменить все символы на удвоенные**

```sql title=Query theme={null}
SELECT replaceRegexpAll('Hello123', '.', '\\\\0\\\\0') AS res
```

```response title=Response theme={null}
┌─res──────────────────┐
│ HHeelllloo112233     │
└──────────────────────┘
```

**Пример замены пустой подстроки**

```sql title=Query theme={null}
SELECT replaceRegexpAll('Hello, World!', '^', 'here: ') AS res
```

```response title=Response theme={null}
┌─res─────────────────┐
│ here: Hello, World! │
└─────────────────────┘
```

<div id="replaceRegexpOne">
  ## replaceRegexpOne
</div>

Добавленный в: v1.1.0

Заменяет первое вхождение подстроки в `haystack`, соответствующее шаблону регулярного выражения `pattern` (в синтаксисе re2), на строку `replacement`.
`replacement` может содержать подстановки `\0-\9`.
Подстановки `\1-\9` соответствуют 1-й–9-й захватывающим группам (подсовпадениям), а подстановка `\0` — всему совпадению.
Чтобы использовать буквальный символ `\` в строках `pattern` или `replacement`, экранируйте его с помощью `\`.
Также имейте в виду, что строковые литералы требуют дополнительного экранирования.

**Синтаксис**

```sql theme={null}
replaceRegexpOne(haystack, pattern, replacement)
```

**Аргументы**

* `haystack` — Входная строка для поиска. [`String`](/ru/reference/data-types/string)
* `pattern` — Шаблон регулярного выражения для поиска. [`const String`](/ru/reference/data-types/string)
* `replacement` — Строка, на которую заменяется найденное совпадение; может содержать подстановки. [`const String`](/ru/reference/data-types/string)

**Возвращаемое значение**

Возвращает строку, в которой заменено первое совпадение по регулярному выражению. [`String`](/ru/reference/data-types/string)

**Примеры**

**Преобразование дат ISO в американский формат**

```sql title=Query theme={null}
SELECT DISTINCT
    EventDate,
    replaceRegexpOne(toString(EventDate), '(\\d{4})-(\\d{2})-(\\d{2})', '\\2/\\3/\\1') AS res
FROM test.hits
LIMIT 7
FORMAT TabSeparated
```

```response title=Response theme={null}
2014-03-17      03/17/2014
2014-03-18      03/18/2014
2014-03-19      03/19/2014
2014-03-20      03/20/2014
2014-03-21      03/21/2014
2014-03-22      03/22/2014
2014-03-23      03/23/2014
```

**Копирование строки десять раз**

```sql title=Query theme={null}
SELECT replaceRegexpOne('Hello, World!', '.*', '\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0') AS res
```

```response title=Response theme={null}
┌─res────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World! │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="translate">
  ## translate
</div>

Добавленный в: v22.7.0

Заменяет символы в строке `s` на основе посимвольного соответствия, заданного строками `from` и `to`.
`from` и `to` должны быть константными ASCII-строками.
Если `from` и `to` имеют одинаковую длину, каждое вхождение первого символа из `from` в `s` заменяется первым символом из `to`, каждого второго символа из `from` — вторым символом из `to` и так далее.
Если `from` содержит больше символов, чем `to`, все вхождения символов в конце `from`, для которых нет соответствующего символа в `to`, удаляются из `s`.
Символы не из ASCII в `s` функцией не изменяются.

**Синтаксис**

```sql theme={null}
translate(s, from, to)
```

**Аргументы**

* `s` — Входная строка для преобразования. [`String`](/ru/reference/data-types/string)
* `from` — Константная строка ASCII, содержащая символы для замены. [`const String`](/ru/reference/data-types/string)
* `to` — Константная строка ASCII, содержащая символы-замены. [`const String`](/ru/reference/data-types/string)

**Возвращаемое значение**

Возвращает строку с заменёнными символами. [`String`](/ru/reference/data-types/string)

**Примеры**

**Сопоставление символов**

```sql title=Query theme={null}
SELECT translate('Hello, World!', 'delor', 'DELOR') AS res
```

```response title=Response theme={null}
┌─res───────────┐
│ HELLO, WORLD! │
└───────────────┘
```

**Различная длина**

```sql title=Query theme={null}
SELECT translate('clickhouse', 'clickhouse', 'CLICK') AS res
```

```response title=Response theme={null}
┌─res───┐
│ CLICK │
└───────┘
```

<div id="translateUTF8">
  ## translateUTF8
</div>

Добавленный в: v22.7.0

Как [`translate`](#translate), но предполагается, что `s`, `from` и `to` — строки в кодировке UTF-8.

**Синтаксис**

```sql theme={null}
translateUTF8(s, from, to)
```

**Аргументы**

* `s` — входная UTF-8-строка для преобразования. [`String`](/ru/reference/data-types/string)
* `from` — константная UTF-8-строка, содержащая символы для замены. [`const String`](/ru/reference/data-types/string)
* `to` — константная UTF-8-строка, содержащая символы, на которые выполняется замена. [`const String`](/ru/reference/data-types/string)

**Возвращаемое значение**

Возвращает значение типа данных `String`. [`String`](/ru/reference/data-types/string)

**Примеры**

**Преобразование символов UTF-8**

```sql title=Query theme={null}
SELECT translateUTF8('Münchener Straße', 'üß', 'us') AS res;
```

```response title=Response theme={null}
┌─res──────────────┐
│ Munchener Strase │
└──────────────────┘
```