> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> 字符串函数文档
# 字符串函数
export const VersionBadge = ({minVersion}) =>
Available in version {minVersion} and later
;
用于在字符串中进行[搜索](/zh/reference/functions/regular-functions/string-search-functions)和[替换](/zh/reference/functions/regular-functions/string-replace-functions)的函数将在其他章节中单独介绍。
以下文档由 `system.functions` 系统表自动生成。
{/*AUTOGENERATED_START*/}
## CRC32
引入版本：v20.1.0
使用 CRC-32-IEEE 802.3 多项式和初始值 `0xffffffff` (zlib 实现) 计算字符串的 CRC32 校验和。
**语法**
```sql theme={null}
CRC32(s)
```
**参数**
* `s` — 要计算 CRC32 的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回该字符串的 CRC32 校验和。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT CRC32('ClickHouse')
```
```response title=Response theme={null}
┌─CRC32('ClickHouse')─┐
│ 1538217360 │
└─────────────────────┘
```
## CRC32IEEE
引入版本：v20.1.0
使用 CRC-32-IEEE 802.3 多项式计算字符串的 CRC32 校验和。
**语法**
```sql theme={null}
CRC32IEEE(s)
```
**参数**
* `s` — 用于计算 CRC32 的 String。[`String`](/zh/reference/data-types/string)
**返回值**
返回该字符串的 CRC32 校验和。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT CRC32IEEE('ClickHouse');
```
```response title=Response theme={null}
┌─CRC32IEEE('ClickHouse')─┐
│ 3089448422 │
└─────────────────────────┘
```
## CRC64
引入于：v20.1.0
使用 CRC-64-ECMA 多项式计算字符串的 CRC64 校验和。
**语法**
```sql theme={null}
CRC64(s)
```
**参数**
* `s` — 要计算 CRC64 的 String。[`String`](/zh/reference/data-types/string)
**返回值**
返回该字符串的 CRC64 校验和。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT CRC64('ClickHouse');
```
```response title=Response theme={null}
┌──CRC64('ClickHouse')─┐
│ 12126588151325169346 │
└──────────────────────┘
```
## appendTrailingCharIfAbsent
引入版本：v1.1.0
如果字符串 `s` 非空且末尾不是字符 `c`，则在其末尾追加字符 `c`。
**语法**
```sql theme={null}
appendTrailingCharIfAbsent(s, c)
```
**参数**
* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
* `c` — 如果不存在则要追加的字符。[`String`](/zh/reference/data-types/string)
**返回值**
如果字符串 `s` 不以字符 `c` 结尾，则返回在其末尾追加了字符 `c` 的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT appendTrailingCharIfAbsent('https://example.com', '/');
```
```response title=Response theme={null}
┌─appendTraili⋯.com', '/')─┐
│ https://example.com/ │
└──────────────────────────┘
```
## ascii
引入版本：v22.11.0
返回字符串 `s` 中第一个字符的 ASCII 码点，返回类型为 `Int32`。
**语法**
```sql theme={null}
ascii(s)
```
**参数**
* `s` — String 类型的输入值。[`String`](/zh/reference/data-types/string)
**返回值**
返回第一个字符的 ASCII 码点。如果 `s` 为空，结果为 `0`。如果第一个字符不是 ASCII 字符，或者不在 UTF-16 的 Latin-1 补充范围内，则结果未定义。[`Int32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT ascii('234')
```
```response title=Response theme={null}
┌─ascii('234')─┐
│ 50 │
└──────────────┘
```
## base32Decode
引入版本：v25.6.0
对 [Base32](https://datatracker.ietf.org/doc/html/rfc4648#section-6) (RFC 4648) 字符串解码。
如果该字符串不是有效的 Base32 编码字符串，则会抛出异常。
**语法**
```sql theme={null}
base32Decode(encoded)
```
**参数**
* `encoded` — String 类型的列或常量。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个字符串，其中包含该参数解码后的值。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT base32Decode('IVXGG33EMVSA====');
```
```response title=Response theme={null}
┌─base32Decode('IVXGG33EMVSA====')─┐
│ Encoded │
└──────────────────────────────────┘
```
## base32Encode
引入于：v25.6.0
使用 [Base32](https://datatracker.ietf.org/doc/html/rfc4648#section-6) 对字符串进行编码。
**语法**
```sql theme={null}
base32Encode(plaintext)
```
**参数**
* `plaintext` — 要编码的明文。[`String`](/zh/reference/data-types/string)
**返回值**
返回包含参数编码值的字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT base32Encode('Encoded')
```
```response title=Response theme={null}
┌─base32Encode('Encoded')─┐
│ IVXGG33EMVSA==== │
└─────────────────────────┘
```
## base58Decode
引入于：v22.7.0
对 [Base58](https://datatracker.ietf.org/doc/html/draft-msporny-base58-03#section-3) 字符串进行解码。
如果字符串不是有效的 Base58 编码字符串，则会抛出异常。
可以提供可选的第二个参数 `expected_size`，以选择经过优化的固定大小解码器。
目前支持的值为 32 和 64。对于其他值，会使用通用解码器。
当选择了优化解码器，但输入无法被解码为恰好对应字节数时，
该函数会抛出异常 (对于 `tryBase58Decode`，则返回空字符串) 。
**语法**
```sql theme={null}
base58Decode(encoded[, expected_size])
```
**参数**
* `encoded` — 要解码的 String 类型列或常量。[`String`](/zh/reference/data-types/string)
* `expected_size` — 可选。预期的解码后大小 (以字节为单位) 。当该值为 32 或 64 时，使用优化解码器；其他值则使用通用解码器。[`UInt8, UInt16, UInt32, or UInt64`](/zh/reference/data-types/int-uint)
**返回值**
返回一个包含该参数解码后值的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT base58Decode('JxF12TrwUP45BMd');
```
```response title=Response theme={null}
┌─base58Decode⋯rwUP45BMd')─┐
│ Hello World │
└──────────────────────────┘
```
## base58Encode
首次引入版本：v22.7.0
使用 [Base58](https://tools.ietf.org/id/draft-msporny-base58-01.html) 对字符串进行编码。
**语法**
```sql theme={null}
base58Encode(plaintext)
```
**参数**
* `plaintext` — 要编码的明文。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个包含该参数编码值的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT base58Encode('ClickHouse');
```
```response title=Response theme={null}
┌─base58Encode('ClickHouse')─┐
│ 4nhk8K7GHXf6zx │
└────────────────────────────┘
```
## base64Decode
引入版本：v18.16.0
根据 RFC 4648，对 [Base64](https://en.wikipedia.org/wiki/Base64) 表示的字符串进行解码。
如果出错，则会抛出异常。
**语法**
```sql theme={null}
base64Decode(encoded)
```
**别名**: `FROM_BASE64`
**参数**
* `encoded` — 要解码的 `String` 类型列或常量。如果该字符串不是有效的 Base64 编码，则会抛出异常。[`String`](/zh/reference/data-types/string)
**返回值**
返回解码后的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT base64Decode('Y2xpY2tob3VzZQ==')
```
```response title=Response theme={null}
┌─base64Decode('Y2xpY2tob3VzZQ==')─┐
│ clickhouse │
└──────────────────────────────────┘
```
## base64Encode
引入版本：v18.16.0
根据 RFC 4648，使用 [Base64](https://en.wikipedia.org/wiki/Base64) 表示形式对字符串进行编码。
**语法**
```sql theme={null}
base64Encode(plaintext)
```
**别名**: `TO_BASE64`
**参数**
* `plaintext` — 要解码的明文列或常量。[`String`](/zh/reference/data-types/string)
**返回值**
返回包含该参数编码值的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT base64Encode('clickhouse')
```
```response title=Response theme={null}
┌─base64Encode('clickhouse')─┐
│ Y2xpY2tob3VzZQ== │
└────────────────────────────┘
```
## base64URLDecode
引入版本：v24.6.0
根据 RFC 4648，使用 URL 安全字母表对 [Base64](https://en.wikipedia.org/wiki/Base64) 表示的字符串进行解码。
出错时会抛出异常。
**语法**
```sql theme={null}
base64URLDecode(encoded)
```
**参数**
* `encoded` — 要进行编码的 String 类型列或常量。如果该字符串不是有效的 Base64 编码字符串，则会抛出异常。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个包含该参数解码后值的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT base64URLDecode('aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ')
```
```response title=Response theme={null}
┌─base64URLDecode('aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ')─┐
│ https://clickhouse.com │
└───────────────────────────────────────────────────┘
```
## base64URLEncode
引入版本：v18.16.0
使用 URL 安全字母表按 [Base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4) (RFC 4648) 表示形式对字符串进行编码。
**语法**
```sql theme={null}
base64URLEncode(plaintext)
```
**参数**
* `plaintext` — 要编码的明文列或常量。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个字符串，其中包含该参数编码后的值。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT base64URLEncode('https://clickhouse.com')
```
```response title=Response theme={null}
┌─base64URLEncode('https://clickhouse.com')─┐
│ aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ │
└───────────────────────────────────────────┘
```
## basename
Introduced in：v20.1.0
提取字符串中最后一个斜杠或反斜杠之后的部分。
此函数通常用于从路径中提取文件名。
**语法**
```sql theme={null}
basename(expr)
```
**参数**
* `expr` — 字符串表达式。反斜杠必须转义。[`String`](/zh/reference/data-types/string)
**返回值**
返回输入字符串中最后一个斜杠或反斜杠之后的部分。如果输入字符串以斜杠或反斜杠结尾，则函数返回空字符串。如果输入字符串中没有斜杠或反斜杠，则返回原始字符串。[`String`](/zh/reference/data-types/string)
**示例**
**从 Unix 路径中提取文件名**
```sql title=Query theme={null}
SELECT 'some/long/path/to/file' AS a, basename(a)
```
```response title=Response theme={null}
┌─a──────────────────────┬─basename('some/long/path/to/file')─┐
│ some/long/path/to/file │ file │
└────────────────────────┴────────────────────────────────────┘
```
**从 Windows 路径提取文件名**
```sql title=Query theme={null}
SELECT 'some\\long\\path\\to\\file' AS a, basename(a)
```
```response title=Response theme={null}
┌─a──────────────────────┬─basename('some\\long\\path\\to\\file')─┐
│ some\long\path\to\file │ file │
└────────────────────────┴────────────────────────────────────────┘
```
**不含路径分隔符的 String**
```sql title=Query theme={null}
SELECT 'some-file-name' AS a, basename(a)
```
```response title=Response theme={null}
┌─a──────────────┬─basename('some-file-name')─┐
│ some-file-name │ some-file-name │
└────────────────┴────────────────────────────┘
```
## byteHammingDistance
引入版本：v23.9.0
计算两个字节字符串之间的 [Hamming 距离](https://en.wikipedia.org/wiki/Hamming_distance)。
**语法**
```sql theme={null}
byteHammingDistance(s1, s2)
```
**别名**: `mismatches`
**参数**
* `s1` — 第一个输入字符串。[`String`](/zh/reference/data-types/string)
* `s2` — 第二个输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回这两个字符串之间的 Hamming 距离。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT byteHammingDistance('karolin', 'kathrin')
```
```response title=Response theme={null}
┌─byteHammingDistance('karolin', 'kathrin')─┐
│ 3 │
└───────────────────────────────────────────┘
```
## caseFoldUTF8
Introduced in: v26.3.0
对 UTF-8 字符串应用 Unicode 大小写折叠，将其转换为适合进行不区分大小写比较的类似小写的规范化结果。
应用标准的 Unicode 大小写折叠。保留不受大小写折叠影响的兼容字符
(例如罗马数字、带圈数字) ，但请注意，像 `ffi` 这样的某些连字仍会被分解，因为 Unicode 大小写折叠本身就会将其展开。
**Syntax**
```sql theme={null}
caseFoldUTF8(str)
```
**参数**
* `str` — UTF-8 编码的输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
进行大小写折叠后的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
**示例**
**基本的大小写折叠**
```sql title=Query theme={null}
SELECT caseFoldUTF8('Straße')
```
```response title=Response theme={null}
┌─caseFoldUTF8('Straße')─┐
│ strasse │
└─────────────────────────┘
```
## compareSubstrings
首次引入于：v25.2.0
按字典序比较两个字符串。
**语法**
```sql theme={null}
compareSubstrings(s1, s2, s1_offset, s2_offset, num_bytes)
```
**参数**
* `s1` — 要比较的第一个字符串。[`String`](/zh/reference/data-types/string)
* `s2` — 要比较的第二个字符串。[`String`](/zh/reference/data-types/string)
* `s1_offset` — 在 `s1` 中开始比较的位置 (从零开始) 。[`UInt*`](/zh/reference/data-types/int-uint)
* `s2_offset` — 在 `s2` 中开始比较的位置 (索引从零开始) 。[`UInt*`](/zh/reference/data-types/int-uint)
* `num_bytes` — 两个字符串中参与比较的最大字节数。如果 `s1_offset` (或 `s2_offset`) + `num_bytes` 超过输入字符串末尾，`num_bytes` 会相应减小。[`UInt*`](/zh/reference/data-types/int-uint)
**返回值**
返回：
* 如果 `s1`\[`s1_offset` : `s1_offset` + `num_bytes`] \< `s2`\[`s2_offset` : `s2_offset` + `num_bytes`]，则返回 `-1`。
* 如果 `s1`\[`s1_offset` : `s1_offset` + `num_bytes`] = `s2`\[`s2_offset` : `s2_offset` + `num_bytes`]，则返回 `0`。
* 如果 `s1`\[`s1_offset` : `s1_offset` + `num_bytes`] > `s2`\[`s2_offset` : `s2_offset` + `num_bytes`]，则返回 `1`。
[`Int8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT compareSubstrings('Saxony', 'Anglo-Saxon', 0, 6, 5) AS result
```
```response title=Response theme={null}
┌─result─┐
│ 0 │
└────────┘
```
## concat
Introduced in: v1.1.0
将给定的参数拼接起来。
不属于 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 类型的参数，会使用其默认序列化方式转换为字符串。
由于这会降低性能，因此不建议使用非 String/FixedString 参数。
**语法**
```sql theme={null}
concat([s1, s2, ...])
```
**参数**
* `s1, s2, ...` — 任意数量、任意类型的值。[`Any`](/zh/reference/data-types)
**返回值**
返回将这些参数连接后生成的 String。如果任一参数为 `NULL`，函数将返回 `NULL`。如果没有参数，则返回空字符串。[`Nullable(String)`](/zh/reference/data-types/nullable)
**示例**
**字符串拼接**
```sql title=Query theme={null}
SELECT concat('Hello, ', 'World!')
```
```response title=Response theme={null}
┌─concat('Hello, ', 'World!')─┐
│ Hello, World! │
└─────────────────────────────┘
```
**数字串联**
```sql title=Query theme={null}
SELECT concat(42, 144)
```
```response title=Response theme={null}
┌─concat(42, 144)─┐
│ 42144 │
└─────────────────┘
```
## concatAssumeInjective
Introduced in：v1.1.0
与 [`concat`](#concat) 类似，但假定 `concat(s1, s2, ...) → sn` 是单射，
也就是说，对于不同的参数会返回不同的结果。
可用于优化 `GROUP BY`。
**Syntax**
```sql theme={null}
concatAssumeInjective([s1, s2, ...])
```
**参数**
* `s1, s2, ...` — 任意数量、任意类型的值。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回将各参数拼接后得到的字符串。如果任一参数值为 `NULL`，函数返回 `NULL`。如果未传入任何参数，则返回空字符串。[`String`](/zh/reference/data-types/string)
**示例**
**Group By 优化**
```sql title=Query theme={null}
SELECT concat(key1, key2), sum(value) FROM key_val GROUP BY concatAssumeInjective(key1, key2)
```
```response title=Response theme={null}
┌─concat(key1, key2)─┬─sum(value)─┐
│ Hello, World! │ 3 │
│ Hello, World! │ 2 │
│ Hello, World │ 3 │
└────────────────────┴────────────┘
```
## concatWithSeparator
引入于：v22.12.0
将提供的字符串连接起来，并以指定的分隔符分隔。
**语法**
```sql theme={null}
concatWithSeparator(sep[, exp1, exp2, ...])
```
**别名**: `concat_ws`
**参数**
* `sep` — 使用的分隔符。[`const String`](/zh/reference/data-types/string) 或 [`const FixedString`](/zh/reference/data-types/fixedstring)
* `exp1, exp2, ...` — 要拼接的表达式。不属于 `String` 或 `FixedString` 类型的参数会通过其默认序列化转换为字符串。由于这会降低性能，因此不建议使用非 `String`/`FixedString` 参数。[`Any`](/zh/reference/data-types)
**返回值**
返回由拼接这些参数得到的 String。如果任一参数值为 `NULL`，函数将返回 `NULL`。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT concatWithSeparator('a', '1', '2', '3', '4')
```
```response title=Response theme={null}
┌─concatWithSeparator('a', '1', '2', '3', '4')─┐
│ 1a2a3a4 │
└──────────────────────────────────────────────┘
```
## concatWithSeparatorAssumeInjective
Introduced in：v22.12.0
与 [`concatWithSeparator`](#concatWithSeparator) 类似，但假定 `concatWithSeparator(sep[,exp1, exp2, ... ]) → result` 是单射。
如果一个函数对不同参数返回不同结果，则称该函数为单射函数。
可用于优化 `GROUP BY`。
**语法**
```sql theme={null}
concatWithSeparatorAssumeInjective(sep[, exp1, exp2, ... ])
```
**参数**
* `sep` — 使用的分隔符。[`const String`](/zh/reference/data-types/string) 或 [`const FixedString`](/zh/reference/data-types/fixedstring)
* `exp1, exp2, ...` — 要拼接的表达式。不属于 `String` 或 `FixedString` 类型的参数会使用其默认序列化方式转换为字符串。由于这会降低性能，因此不建议使用非 `String`/`FixedString` 参数。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回由参数拼接而成的 String。如果任一参数值为 `NULL`，则函数返回 `NULL`。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
CREATE TABLE user_data (
user_id UInt32,
first_name String,
last_name String,
score UInt32
)
ENGINE = MergeTree
ORDER BY tuple();
INSERT INTO user_data VALUES
(1, 'John', 'Doe', 100),
(2, 'Jane', 'Smith', 150),
(3, 'John', 'Wilson', 120),
(4, 'Jane', 'Smith', 90);
SELECT
concatWithSeparatorAssumeInjective('-', first_name, last_name) as full_name,
sum(score) as total_score
FROM user_data
GROUP BY concatWithSeparatorAssumeInjective('-', first_name, last_name);
```
```response title=Response theme={null}
┌─full_name───┬─total_score─┐
│ Jane-Smith │ 240 │
│ John-Doe │ 100 │
│ John-Wilson │ 120 │
└─────────────┴─────────────┘
```
## conv
引入版本：v25.10.0
在不同数制之间转换数字。
该函数可将数字从一种数制转换为另一种数制，支持 2 到 36 进制。
对于大于 10 的进制，使用字母 A-Z (不区分大小写) 表示数字 10-35。
该函数与 MySQL 的 CONV() 函数兼容。
**语法**
```sql theme={null}
conv(number, from_base, to_base)
```
**参数**
* `number` — 要转换的数字。可以是字符串或数值类型。 - `from_base` — 源进制 (2-36) 。必须是整数。 - `to_base` — 目标进制 (2-36) 。必须是整数。
**返回值**
该数字在目标进制中的字符串表示形式。
**示例**
**将十进制转换为二进制**
```sql title=Query theme={null}
SELECT conv('10', 10, 2)
```
```response title=Response theme={null}
1010
```
**将十六进制转换为十进制**
```sql title=Query theme={null}
SELECT conv('FF', 16, 10)
```
```response title=Response theme={null}
255
```
**用负数转换**
```sql title=Query theme={null}
SELECT conv('-1', 10, 16)
```
```response title=Response theme={null}
FFFFFFFFFFFFFFFF
```
**将二进制转换为八进制**
```sql title=Query theme={null}
SELECT conv('1010', 2, 8)
```
```response title=Response theme={null}
12
```
## convertCharset
引入版本：v1.1.0
返回将字符串 `s` 从编码 `from` 转换为编码 `to` 后的结果。
**语法**
```sql theme={null}
convertCharset(s, from, to)
```
**参数**
* `s` — 输入的字符串。[`String`](/zh/reference/data-types/string)
* `from` — 源字符编码。[`String`](/zh/reference/data-types/string)
* `to` — 目标字符编码。[`String`](/zh/reference/data-types/string)
**返回值**
返回将字符串 `s` 从编码 `from` 转换为编码 `to` 后的结果。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT convertCharset('Café', 'UTF-8', 'ISO-8859-1');
```
```response title=Response theme={null}
┌─convertChars⋯SO-8859-1')─┐
│ Caf� │
└──────────────────────────┘
```
## damerauLevenshteinDistance
引入版本：v24.1.0
计算两个字节字符串之间的 [Damerau-Levenshtein 距离](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance)。
**语法**
```sql theme={null}
damerauLevenshteinDistance(s1, s2)
```
**参数**
* `s1` — 第一个输入字符串。[`String`](/zh/reference/data-types/string)
* `s2` — 第二个输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回两个字符串之间的 Damerau-Levenshtein 距离。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT damerauLevenshteinDistance('clickhouse', 'mouse')
```
```response title=Response theme={null}
┌─damerauLevenshteinDistance('clickhouse', 'mouse')─┐
│ 6 │
└───────────────────────────────────────────────────┘
```
## decodeHTMLComponent
引入版本：v23.9.0
将字符串中的 HTML 实体解码为对应的字符。
**语法**
```sql theme={null}
decodeHTMLComponent(s)
```
**参数**
* `s` — 包含要解码的 HTML 实体的 String。[`String`](/zh/reference/data-types/string)
**返回值**
返回将 HTML 实体解码后的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT decodeHTMLComponent('<div>Hello & "World"</div>')
```
```response title=Response theme={null}
┌─decodeHTMLComponent('<div>Hello & "World"</div>')─┐
│ Hello & "World"
│
└─────────────────────────────────────────────────────────────────────────────┘
```
## decodeXMLComponent
自 v21.2.0 引入
将字符串中的 XML 实体解码为对应的字符。
**语法**
```sql theme={null}
decodeXMLComponent(s)
```
**参数**
* `s` — 包含待解码 XML 实体的 String。[`String`](/zh/reference/data-types/string)
**返回值**
返回对所提供字符串中的 XML 实体解码后的结果。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT decodeXMLComponent('<tag>Hello & World</tag>')
```
```response title=Response theme={null}
┌─decodeXMLCom⋯;/tag>')─┐
│ Hello & World │
└──────────────────────────┘
```
## editDistance
自 v23.9.0 引入
计算两个字节字符串之间的[编辑距离](https://en.wikipedia.org/wiki/Edit_distance)。
**语法**
```sql theme={null}
editDistance(s1, s2)
```
**别名**: `levenshteinDistance`
**参数**
* `s1` — 第一个输入字符串。[`String`](/zh/reference/data-types/string)
* `s2` — 第二个输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回这两个字符串之间的编辑距离。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT editDistance('clickhouse', 'mouse')
```
```response title=Response theme={null}
┌─editDistance('clickhouse', 'mouse')─┐
│ 6 │
└─────────────────────────────────────┘
```
## editDistanceUTF8
引入版本：v24.6.0
计算两个 UTF8 字符串之间的[编辑距离](https://en.wikipedia.org/wiki/Edit_distance)。
**语法**
```sql theme={null}
editDistanceUTF8(s1, s2)
```
**别名**: `levenshteinDistanceUTF8`
**参数**
* `s1` — 第一个输入字符串。[`String`](/zh/reference/data-types/string)
* `s2` — 第二个输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回两个 UTF8 字符串之间的编辑距离。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT editDistanceUTF8('我是谁', '我是我')
```
```response title=Response theme={null}
┌─editDistanceUTF8('我是谁', '我是我')──┐
│ 1 │
└─────────────────────────────────────┘
```
## encodeXMLComponent
引入版本：v21.1.0
对字符进行转义，以便将字符串置于 XML 文本节点或属性中。
**语法**
```sql theme={null}
encodeXMLComponent(s)
```
**参数**
* `s` — 待转义的 String。[`String`](/zh/reference/data-types/string)
**返回值**
返回转义后的 String。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
'Hello & "World"' AS original,
encodeXMLComponent('Hello & "World"') AS xml_encoded;
```
```response title=Response theme={null}
┌─original───────────────────┬─xml_encoded──────────────────────────────────────────┐
│ Hello & "World" │ <tag>Hello & "World"</tag> │
└────────────────────────────┴──────────────────────────────────────────────────────┘
```
## endsWith
引入版本：v1.1.0
检查字符串是否以给定的后缀结尾。
**语法**
```sql theme={null}
endsWith(s, suffix)
```
**参数**
* `s` — 要检查的字符串。[`String`](/zh/reference/data-types/string)
* `suffix` — 要检查的后缀。[`String`](/zh/reference/data-types/string)
**返回值**
如果 `s` 以 `suffix` 结尾，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT endsWith('ClickHouse', 'House');
```
```response title=Response theme={null}
┌─endsWith('Cl⋯', 'House')─┐
│ 1 │
└──────────────────────────┘
```
## endsWithCaseInsensitive
引入版本：v25.10.0
检查字符串是否以给定的、不区分大小写的后缀结尾。
**语法**
```sql theme={null}
endsWithCaseInsensitive(s, suffix)
```
**参数**
* `s` — 要检查的字符串。[`String`](/zh/reference/data-types/string)
* `suffix` — 要检查的、不区分大小写的后缀。[`String`](/zh/reference/data-types/string)
**返回值**
如果 `s` 以不区分大小写的 `suffix` 结尾，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT endsWithCaseInsensitive('ClickHouse', 'HOUSE');
```
```response title=Response theme={null}
┌─endsWithCaseInsensitive('Cl⋯', 'HOUSE')─┐
│ 1 │
└─────────────────────────────────────────┘
```
## endsWithCaseInsensitiveUTF8
首次引入于：v25.10.0
返回字符串 `s` 是否以不区分大小写的 `suffix` 结尾。
假定该字符串包含有效的 UTF-8 编码文本。
如果不满足这一假定，不会抛出异常，结果未定义。
**语法**
```sql theme={null}
endsWithCaseInsensitiveUTF8(s, suffix)
```
**参数**
* `s` — 要检查的字符串。[`String`](/zh/reference/data-types/string)
* `suffix` — 要检查的、不区分大小写的后缀。[`String`](/zh/reference/data-types/string)
**返回值**
如果 `s` 以不区分大小写的 `suffix` 结尾，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT endsWithCaseInsensitiveUTF8('данных', 'ых');
```
```response title=Response theme={null}
┌─endsWithCaseInsensitiveUTF8('данных', 'ых')─┐
│ 1 │
└─────────────────────────────────────────────┘
```
## endsWithUTF8
引入版本：v23.8.0
返回字符串 `s` 是否以 `suffix` 结尾。
假定该字符串包含有效的 UTF-8 编码文本。
如果不满足这一假定，不会抛出异常，结果未定义。
**语法**
```sql theme={null}
endsWithUTF8(s, suffix)
```
**参数**
* `s` — 要检查的字符串。[`String`](/zh/reference/data-types/string)
* `suffix` — 要检查的后缀。[`String`](/zh/reference/data-types/string)
**返回值**
如果 `s` 以 `suffix` 结尾，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT endsWithUTF8('данных', 'ых');
```
```response title=Response theme={null}
┌─endsWithUTF8('данных', 'ых')─┐
│ 1 │
└──────────────────────────────┘
```
Introduced in：v21.3.0
从 HTML 或 XHTML 中提取文本内容。
此函数会移除 HTML 标签、注释以及 script/style 元素，仅保留文本内容。它支持：
* 移除所有 HTML/XML 标签
* 移除注释 (`{/* */}`)
* 移除 script 和 style 元素及其内容
* 处理 CDATA 区段 (按原样复制)
* 正确处理并规范化空白字符
注意：HTML 实体不会被解码，如有需要，应使用单独的函数处理。
**Syntax**
```sql theme={null}
extractTextFromHTML(html)
```
**参数**
* `html` — 包含要从中提取文本的 HTML 内容的 String。[`String`](/zh/reference/data-types/string)
**返回值**
返回提取出的文本内容，其中空白字符会被归一化。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT extractTextFromHTML('
Page Title
Hello World!
');
```
```response title=Response theme={null}
┌─extractTextFromHTML('...')─┐
│ Page Title Hello World! │
└────────────────────────────────────────┘
```
## firstLine
引入版本：v23.7.0
返回多行字符串中的第一行。
**语法**
```sql theme={null}
firstLine(s)
```
**参数**
* `s` — 输入的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回输入字符串的第一行；如果没有行分隔符，则返回整个字符串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT firstLine('foo\\nbar\\nbaz')
```
```response title=Response theme={null}
┌─firstLine('foo\nbar\nbaz')─┐
│ foo │
└────────────────────────────┘
```
## idnaDecode
引入版本：v24.1.0
根据 [Internationalized Domain Names in Applications](https://en.wikipedia.org/wiki/Internationalized_domain_name#Internationalizing_Domain_Names_in_Applications) (IDNA) 机制，返回域名的 Unicode (UTF-8) 表示形式 (ToUnicode 算法) 。
如果发生错误 (例如输入无效) ，则返回输入字符串。
请注意，由于大小写规范化，反复应用 [`idnaEncode()`](#idnaEncode) 和 [`idnaDecode()`](#idnaDecode) 后，返回的结果不一定是原始字符串。
**语法**
```sql theme={null}
idnaDecode(s)
```
**参数**
* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
根据输入值的 IDNA 机制，返回输入字符串的 Unicode (UTF-8) 形式。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT idnaDecode('xn--strae-oqa.xn--mnchen-3ya.de')
```
```response title=Response theme={null}
┌─idnaDecode('xn--strae-oqa.xn--mnchen-3ya.de')─┐
│ straße.münchen.de │
└───────────────────────────────────────────────┘
```
## idnaEncode
引入版本：v24.1.0
根据 [Internationalized Domain Names in Applications](https://en.wikipedia.org/wiki/Internationalized_domain_name#Internationalizing_Domain_Names_in_Applications) (IDNA) 机制，返回域名的 ASCII 表示形式 (ToASCII 算法) 。
输入字符串必须采用 UTF 编码，且能够转换为 ASCII 字符串，否则将抛出异常。
不会执行百分号解码，也不会去除制表符、空格或控制字符。
**语法**
```sql theme={null}
idnaEncode(s)
```
**参数**
* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
根据输入值的 IDNA 机制，返回输入字符串的 ASCII 表示形式。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT idnaEncode('straße.münchen.de')
```
```response title=Response theme={null}
┌─idnaEncode('straße.münchen.de')─────┐
│ xn--strae-oqa.xn--mnchen-3ya.de │
└─────────────────────────────────────┘
```
## initcap
Introduced in: v23.7.0
将每个单词的首字母转换为大写，其余字母转换为小写。
单词是由非字母数字字符分隔的字母数字字符序列。
由于 `initcap` 只会将每个单词的首字母转换为大写，因此对于包含撇号或大写字母的单词，结果可能不符合预期。
这是已知行为，目前暂无修复计划。
**Syntax**
```sql theme={null}
initcap(s)
```
**参数**
* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回将 `s` 中每个单词的首字母转换为大写后的结果。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT initcap('building for fast')
```
```response title=Response theme={null}
┌─initcap('building for fast')─┐
│ Building For Fast │
└──────────────────────────────┘
```
**包含撇号或大写字母的单词的已知行为示例**
```sql title=Query theme={null}
SELECT initcap('John''s cat won''t eat.');
```
```response title=Response theme={null}
┌─initcap('Joh⋯n\'t eat.')─┐
│ John'S Cat Won'T Eat. │
└──────────────────────────┘
```
## initcapUTF8
引入版本：v23.7.0
与 [`initcap`](#initcap) 类似，`initcapUTF8` 会将每个单词的首字母转换为大写，其余字母转换为小写。
假定该字符串包含有效的 UTF-8 编码文本。
如果不满足这一假设，不会抛出异常，结果未定义。
此函数不会检测语言，例如对于土耳其语，结果可能并不完全正确 (i/İ 与 i/I) 。
如果某个码点的大写和小写形式对应的 UTF-8 字节序列长度不同，则该码点的结果可能不正确。
**语法**
```sql theme={null}
initcapUTF8(s)
```
**参数**
* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回将 `s` 中每个单词的首字母转换为大写后的结果。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT initcapUTF8('не тормозит')
```
```response title=Response theme={null}
┌─initcapUTF8('не тормозит')─┐
│ Не Тормозит │
└────────────────────────────┘
```
## isValidASCII
引入版本：v25.9.0
如果输入的 String 或 FixedString 仅包含 ASCII 字节 (0x00–0x7F) ，则返回 1，否则返回 0。针对正向场景 (即输入 *是* 有效 ASCII) 进行了优化。
**语法**
```sql theme={null}
isValidASCII(str)
```
**别名**：`isASCII`
**参数**
* 无。
**返回值**
**示例**
**isValidASCII**
```sql title=Query theme={null}
SELECT isValidASCII('hello') AS is_ascii, isValidASCII('你好') AS is_not_ascii
```
```response title=Response theme={null}
```
## isValidUTF8
引入版本：v20.1.0
检查这组字节是否为有效的 UTF-8 编码文本。
**语法**
```sql theme={null}
isValidUTF8(s)
```
**参数**
* `s` — 要检查是否为有效 UTF-8 编码的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
如果该字节序列构成有效的 UTF-8 编码文本，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT isValidUTF8('\\xc3\\xb1') AS valid, isValidUTF8('\\xc3\\x28') AS invalid
```
```response title=Response theme={null}
┌─valid─┬─invalid─┐
│ 1 │ 0 │
└───────┴─────────┘
```
## jaroSimilarity
引入版本：v24.1.0
计算两个字节字符串之间的 [Jaro 相似度](https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance#Jaro_similarity)。
**语法**
```sql theme={null}
jaroSimilarity(s1, s2)
```
**参数**
* `s1` — 第一个输入字符串。[`String`](/zh/reference/data-types/string)
* `s2` — 第二个输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回这两个字符串之间的 Jaro 相似度。[`Float64`](/zh/reference/data-types/float)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT jaroSimilarity('clickhouse', 'click')
```
```response title=Response theme={null}
┌─jaroSimilarity('clickhouse', 'click')─┐
│ 0.8333333333333333 │
└───────────────────────────────────────┘
```
## jaroWinklerSimilarity
首次引入版本：v24.1.0
计算两个字节字符串之间的 [Jaro-Winkler 相似性](https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance)。
**语法**
```sql theme={null}
jaroWinklerSimilarity(s1, s2)
```
**参数**
* `s1` — 第一个输入字符串。[`String`](/zh/reference/data-types/string)
* `s2` — 第二个输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回两个字符串之间的 Jaro-Winkler 相似度。[`Float64`](/zh/reference/data-types/float)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT jaroWinklerSimilarity('clickhouse', 'click')
```
```response title=Response theme={null}
┌─jaroWinklerSimilarity('clickhouse', 'click')─┐
│ 0.8999999999999999 │
└──────────────────────────────────────────────┘
```
## left
版本引入：v22.1.0
返回字符串 `s` 中从左侧按指定 `offset` 开始的子串。
**语法**
```sql theme={null}
left(s, offset)
```
**参数**
* `s` — 要从中提取子串的字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `offset` — 偏移量的字节数。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回：
* 当 `offset` 为正数时，返回从字符串左侧开始、长度为 `offset` 字节的 `s` 的子串。
* 当 `offset` 为负数时，返回从字符串左侧开始、长度为 `length(s) - |offset|` 字节的 `s` 的子串。
* 如果 `length` 为 `0`，则返回空字符串。
[`String`](/zh/reference/data-types/string)
**示例**
**正偏移量**
```sql title=Query theme={null}
SELECT left('Hello World', 5)
```
```response title=Response theme={null}
Hello
```
**负偏移量**
```sql title=Query theme={null}
SELECT left('Hello World', -6)
```
```response title=Response theme={null}
Hello
```
## leftPad
引入版本：v21.8.0
从左侧使用空格或指定字符串 (如有需要可重复多次) 填充字符串，直到结果字符串达到指定的 `length`。
**语法**
```sql theme={null}
leftPad(string, length[, pad_string])
```
**别名**: `lpad`
**参数**
* `string` — 要进行填充的输入字符串。[`String`](/zh/reference/data-types/string)
* `length` — 结果字符串的长度。如果该值小于输入字符串的长度，则输入字符串会被截断为 `length` 个字符。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `pad_string` — 可选。用于填充输入字符串的字符串。如果未指定，则使用空格对输入字符串进行填充。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个左侧填充到指定长度的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT leftPad('abc', 7, '*'), leftPad('def', 7)
```
```response title=Response theme={null}
┌─leftPad('abc', 7, '*')─┬─leftPad('def', 7)─┐
│ ****abc │ def │
└────────────────────────┴───────────────────┘
```
## leftPadUTF8
Introduced in：v21.8.0
从左侧用空格或指定字符串填充 UTF8 字符串 (如有需要可重复多次) ，直到结果字符串达到给定长度。
不同于按字节计算字符串长度的 [`leftPad`](#leftPad)，此处的字符串长度按码点计算。
**语法**
```sql theme={null}
leftPadUTF8(string, length[, pad_string])
```
**参数**
* `string` — 需要填充的输入字符串。[`String`](/zh/reference/data-types/string)
* `length` — 结果字符串的长度。如果该值小于输入字符串的长度，则输入字符串会被截短为 `length` 个字符。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `pad_string` — 可选。用于填充输入字符串的字符串。如果未指定，则使用空格填充输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个左侧填充到给定长度的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT leftPadUTF8('абвг', 7, '*'), leftPadUTF8('дежз', 7)
```
```response title=Response theme={null}
┌─leftPadUTF8('абвг', 7, '*')─┬─leftPadUTF8('дежз', 7)─┐
│ ***абвг │ дежз │
└─────────────────────────────┴────────────────────────┘
```
## leftUTF8
引入版本：v22.1.0
返回 UTF-8 编码字符串 `s` 中从左侧开始、指定 `offset` 的子串。
**语法**
```sql theme={null}
leftUTF8(s, offset)
```
**参数**
* `s` — 用于计算子串的 UTF-8 编码字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `offset` — 偏移的字节数。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回：
* 当 `offset` 为正数时，返回 `s` 的子串，长度为 `offset` 个字节，从字符串左侧开始。\n"
* 当 `offset` 为负数时，返回 `s` 的子串，长度为 `length(s) - |offset|` 个字节，从字符串左侧开始。\n"
* 如果 `length` 为 0，则返回空字符串。
[`String`](/zh/reference/data-types/string)
**示例**
**正偏移量**
```sql title=Query theme={null}
SELECT leftUTF8('Привет', 4)
```
```response title=Response theme={null}
Прив
```
**负数偏移量**
```sql title=Query theme={null}
SELECT leftUTF8('Привет', -4)
```
```response title=Response theme={null}
Пр
```
## lengthUTF8
引入版本：v1.1.0
返回字符串的长度，以 Unicode 码点数计，而不是以字节数或字符数计。
它假定字符串包含有效的 UTF-8 编码文本。
如果这一假定不成立，不会抛出异常，结果未定义。
**语法**
```sql theme={null}
lengthUTF8(s)
```
**别名**: `CHARACTER_LENGTH`, `CHAR_LENGTH`
**参数**
* `s` — 包含有效 UTF-8 编码文本的 String。[`String`](/zh/reference/data-types/string)
**返回值**
字符串 `s` 的长度 (以 Unicode 码点数计) 。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT lengthUTF8('Здравствуй, мир!')
```
```response title=Response theme={null}
┌─lengthUTF8('Здравствуй, мир!')─┐
│ 16 │
└────────────────────────────────┘
```
## lower
引入版本：v1.1.0
将 ASCII 字符串转换为小写。
**语法**
```sql theme={null}
lower(s)
```
**别名**: `lcase`
**参数**
* `s` — 要转换为小写的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回将 `s` 转换为小写后的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT lower('CLICKHOUSE')
```
```response title=Response theme={null}
┌─lower('CLICKHOUSE')─┐
│ clickhouse │
└─────────────────────┘
```
## lowerUTF8
引入版本：v1.1.0
将字符串转换为小写，前提是字符串包含有效的 UTF-8 编码文本。如果不满足此前提，则不会抛出异常，返回结果未定义。
**语法**
```sql theme={null}
lowerUTF8(input)
```
**参数**
* `input` — 要转换为小写的输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回小写字符串。[`String`](/zh/reference/data-types/string)
**示例**
**第一个**
```sql title=Query theme={null}
SELECT lowerUTF8('München') as Lowerutf8;
```
```response title=Response theme={null}
münchen
```
## naturalSortKey
引入版本：v26.3.0
该函数用于自然排序。
**语法**
```sql theme={null}
naturalSortKey(s)
```
**别名**: `NATURAL_SORT_KEY`
**参数**
* `s` — 要转换为自然排序键的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回由 `s` 转换得到的自然排序键字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT s FROM t ORDER BY naturalSortKey(s)
```
```response title=Response theme={null}
┌─s───┐
│ a1 │
| a02 │
└─────┘
```
## normalizeUTF8NFC
引入版本：v21.11.0
根据 [NFC 规范化形式](https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms)对 UTF-8 字符串进行规范化。
**语法**
```sql theme={null}
normalizeUTF8NFC(str)
```
**参数**
* `str` — UTF-8 编码的输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UTF-8 字符串的 NFC 规范化结果。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT
'é' AS original, -- e + 组合尖音符 (U+0065 + U+0301)
length(original),
normalizeUTF8NFC('é') AS nfc_normalized, -- é (U+00E9)
length(nfc_normalized);
```
```response title=Response theme={null}
┌─original─┬─length(original)─┬─nfc_normalized─┬─length(nfc_normalized)─┐
│ é │ 2 │ é │ 2 │
└──────────┴──────────────────┴────────────────┴────────────────────────┘
```
## normalizeUTF8NFD
引入版本：v21.11.0
按照 [NFD 规范化结果](https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms) 对 UTF-8 字符串进行规范化。
**语法**
```sql theme={null}
normalizeUTF8NFD(str)
```
**参数**
* `str` — UTF-8 编码的输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UTF-8 字符串的 NFD 规范化结果。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
'é' AS original, -- é (U+00E9)
length(original),
normalizeUTF8NFD('é') AS nfd_normalized, -- e + 组合重音符（U+0065 + U+0301）
length(nfd_normalized);
```
```response title=Response theme={null}
┌─original─┬─length(original)─┬─nfd_normalized─┬─length(nfd_normalized)─┐
│ é │ 2 │ é │ 3 │
└──────────┴──────────────────┴────────────────┴────────────────────────┘
```
## normalizeUTF8NFKC
首次引入于：v21.11.0
按照 [NFKC 规范化结果](https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms) 对 UTF-8 字符串进行规范化。
**语法**
```sql theme={null}
normalizeUTF8NFKC(str)
```
**参数**
* `str` — UTF-8 编码的输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UTF-8 字符串的 NFKC 规范化结果。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
'① ② ③' AS original, -- 带圆圈的数字字符
normalizeUTF8NFKC('① ② ③') AS nfkc_normalized; -- 转换为 1 2 3
```
```response title=Response theme={null}
┌─original─┬─nfkc_normalized─┐
│ ① ② ③ │ 1 2 3 │
└──────────┴─────────────────┘
```
## normalizeUTF8NFKCCasefold
引入版本：v26.3.0
根据 [NFKC\_Casefold 规范化结果](https://unicode.org/reports/tr44/#NFKC_Casefold) 对 UTF-8 字符串进行规范化，即先执行 NFKC 规范化，再进行大小写折叠。
这对于不区分大小写地匹配标识符非常有用。
**语法**
```sql theme={null}
normalizeUTF8NFKCCasefold(str)
```
**参数**
* `str` — UTF-8 编码的输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UTF-8 字符串的 NFKC\_Casefold 规范化结果。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
'Ä ① Hello' AS original,
normalizeUTF8NFKCCasefold('Ä ① Hello') AS nfkc_cf_normalized;
```
```response title=Response theme={null}
┌─original───┬─nfkc_cf_normalized─┐
│ Ä ① Hello │ ä 1 hello │
└────────────┴────────────────────┘
```
## normalizeUTF8NFKD
引入版本：v21.11.0
按照 [NFKD 规范化形式](https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms)对 UTF-8 字符串进行规范化。
**语法**
```sql theme={null}
normalizeUTF8NFKD(str)
```
**参数**
* `str` — UTF-8 编码的输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回该 UTF-8 字符串的 NFKD 规范化结果。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
'H₂O²' AS original, -- H + 下标 2 + O + 上标 2
normalizeUTF8NFKD('H₂O²') AS nfkd_normalized; -- 转换为 H 2 O 2
```
```response title=Response theme={null}
┌─original─┬─nfkd_normalized─┐
│ H₂O² │ H2O2 │
└──────────┴─────────────────┘
```
## punycodeDecode
引入版本：v24.1.0
返回 [Punycode](https://en.wikipedia.org/wiki/Punycode) 编码字符串对应的 UTF8 编码明文。
如果给定的不是有效的 Punycode 编码字符串，则会抛出异常。
**语法**
```sql theme={null}
punycodeDecode(s)
```
**参数**
* `s` — 采用 Punycode 编码的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回输入值的明文形式。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT punycodeDecode('Mnchen-3ya')
```
```response title=Response theme={null}
┌─punycodeDecode('Mnchen-3ya')─┐
│ München │
└──────────────────────────────┘
```
## punycodeEncode
引入版本：v24.1.0
返回字符串的 [Punycode](https://en.wikipedia.org/wiki/Punycode) 表示。
字符串必须采用 UTF8 编码，否则行为未定义。
**语法**
```sql theme={null}
punycodeEncode(s)
```
**参数**
* `s` — 输入值。[`String`](/zh/reference/data-types/string)
**返回值**
返回输入值的 Punycode 表示。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT punycodeEncode('München')
```
```response title=Response theme={null}
┌─punycodeEncode('München')─┐
│ Mnchen-3ya │
└───────────────────────────┘
```
引入版本：v23.2.0
从 `haystack` 中提取第一个匹配正则表达式 pattern 且对应指定正则分组索引的字符串。
**语法**
```sql theme={null}
regexpExtract(haystack, pattern[, index])
```
**别名**: `REGEXP_EXTRACT`
**参数**
* `haystack` — String，待进行正则表达式模式匹配的字符串。[`String`](/zh/reference/data-types/string)
* `pattern` — String，正则表达式。`pattern` 可以包含多个正则分组，`index` 指定要提取的正则分组。索引为 0 表示匹配整个正则表达式。[`const String`](/zh/reference/data-types/string)
* `index` — 可选。一个大于或等于 0 的整数，默认值为 1。表示要提取的正则分组。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回匹配到的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
regexpExtract('100-200', '(\\d+)-(\\d+)', 1),
regexpExtract('100-200', '(\\d+)-(\\d+)', 2),
regexpExtract('100-200', '(\\d+)-(\\d+)', 0),
regexpExtract('100-200', '(\\d+)-(\\d+)');
```
```response title=Response theme={null}
┌─regexpExtract('100-200', '(\\d+)-(\\d+)', 1)─┬─regexpExtract('100-200', '(\\d+)-(\\d+)', 2)─┬─regexpExtract('100-200', '(\\d+)-(\\d+)', 0)─┬─regexpExtract('100-200', '(\\d+)-(\\d+)')─┐
│ 100 │ 200 │ 100-200 │ 100 │
└──────────────────────────────────────────────┴──────────────────────────────────────────────┴──────────────────────────────────────────────┴───────────────────────────────────────────┘
```
## regexpPosition
引入版本：v26.5.0
返回 `pattern` 在 `haystack` 中第 `occurrence` 次匹配的字节位置 (从 1 开始) ，搜索从字节位置 `position` 开始。
如果 `return_option` 为 0 (默认值) ，则返回匹配结果第一个字节的位置；如果为 1，则返回匹配结束后第一个字节的位置。
如果 `subexpression` 大于 0，则返回相应捕获组的位置，而不是整个匹配的位置。
如果未找到匹配，或所请求的捕获组未参与匹配，则返回 0。
此函数用于兼容 PostgreSQL 的 `regexp_instr` (也以该别名提供) 。请注意，这里的位置按字节计算，与其他 ClickHouse 正则函数一致；而 PostgreSQL 的 `regexp_instr` 按字符计算。
**语法**
```sql theme={null}
regexpPosition(haystack, pattern[, position[, occurrence[, return_option[, flags[, subexpression]]]]])
```
**别名**: `regexpInstr`, `regexp_instr`
**参数**
* `haystack` — 待搜索的字符串。[`String`](/zh/reference/data-types/string)
* `pattern` — 正则表达式模式。[`const String`](/zh/reference/data-types/string)
* `position` — 可选。开始搜索的字节位置，从 1 开始计数。默认值：1。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `occurrence` — 可选。返回第几个匹配项。默认值：1。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `return_option` — 可选。0 返回匹配的起始位置，1 返回匹配结束后紧接着的位置。默认值：0。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `flags` — 可选。正则标志。支持：`i` (不区分大小写) 、`c` (区分大小写) 、`m`/`n` (多行锚点) 、`s` (点号匹配换行符) 。默认值：空字符串。[`const String`](/zh/reference/data-types/string)
* `subexpression` — 可选。要返回其位置的捕获组索引。0 表示整个匹配。默认值：0。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回匹配的字节位置；如果未找到，则返回 0。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**基本用法**
```sql title=Query theme={null}
SELECT
regexpPosition('hello world', 'world'),
regexpPosition('aXbXcXd', 'X', 1, 2),
regexpPosition('aXbXcXd', 'X', 1, 2, 1),
regexpPosition('Hello WORLD', 'world', 1, 1, 0, 'i'),
regexpPosition('foo123bar456', '([a-z]+)([0-9]+)', 1, 2, 0, '', 2);
```
```response title=Response theme={null}
┌─...─┬─...─┬─...─┬─...─┬─...─┐
│ 7 │ 4 │ 5 │ 7 │ 10 │
└─────┴─────┴─────┴─────┴─────┘
```
## removeDiacriticsUTF8
Introduced in: v26.3.0
通过先使用 NFD 分解字符、
去除组合附加符号 (Unicode 类别 Mn) ，再使用 NFC 重新组合，从 UTF-8 字符串中移除变音符号 (重音) 。
**Syntax**
```sql theme={null}
removeDiacriticsUTF8(str)
```
**别名**: `removeAccentsUTF8`
**参数**
* `str` — UTF-8 编码的输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
移除变音符号后的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
**示例**
**基本重音去除**
```sql title=Query theme={null}
SELECT removeDiacriticsUTF8('café résumé naïve')
```
```response title=Response theme={null}
┌─removeDiacriticsUTF8('café résumé naïve')─┐
│ cafe resume naive │
└────────────────────────────────────────────┘
```
## repeat
引入版本：v20.1.0
按指定次数将一个字符串与自身连接。
**语法**
```sql theme={null}
repeat(s, n)
```
**参数**
* `s` — 要重复的字符串。[`String`](/zh/reference/data-types/string)
* `n` — 字符串的重复次数。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
将字符串 `s` 重复 `n` 次后得到的字符串。如果 `n` 为负数，函数将返回空字符串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT repeat('abc', 10)
```
```response title=Response theme={null}
┌─repeat('abc', 10)──────────────┐
│ abcabcabcabcabcabcabcabcabcabc │
└────────────────────────────────┘
```
## reverseUTF8
引入版本：v1.1.0
反转字符串中的 Unicode 码点序列。
假定该字符串包含有效的 UTF-8 编码文本。
如果不满足这一假定，则不会抛出异常，结果未定义。
**语法**
```sql theme={null}
reverseUTF8(s)
```
**参数**
* `s` — 包含有效 UTF-8 编码文本的 String。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个将 Unicode 码点序列倒序后的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT reverseUTF8('ClickHouse')
```
```response title=Response theme={null}
esuoHkcilC
```
## right
首次引入版本：v22.1.0
返回字符串 `s` 中从右侧开始、以指定 `offset` 为起点的子串。
**语法**
```sql theme={null}
right(s, offset)
```
**参数**
* `s` — 要从中提取子串的字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `offset` — 偏移量的字节数。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回：
* 当 `offset` 为正数时，返回从字符串右侧开始、长度为 `offset` 字节的 `s` 的子串。
* 当 `offset` 为负数时，返回从字符串右侧开始、长度为 `length(s) - |offset|` 字节的 `s` 的子串。
* 如果 `length` 为 `0`，则返回空字符串。
[`String`](/zh/reference/data-types/string)
**示例**
**正偏移量**
```sql title=Query theme={null}
SELECT right('Hello', 3)
```
```response title=Response theme={null}
llo
```
**负偏移**
```sql title=Query theme={null}
SELECT right('Hello', -3)
```
```response title=Response theme={null}
lo
```
## rightPad
Introduced in: v21.8.0
在字符串右侧填充空格或指定字符串 (如有需要可重复多次) ，直到结果字符串达到指定的 `length`。
**语法**
```sql theme={null}
rightPad(string, length[, pad_string])
```
**别名**: `rpad`
**参数**
* `string` — 需要填充的输入字符串。[`String`](/zh/reference/data-types/string)
* `length` — 结果字符串的长度。如果该值小于输入字符串的长度，则输入字符串会被截断为 `length` 个字符。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `pad_string` — 可选。用于填充输入字符串的字符串。若未指定，则使用空格填充输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个右侧填充到给定长度的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT rightPad('abc', 7, '*'), rightPad('abc', 7)
```
```response title=Response theme={null}
┌─rightPad('abc', 7, '*')─┬─rightPad('abc', 7)─┐
│ abc**** │ abc │
└─────────────────────────┴────────────────────┘
```
## rightPadUTF8
引入版本：v21.8.0
从右侧用空格或指定字符串 (如有需要可重复多次) 填充该字符串，直到结果字符串达到给定长度。
不同于按字节计算字符串长度的 [`rightPad`](#rightPad)，这里的字符串长度按码点计算。
**语法**
```sql theme={null}
rightPadUTF8(string, length[, pad_string])
```
**参数**
* `string` — 需要填充的输入字符串。[`String`](/zh/reference/data-types/string)
* `length` — 结果字符串的长度。如果该值小于输入字符串的长度，则输入字符串会被截断为 `length` 个字符。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `pad_string` — 可选。用于填充输入字符串的字符串。如果未指定，则使用空格填充输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个右侧填充至给定长度的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT rightPadUTF8('абвг', 7, '*'), rightPadUTF8('абвг', 7)
```
```response title=Response theme={null}
┌─rightPadUTF8('абвг', 7, '*')─┬─rightPadUTF8('абвг', 7)─┐
│ абвг*** │ абвг │
└──────────────────────────────┴─────────────────────────┘
```
## rightUTF8
版本引入：v22.1.0
返回 UTF-8 编码字符串 `s` 中从右侧开始、指定 `offset` 的子串。
**语法**
```sql theme={null}
rightUTF8(s, offset)
```
**参数**
* `s` — 用于计算子串的 UTF-8 编码字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `offset` — 偏移量的字节数。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回：
* 当 `offset` 为正数时，返回 `s` 的一个子串，长度为 `offset` 字节，从字符串右侧开始截取。
* 当 `offset` 为负数时，返回 `s` 的一个子串，长度为 `length(s) - |offset|` 字节，从字符串右侧开始截取。
* 如果 `length` 为 `0`，则返回空字符串。
[`String`](/zh/reference/data-types/string)
**示例**
**正偏移量**
```sql title=Query theme={null}
SELECT rightUTF8('Привет', 4)
```
```response title=Response theme={null}
ивет
```
**负 OFFSET**
```sql title=Query theme={null}
SELECT rightUTF8('Привет', -4)
```
```response title=Response theme={null}
ет
```
## soundex
引入版本：v23.4.0
返回字符串的 [Soundex 编码](https://en.wikipedia.org/wiki/Soundex)。
**语法**
```sql theme={null}
soundex(s)
```
**参数**
* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回输入字符串的 Soundex 编码。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT soundex('aksel')
```
```response title=Response theme={null}
┌─soundex('aksel')─┐
│ A240 │
└──────────────────┘
```
## space
首次引入版本：v23.5.0
按指定次数重复拼接空格 (` `) 。
**语法**
```sql theme={null}
space(n)
```
**参数**
* `n` — 空格重复的次数。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回一个由 `n` 个空格组成的字符串。如果 `n <= 0`，函数将返回空字符串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT space(3) AS res, length(res);
```
```response title=Response theme={null}
┌─res─┬─length(res)─┐
│ │ 3 │
└─────┴─────────────┘
```
## sparseGrams
引入版本：v25.5.0
在给定字符串中查找所有长度至少为 `n` 的子字符串，
其中该子字符串边界上的 `(n-1)`-gram 的哈希值
严格大于其内部任意 `(n-1)`-gram 的哈希值。
使用 `CRC32` 作为哈希函数。
**语法**
```sql theme={null}
sparseGrams(s[, min_ngram_length[, max_ngram_length[, min_cutoff_length]]])
```
**参数**
* `s` — 输入的字符串。[`String`](/zh/reference/data-types/string)
* `min_ngram_length` — 可选。提取的 ngram 的最小长度。默认值和最小值均为 3。[`UInt*`](/zh/reference/data-types/int-uint)
* `max_ngram_length` — 可选。提取的 ngram 的最大长度。默认值为 100。不得小于 `min_ngram_length`。[`UInt*`](/zh/reference/data-types/int-uint)
* `min_cutoff_length` — 可选。如果指定，则仅返回长度大于或等于 `min_cutoff_length` 的 n-grams。默认值与 `min_ngram_length` 相同。不得小于 `min_ngram_length`，也不得大于 `max_ngram_length`。[`UInt*`](/zh/reference/data-types/int-uint)
**返回值**
返回所选子字符串的数组。[`Array(String)`](/zh/reference/data-types/array)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT sparseGrams('alice', 3)
```
```response title=Response theme={null}
┌─sparseGrams('alice', 3)────────────┐
│ ['ali','lic','lice','ice'] │
└────────────────────────────────────┘
```
## sparseGramsHashes
引入版本：v25.5.0
查找给定字符串中所有长度至少为 `n` 的子字符串的哈希值，
其中该子字符串边界上的 (n-1)-gram 的哈希值
严格大于该子字符串内部任意 (n-1)-gram 的哈希值。
使用 `CRC32` 作为哈希函数。
**语法**
```sql theme={null}
sparseGramsHashes(s[, min_ngram_length, max_ngram_length])
```
**参数**
* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
* `min_ngram_length` — 可选。提取的 ngram 的最小长度。默认值和最小值均为 3。[`UInt*`](/zh/reference/data-types/int-uint)
* `max_ngram_length` — 可选。提取的 ngram 的最大长度。默认值为 100。不应小于 `min_ngram_length`。[`UInt*`](/zh/reference/data-types/int-uint)
* `min_cutoff_length` — 可选。若指定，则仅返回长度大于或等于 `min_cutoff_length` 的 n-grams。默认值与 `min_ngram_length` 相同。不应小于 `min_ngram_length`，也不应大于 `max_ngram_length`。[`UInt*`](/zh/reference/data-types/int-uint)
**返回值**
返回由选定子字符串的 CRC32 哈希值组成的数组。[`Array(UInt32)`](/zh/reference/data-types/array)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT sparseGramsHashes('alice', 3)
```
```response title=Response theme={null}
┌─sparseGramsHashes('alice', 3)──────────────────────┐
│ [1481062250,2450405249,4012725991,1918774096] │
└────────────────────────────────────────────────────┘
```
## sparseGramsHashesUTF8
Introduced in: v25.5.0
返回给定 UTF-8 字符串中所有长度至少为 `n` 的子字符串的哈希值，其中该子字符串边界上的 (n-1)-gram 的哈希值严格大于其内部任意 (n-1)-gram 的哈希值。
该函数要求输入为 UTF-8 字符串；如果 UTF-8 序列无效，则会抛出异常。
使用 `CRC32` 作为哈希函数。
**Syntax**
```sql theme={null}
sparseGramsHashesUTF8(s[, min_ngram_length, max_ngram_length])
```
**参数**
* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
* `min_ngram_length` — 可选。提取的 ngram 的最小长度。默认值和最小值均为 3。[`UInt*`](/zh/reference/data-types/int-uint)
* `max_ngram_length` — 可选。提取的 ngram 的最大长度。默认值为 100。不能小于 `min_ngram_length`。[`UInt*`](/zh/reference/data-types/int-uint)
* `min_cutoff_length` — 可选。如果指定，则仅返回长度大于等于 `min_cutoff_length` 的 n-grams。默认值与 `min_ngram_length` 相同。不能小于 `min_ngram_length`，也不能大于 `max_ngram_length`。[`UInt*`](/zh/reference/data-types/int-uint)
**返回值**
返回所选 UTF-8 子字符串的 CRC32 哈希数组。[`Array(UInt32)`](/zh/reference/data-types/array)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT sparseGramsHashesUTF8('алиса', 3)
```
```response title=Response theme={null}
┌─sparseGramsHashesUTF8('алиса', 3)─┐
│ [4178533925,3855635300,561830861] │
└───────────────────────────────────┘
```
## sparseGramsUTF8
Introduced in: v25.5.0
查找给定 UTF-8 字符串中所有长度至少为 `n` 的子字符串，其中该子字符串边界处的 `(n-1)`-gram 的哈希值严格大于其内部任意 `(n-1)`-gram 的哈希值。
该函数接受一个 UTF-8 字符串；如果 UTF-8 序列无效，则会抛出异常。
使用 `CRC32` 作为哈希函数。
**Syntax**
```sql theme={null}
sparseGramsUTF8(s[, min_ngram_length[, max_ngram_length[, min_cutoff_length]]])
```
**参数**
* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
* `min_ngram_length` — 可选。提取的 ngram 的最小长度。默认值和最小值均为 3。[`UInt*`](/zh/reference/data-types/int-uint)
* `max_ngram_length` — 可选。提取的 ngram 的最大长度。默认值为 100。不得小于 `min_ngram_length`。[`UInt*`](/zh/reference/data-types/int-uint)
* `min_cutoff_length` — 可选。如果指定，则仅返回长度大于或等于 `min_cutoff_length` 的 n-grams。默认值与 `min_ngram_length` 相同。不得小于 `min_ngram_length`，也不得大于 `max_ngram_length`。[`UInt*`](/zh/reference/data-types/int-uint)
**返回值**
返回由选定的 UTF-8 子字符串组成的数组。[`Array(String)`](/zh/reference/data-types/array)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT sparseGramsUTF8('алиса', 3)
```
```response title=Response theme={null}
┌─sparseGramsUTF8('алиса', 3)─┐
│ ['али','лис','иса'] │
└─────────────────────────────┘
```
## startsWith
首次引入于：v1.1.0
检查字符串是否以给定字符串开头。
**语法**
```sql theme={null}
startsWith(s, prefix)
```
**参数**
* `s` — 要检查的字符串。[`String`](/zh/reference/data-types/string)
* `prefix` — 要检查的前缀。[`String`](/zh/reference/data-types/string)
**返回值**
如果 `s` 以 `prefix` 开头，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT startsWith('ClickHouse', 'Click');
```
```response title=Response theme={null}
┌─startsWith('⋯', 'Click')─┐
│ 1 │
└──────────────────────────┘
```
## startsWithCaseInsensitive
引入版本：v25.10.0
检查字符串是否以给定的不区分大小写字符串开头。
**语法**
```sql theme={null}
startsWithCaseInsensitive(s, prefix)
```
**参数**
* `s` — 要检查的字符串。[`String`](/zh/reference/data-types/string)
* `prefix` — 要检查的、不区分大小写的前缀。[`String`](/zh/reference/data-types/string)
**返回值**
如果 `s` 以不区分大小写的 `prefix` 开头，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT startsWithCaseInsensitive('ClickHouse', 'CLICK');
```
```response title=Response theme={null}
┌─startsWithCaseInsensitive('⋯', 'CLICK')─┐
│ 1 │
└─────────────────────────────────────────┘
```
## startsWithCaseInsensitiveUTF8
引入版本：v25.10.0
检查字符串是否以给定的不区分大小写的前缀开头。
假定该字符串包含有效的 UTF-8 编码文本。
如果不满足这一假定，不会抛出异常，结果未定义。
**语法**
```sql theme={null}
startsWithCaseInsensitiveUTF8(s, prefix)
```
**参数**
* `s` — 要检查的 String。[`String`](/zh/reference/data-types/string)
* `prefix` — 要检查的、不区分大小写的前缀。[`String`](/zh/reference/data-types/string)
**返回值**
如果 `s` 以不区分大小写的 `prefix` 开头，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT startsWithCaseInsensitiveUTF8('приставка', 'при')
```
```response title=Response theme={null}
┌─startsWithUT⋯ка', 'при')─┐
│ 1 │
└──────────────────────────┘
```
## startsWithUTF8
引入版本：v23.8.0
检查字符串是否以给定的前缀开头。
假定字符串包含有效的 UTF-8 编码文本。
如果不满足这一假定，则不会抛出异常，结果未定义。
**语法**
```sql theme={null}
startsWithUTF8(s, prefix)
```
**参数**
* `s` — 要检查的字符串。[`String`](/zh/reference/data-types/string)
* `prefix` — 要检查的前缀。[`String`](/zh/reference/data-types/string)
**返回值**
如果 `s` 以 `prefix` 开头，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT startsWithUTF8('приставка', 'при')
```
```response title=Response theme={null}
┌─startsWithUT⋯ка', 'при')─┐
│ 1 │
└──────────────────────────┘
```
## stringBytesEntropy
引入版本：v25.6.0
计算字符串中字节分布的香农熵。
**语法**
```sql theme={null}
stringBytesEntropy(s)
```
**参数**
* `s` — 要分析的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回该字符串中字节分布的香农熵。[`Float64`](/zh/reference/data-types/float)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT stringBytesEntropy('Hello, world!')
```
```response title=Response theme={null}
┌─stringBytesEntropy('Hello, world!')─┐
│ 3.07049960 │
└─────────────────────────────────────┘
```
## stringBytesUniq
引入于：v25.6.0
统计字符串中不同字节的个数。
**语法**
```sql theme={null}
stringBytesUniq(s)
```
**参数**
* `s` — 要分析的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回字符串中不同字节的个数。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT stringBytesUniq('Hello')
```
```response title=Response theme={null}
┌─stringBytesUniq('Hello')─┐
│ 4 │
└──────────────────────────┘
```
## stringJaccardIndex
引入版本：v23.11.0
计算两个字节字符串之间的 [Jaccard 相似系数](https://en.wikipedia.org/wiki/Jaccard_index)。
**语法**
```sql theme={null}
stringJaccardIndex(s1, s2)
```
**参数**
* `s1` — 第一个输入字符串。[`String`](/zh/reference/data-types/string)
* `s2` — 第二个输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回两个字符串之间的 Jaccard 相似系数。[`Float64`](/zh/reference/data-types/float)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT stringJaccardIndex('clickhouse', 'mouse')
```
```response title=Response theme={null}
┌─stringJaccardIndex('clickhouse', 'mouse')─┐
│ 0.4 │
└───────────────────────────────────────────┘
```
## stringJaccardIndexUTF8
引入版本：v23.11.0
与 [`stringJaccardIndex`](#stringJaccardIndex) 类似，但适用于 UTF-8 编码的字符串。
**语法**
```sql theme={null}
stringJaccardIndexUTF8(s1, s2)
```
**参数**
* `s1` — 第一个输入的 UTF8 字符串。[`String`](/zh/reference/data-types/string)
* `s2` — 第二个输入的 UTF8 字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回这两个 UTF8 字符串之间的 Jaccard 相似系数。[`Float64`](/zh/reference/data-types/float)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT stringJaccardIndexUTF8('我爱你', '我也爱你')
```
```response title=Response theme={null}
┌─stringJaccardIndexUTF8('我爱你', '我也爱你')─┐
│ 0.75 │
└─────────────────────────────────────────────┘
```
## substring
引入版本：v1.1.0
返回字符串 `s` 中从指定字节索引 `offset` 开始的子串。
字节计数从 1 开始，规则如下：
* 如果 `offset` 为 `0`，则返回空字符串。
* 如果 `offset` 为负数，则子串从字符串末尾向前数 `|offset|` 个字符处开始，而不是从开头开始。
可选参数 `length` 用于指定返回子串的最大字节数。
**语法**
```sql theme={null}
substring(s, offset[, length])
```
**别名**: `byteSlice`, `mid`, `substr`
**参数**
* `s` — 要从中提取子串的字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`Enum`](/zh/reference/data-types/enum)
* `offset` — `s` 中子串的起始位置。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `length` — 可选。子串的最大长度。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回 `s` 中从索引 `offset` 开始、长度为 `length` 字节的子串。[`String`](/zh/reference/data-types/string)
**示例**
**基本用法**
```sql title=Query theme={null}
SELECT 'database' AS db, substr(db, 5), substr(db, 5, 1)
```
```response title=Response theme={null}
┌─db───────┬─substring('database', 5)─┬─substring('database', 5, 1)─┐
│ database │ base │ b │
└──────────┴──────────────────────────┴─────────────────────────────┘
```
## substringIndex
引入于：v23.7.0
返回 `s` 中位于分隔符 `delim` 第 `count` 次出现之前的子串，与 Spark 或 MySQL 中的行为一致。
**语法**
```sql theme={null}
substringIndex(s, delim, count)
```
**别名**: `SUBSTRING_INDEX`
**参数**
* `s` — 要从中提取子串的字符串。[`String`](/zh/reference/data-types/string)
* `delim` — 用于分割的字符。[`String`](/zh/reference/data-types/string)
* `count` — 提取子串前要计数的分隔符出现次数。如果 `count` 为正，则返回从左开始计数的最后一个分隔符左侧的所有内容。如果 `count` 为负，则返回从右开始计数的最后一个分隔符右侧的所有内容。[`UInt`](/zh/reference/data-types/int-uint) 或 [`Int`](/zh/reference/data-types/int-uint)
**返回值**
返回 `s` 中 `delim` 出现 `count` 次之前的子串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT substringIndex('www.clickhouse.com', '.', 2)
```
```response title=Response theme={null}
┌─substringIndex('www.clickhouse.com', '.', 2)─┐
│ www.clickhouse │
└──────────────────────────────────────────────┘
```
## substringIndexUTF8
首次引入版本：v23.7.0
返回 `s` 中位于分隔符 `delim` 出现 `count` 次之前的子串，按 Unicode 码点处理。
假定该字符串包含有效的 UTF-8 编码文本。
如果不满足这一假定，不会抛出异常，结果未定义。
**语法**
```sql theme={null}
substringIndexUTF8(s, delim, count)
```
**参数**
* `s` — 要从中提取子串的字符串。[`String`](/zh/reference/data-types/string)
* `delim` — 用于分割的字符。[`String`](/zh/reference/data-types/string)
* `count` — 提取子串前需要计数的分隔符出现次数。如果 `count` 为正，则返回最后一个分隔符左侧的所有内容 (从左开始计数) 。如果 `count` 为负，则返回最后一个分隔符右侧的所有内容 (从右开始计数) 。[`UInt`](/zh/reference/data-types/int-uint) 或 [`Int`](/zh/reference/data-types/int-uint)
**返回值**
返回 `s` 中第 `count` 次出现 `delim` 之前的子串。[`String`](/zh/reference/data-types/string)
**示例**
**UTF8 示例**
```sql title=Query theme={null}
SELECT substringIndexUTF8('www.straßen-in-europa.de', '.', 2)
```
```response title=Response theme={null}
www.straßen-in-europa
```
## substringUTF8
Introduced in: v1.1.0
返回字符串 `s` 中从指定码点索引 `offset` 开始的子串。
码点从 `1` 开始计数，规则如下：
* 如果 `offset` 为 `0`，则返回空字符串。
* 如果 `offset` 为负数，则子串从字符串末尾向前数 `offset` 个码点处开始，而不是从开头开始。
可选参数 `length` 指定返回子串可包含的最大码点数。
该函数假定字符串包含有效的 UTF-8 编码文本。
如果这一假设不成立，不会抛出异常，结果未定义。
**Syntax**
```sql theme={null}
substringUTF8(s, offset[, length])
```
**参数**
* `s` — 要从中提取子串的字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`Enum`](/zh/reference/data-types/enum)
* `offset` — `s` 中子串的起始位置。[`Int`](/zh/reference/data-types/int-uint) 或 [`UInt`](/zh/reference/data-types/int-uint)
* `length` — 子串的最大长度。可选。[`Int`](/zh/reference/data-types/int-uint) 或 [`UInt`](/zh/reference/data-types/int-uint)
**返回值**
返回从码点索引 `offset` 开始、长度为 `length` 个码点的 `s` 的子串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT 'Täglich grüßt das Murmeltier.' AS str, substringUTF8(str, 9), substringUTF8(str, 9, 5)
```
```response title=Response theme={null}
Täglich grüßt das Murmeltier. grüßt das Murmeltier. grüßt
```
## toValidUTF8
引入版本：v20.1.0
将字符串转换为有效的 UTF-8 编码：任何无效的 UTF-8 字符都会被替换为替换字符 `�` (U+FFFD) 。
如果存在多个连续的无效字符，它们会合并为一个替换字符。
**语法**
```sql theme={null}
toValidUTF8(s)
```
**参数**
* `s` — 以 String 数据类型对象表示的任意字节序列。[`String`](/zh/reference/data-types/string)
**返回值**
返回有效的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toValidUTF8('\\x61\\xF0\\x80\\x80\\x80b')
```
```response title=Response theme={null}
c
┌─toValidUTF8('a����b')─┐
│ a�b │
└───────────────────────┘
```
## trimBoth
引入版本：v20.1.0
移除字符串开头和结尾处的指定字符。
默认情况下，会移除常见的空白 (ASCII) 字符。
**语法**
```sql theme={null}
trimBoth(s[, trim_characters])
```
**别名**: `trim`
**参数**
* `s` — 要去除首尾字符的 String。[`String`](/zh/reference/data-types/string)
* `trim_characters` — 可选。要去除的字符。如果未指定，则会移除常见的空白字符。[`String`](/zh/reference/data-types/string)
**返回值**
返回去除两端指定字符后的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT trimBoth('$$ClickHouse$$', '$')
```
```response title=Response theme={null}
┌─trimBoth('$$⋯se$$', '$')─┐
│ ClickHouse │
└──────────────────────────┘
```
## trimLeft
引入版本：v20.1.0
移除字符串开头的指定字符。
默认会移除常见的空白 (ASCII) 字符。
**语法**
```sql theme={null}
trimLeft(input[, trim_characters])
```
**别名**: `ltrim`
**参数**
* `input` — 要裁剪的字符串。[`String`](/zh/reference/data-types/string)
* `trim_characters` — 可选。要裁剪的字符。如果未指定，则会移除常见的空白字符。[`String`](/zh/reference/data-types/string)
**返回值**
返回从左侧裁剪掉指定字符后的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT trimLeft('ClickHouse', 'Click');
```
```response title=Response theme={null}
┌─trimLeft('Cl⋯', 'Click')─┐
│ House │
└──────────────────────────┘
```
## trimRight
引入版本：v20.1.0
从字符串末尾移除指定字符。
默认会移除常见的空白 (ASCII) 字符。
**语法**
```sql theme={null}
trimRight(s[, trim_characters])
```
**别名**：`rtrim`
**参数**
* `s` — 要修剪的字符串。[`String`](/zh/reference/data-types/string)
* `trim_characters` — 可选，要修剪的字符。如果未指定，则会移除常见的空白字符。[`String`](/zh/reference/data-types/string)
**返回值**
返回从右侧修剪掉指定字符后的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT trimRight('ClickHouse','House');
```
```response title=Response theme={null}
┌─trimRight('C⋯', 'House')─┐
│ Click │
└──────────────────────────┘
```
## tryBase32Decode
引入版本：v25.6.0
接受一个字符串，并使用 [Base32](https://datatracker.ietf.org/doc/html/rfc4648#section-6) 编码方案将其解码。
**语法**
```sql theme={null}
tryBase32Decode(encoded)
```
**参数**
* `encoded` — 要解码的 String 类型列或常量。如果该字符串不是有效的 Base32 编码，则在出错时返回空字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个包含参数解码后值的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT tryBase32Decode('IVXGG33EMVSA====');
```
```response title=Response theme={null}
┌─tryBase32Decode('IVXGG33EMVSA====')─┐
│ Encoded │
└─────────────────────────────────────┘
```
## tryBase58Decode
自 v22.10.0 引入
与 [`base58Decode`](#base58Decode) 类似，但发生错误时会返回空字符串。
**语法**
```sql theme={null}
tryBase58Decode(encoded[, expected_size])
```
**参数**
* `encoded` — `String` 类型的列或常量。如果该字符串不是有效的 Base58 编码，出错时将返回空字符串。[`String`](/zh/reference/data-types/string)
* `expected_size` — 可选。预期的解码后大小 (以字节为单位) 。当值为 32 或 64 时，使用优化解码器；其他值则使用通用解码器。[`UInt8, UInt16, UInt32, or UInt64`](/zh/reference/data-types/int-uint)
**返回值**
返回一个字符串，其中包含参数解码后的值。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT tryBase58Decode('3dc8KtHrwM') AS res, tryBase58Decode('invalid') AS res_invalid;
```
```response title=Response theme={null}
┌─res─────┬─res_invalid─┐
│ Encoded │ │
└─────────┴─────────────┘
```
## tryBase64Decode
首次引入版本：v18.16.0
与 [`base64Decode`](#base64Decode) 类似，但发生错误时会返回空字符串。
**语法**
```sql theme={null}
tryBase64Decode(encoded)
```
**参数**
* `encoded` — 要解码的 String 类型列或常量。如果字符串不是有效的 Base64 编码，发生错误时将返回空字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个包含该参数解码后值的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT tryBase64Decode('Y2xpY2tob3VzZQ==')
```
```response title=Response theme={null}
┌─tryBase64Decode('Y2xpY2tob3VzZQ==')─┐
│ clickhouse │
└─────────────────────────────────────┘
```
## tryBase64URLDecode
首次引入版本：v18.16.0
与 [`base64URLDecode`](#base64URLDecode) 类似，但发生错误时返回空字符串。
**语法**
```sql theme={null}
tryBase64URLDecode(encoded)
```
**参数**
* `encoded` — 要解码的 String 类型列或常量。如果该字符串不是有效的 Base64 编码，出错时返回空字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个字符串，其中包含该参数解码后的值。[`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT tryBase64URLDecode('aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ')
```
```response title=Response theme={null}
┌─tryBase64URLDecode('aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ')─┐
│ https://clickhouse.com │
└──────────────────────────────────────────────────────┘
```
## tryIdnaEncode
引入版本：v24.1.0
根据 [Internationalized Domain Names in Applications](https://en.wikipedia.org/wiki/Internationalized_domain_name#Internationalizing_Domain_Names_in_Applications) (IDNA) 机制，返回域名的 Unicode (UTF-8) 表示 (ToUnicode 算法) 。
如果发生错误，则返回空字符串，而不是抛出异常。
**语法**
```sql theme={null}
tryIdnaEncode(s)
```
**参数**
* `s` — 输入字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回输入字符串按输入值的 IDNA 机制转换后的 ASCII 表示形式；如果输入无效，则返回空字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT tryIdnaEncode('straße.münchen.de')
```
```response title=Response theme={null}
┌─tryIdnaEncode('straße.münchen.de')──┐
│ xn--strae-oqa.xn--mnchen-3ya.de │
└─────────────────────────────────────┘
```
## tryPunycodeDecode
引入版本：v24.1.0
与 `punycodeDecode` 类似，但如果给定的字符串不是有效的 Punycode 编码字符串，则返回空字符串。
**语法**
```sql theme={null}
tryPunycodeDecode(s)
```
**参数**
* `s` — 经过 Punycode 编码的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回输入值的明文；如果输入无效，则返回空字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT tryPunycodeDecode('Mnchen-3ya')
```
```response title=Response theme={null}
┌─tryPunycodeDecode('Mnchen-3ya')─┐
│ München │
└─────────────────────────────────┘
```
## upper
引入版本：v1.1.0
将字符串中的 ASCII 拉丁字母转换为大写。
**语法**
```sql theme={null}
upper(s)
```
**别名**: `ucase`
**参数**
* `s` — 要转换为大写的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回将 `s` 转换为大写后的字符串。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT upper('clickhouse')
```
```response title=Response theme={null}
┌─upper('clickhouse')─┐
│ CLICKHOUSE │
└─────────────────────┘
```
## upperUTF8
推出版本：v1.1.0
将字符串转换为大写，前提是字符串包含有效的 UTF-8 编码文本。
如果不满足此前提，也不会抛出异常，结果未定义。
此函数不会检测语言，例如对于土耳其语，结果可能并不完全正确 (i/İ 与 i/I) 。
如果某个代码点的大写和小写形式的 UTF-8 字节序列长度不同 (例如 `ẞ` 和 `ß`) ，则该代码点的转换结果可能不正确。
**语法**
```sql theme={null}
upperUTF8(s)
```
**参数**
* `s` — String 类型。[`String`](/zh/reference/data-types/string)
**返回值**
String 类型的值。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT upperUTF8('München') AS Upperutf8
```
```response title=Response theme={null}
┌─Upperutf8─┐
│ MÜNCHEN │
└───────────┘
```