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

> 字符串替换函数文档

# 字符串替换函数

[常规字符串函数](/zh/reference/functions/regular-functions/string-functions)和[字符串搜索函数](/zh/reference/functions/regular-functions/string-search-functions)分别在其他页面中说明。

<Note>
  以下文档根据 `system.functions` 系统表自动生成。
</Note>

{/*AUTOGENERATED_START*/}

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

Introduced in：v20.1.0

使用参数中列出的值 (字符串、整数等) 对 `pattern` 字符串进行格式化，类似于 Python 中的格式化方式。
模式字符串可以包含由花括号 `{}` 括起来的替换字段。
凡是不在花括号中的内容都会被视为字面文本，并原样复制到输出中。
字面花括号字符可以用两个花括号进行转义：`{{` 和 `}}`。
字段名可以是数字 (从零开始) ，也可以为空 (此时会隐式分配按顺序递增的编号) 。

**Syntax**

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

**参数**

* `pattern` — 包含占位符的格式字符串。[`String`](/zh/reference/data-types/string)
* `s0[, s1, ...]` — 用于替换模式中占位符的一个或多个值。[`Any`](/zh/reference/data-types/index)

**返回值**

返回格式化后的字符串。[`String`](/zh/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

从基于 1 的位置 `offset` 开始，用另一个字符串 `replace` 替换字符串 `input` 的一部分。

**语法**

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

**参数**

* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
* `replace` — 替换字符串。[`const String`](/zh/reference/data-types/string)
* `offset` — 整数类型 `Int` (从 1 开始计数) 。如果 `offset` 为负数，则从字符串 `s` 的末尾开始计数。[`Int`](/zh/reference/data-types/int-uint)
* `length` — 可选。整数类型 `Int`。`length` 指定输入字符串 `s` 中要替换的片段长度。如果未指定 `length`，则从 `s` 中移除的字节数等于 `replace` 的长度；否则移除 `length` 个字节。[`Int`](/zh/reference/data-types/int-uint)

**返回值**

返回替换后的字符串。[`String`](/zh/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

从基于 1 的索引 `offset` 开始，将字符串 `s` 的一部分替换为另一个字符串 `replace`。
假定该字符串包含有效的 UTF-8 编码文本。
如果这一假定不成立，不会抛出异常，结果将是未定义的。

**语法**

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

**参数**

* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
* `replace` — 替换字符串。[`const String`](/zh/reference/data-types/string)
* `offset` — 整数类型 `Int` (从 1 开始计数) 。如果 `offset` 为负数，则从输入字符串 `s` 的末尾开始计数。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `length` — 可选。指定输入字符串 `s` 中要替换的片段长度。如果未指定 `length`，则从 `s` 中移除的字符数等于 `replace` 的长度；否则移除 `length` 个字符。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回替换后的字符串。[`String`](/zh/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` 函数使用参数中列出的值 (字符串、整数、浮点数等) 对给定字符串进行格式化，类似于 C++ 中的 `printf` 函数。
格式字符串可以包含以 `%` 字符开头的格式说明符。
凡是不包含在 `%` 及其后续格式说明符中的内容，都会被视为字面文本，并原样复制到输出中。
字面 `%` 字符可通过 `%%` 转义。
格式字符串既可以是常量，也可以是列表达式，因此每一行都可以使用不同的格式模式。

**语法**

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

**参数**

* `format` — 包含 `%` 说明符的格式字符串。[`String`](/zh/reference/data-types/string)
* `sub1, sub2, ...` — 可选。用于替换到格式字符串中的零个或多个值。[`Any`](/zh/reference/data-types/index)

**返回值**

返回格式化后的字符串。[`String`](/zh/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`](/zh/reference/data-types/string)

**返回值**

返回一个对正则表达式特殊字符进行转义后的字符串。[`String`](/zh/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

将 `haystack` 中出现的所有子串 `pattern` 替换为 `replacement` 字符串。

**语法**

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

**别名**: `replace`

**参数**

* `haystack` — 要搜索的输入字符串。[`String`](/zh/reference/data-types/string)
* `pattern` — 要查找并替换的子串。[`const String`](/zh/reference/data-types/string)
* `replacement` — 用于替换 `pattern` 的字符串。[`const String`](/zh/reference/data-types/string)

**返回值**

返回将 `pattern` 的所有匹配项都替换后的字符串。[`String`](/zh/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

将 `haystack` 中首次出现的子串 `pattern` 替换为 `replacement` 字符串。

**语法**

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

**参数**

* `haystack` — 要搜索的输入字符串。[`String`](/zh/reference/data-types/string)
* `pattern` — 要查找并替换的子串。[`const String`](/zh/reference/data-types/string)
* `replacement` — 用于替换 `pattern` 的字符串。[`const String`](/zh/reference/data-types/string)

**返回值**

返回一个将 `pattern` 首次出现替换后的字符串。[`String`](/zh/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`](/zh/reference/data-types/string)
* `pattern` — 要查找的正则表达式模式。[`const String`](/zh/reference/data-types/string)
* `replacement` — 用于替换该模式的字符串，可包含替换。[`const String`](/zh/reference/data-types/string)

**返回值**

返回一个将所有正则匹配项替换后的字符串。[`String`](/zh/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`](/zh/reference/data-types/string)
* `pattern` — 要查找的正则表达式模式。[`const String`](/zh/reference/data-types/string)
* `replacement` — 用于替换匹配模式的字符串，可包含替换。[`const String`](/zh/reference/data-types/string)

**返回值**

返回将第一个正则匹配项替换后的字符串。[`String`](/zh/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

按照 `from` 和 `to` 字符串定义的一对一字符映射，替换字符串 `s` 中的字符。
`from` 和 `to` 必须是常量 ASCII 字符串。
如果 `from` 和 `to` 的长度相同，则将 `s` 中出现的 `from` 的第一个字符替换为 `to` 的第一个字符，将 `from` 的第二个字符替换为 `to` 的第二个字符，依此类推。
如果 `from` 包含的字符多于 `to`，则 `from` 末尾那些在 `to` 中没有对应字符的字符在 `s` 中出现时都会被删除。
函数不会修改 `s` 中的非 ASCII 字符。

**语法**

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

**参数**

* `s` — 待转换的输入字符串。[`String`](/zh/reference/data-types/string)
* `from` — 包含待替换字符的常量 ASCII 字符串。[`const String`](/zh/reference/data-types/string)
* `to` — 包含替换后字符的常量 ASCII 字符串。[`const String`](/zh/reference/data-types/string)

**返回值**

返回应用字符转换后的字符串。[`String`](/zh/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`](/zh/reference/data-types/string)
* `from` — 包含待替换字符的常量 UTF-8 字符串。[`const String`](/zh/reference/data-types/string)
* `to` — 包含替换字符的常量 UTF-8 字符串。[`const String`](/zh/reference/data-types/string)

**返回值**

返回 `String` 数据类型的值。[`String`](/zh/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 │
└──────────────────┘
```