字符串函数 - ClickHouse Documentation

用于在字符串中进行搜索和替换的函数将在其他章节中单独介绍。

以下文档由 system.functions 系统表自动生成。

CRC32

引入版本：v20.1.0 使用 CRC-32-IEEE 802.3 多项式和初始值 0xffffffff (zlib 实现) 计算字符串的 CRC32 校验和。语法

CRC32(s)

参数

s — 要计算 CRC32 的字符串。String

返回值 返回该字符串的 CRC32 校验和。UInt32 示例 使用示例

Query

SELECT CRC32('ClickHouse')

Response

┌─CRC32('ClickHouse')─┐
│          1538217360 │
└─────────────────────┘

CRC32IEEE

引入版本：v20.1.0 使用 CRC-32-IEEE 802.3 多项式计算字符串的 CRC32 校验和。语法

CRC32IEEE(s)

参数

s — 用于计算 CRC32 的 String。String

返回值 返回该字符串的 CRC32 校验和。UInt32 示例 使用示例

Query

SELECT CRC32IEEE('ClickHouse');

Response

┌─CRC32IEEE('ClickHouse')─┐
│              3089448422 │
└─────────────────────────┘

CRC64

引入于：v20.1.0 使用 CRC-64-ECMA 多项式计算字符串的 CRC64 校验和。语法

CRC64(s)

参数

s — 要计算 CRC64 的 String。String

返回值 返回该字符串的 CRC64 校验和。UInt64 示例 使用示例

Query

SELECT CRC64('ClickHouse');

Response

┌──CRC64('ClickHouse')─┐
│ 12126588151325169346 │
└──────────────────────┘

appendTrailingCharIfAbsent

引入版本：v1.1.0 如果字符串 s 非空且末尾不是字符 c，则在其末尾追加字符 c。语法

appendTrailingCharIfAbsent(s, c)

参数

s — 输入字符串。String
c — 如果不存在则要追加的字符。String

返回值 如果字符串 s 不以字符 c 结尾，则返回在其末尾追加了字符 c 的字符串。String 示例 使用示例

Query

SELECT appendTrailingCharIfAbsent('https://example.com', '/');

Response

┌─appendTraili⋯.com', '/')─┐
│ https://example.com/     │
└──────────────────────────┘

ascii

引入版本：v22.11.0 返回字符串 s 中第一个字符的 ASCII 码点，返回类型为 Int32。语法

ascii(s)

参数

s — String 类型的输入值。String

返回值 返回第一个字符的 ASCII 码点。如果 s 为空，结果为 0。如果第一个字符不是 ASCII 字符，或者不在 UTF-16 的 Latin-1 补充范围内，则结果未定义。Int32 示例 使用示例

Query

SELECT ascii('234')

Response

┌─ascii('234')─┐
│           50 │
└──────────────┘

base32Decode

引入版本：v25.6.0 对 Base32 (RFC 4648) 字符串解码。如果该字符串不是有效的 Base32 编码字符串，则会抛出异常。语法

base32Decode(encoded)

参数

encoded — String 类型的列或常量。String

返回值 返回一个字符串，其中包含该参数解码后的值。String 示例 使用示例

Query

SELECT base32Decode('IVXGG33EMVSA====');

Response

┌─base32Decode('IVXGG33EMVSA====')─┐
│ Encoded                          │
└──────────────────────────────────┘

base32Encode

引入于：v25.6.0 使用 Base32 对字符串进行编码。语法

base32Encode(plaintext)

参数

plaintext — 要编码的明文。String

返回值 返回包含参数编码值的字符串。String 或 FixedString 示例 使用示例

Query

SELECT base32Encode('Encoded')

Response

┌─base32Encode('Encoded')─┐
│ IVXGG33EMVSA====        │
└─────────────────────────┘

base58Decode

引入于：v22.7.0 对 Base58 字符串进行解码。如果字符串不是有效的 Base58 编码字符串，则会抛出异常。可以提供可选的第二个参数 expected_size，以选择经过优化的固定大小解码器。目前支持的值为 32 和 64。对于其他值，会使用通用解码器。当选择了优化解码器，但输入无法被解码为恰好对应字节数时，该函数会抛出异常 (对于 tryBase58Decode，则返回空字符串) 。语法

base58Decode(encoded[, expected_size])

参数

encoded — 要解码的 String 类型列或常量。String
expected_size — 可选。预期的解码后大小 (以字节为单位) 。当该值为 32 或 64 时，使用优化解码器；其他值则使用通用解码器。UInt8, UInt16, UInt32, or UInt64

返回值 返回一个包含该参数解码后值的字符串。String 示例 使用示例

Query

SELECT base58Decode('JxF12TrwUP45BMd');

Response

┌─base58Decode⋯rwUP45BMd')─┐
│ Hello World              │
└──────────────────────────┘

base58Encode

首次引入版本：v22.7.0 使用 Base58 对字符串进行编码。语法

base58Encode(plaintext)

参数

plaintext — 要编码的明文。String

返回值 返回一个包含该参数编码值的字符串。String 示例 使用示例

Query

SELECT base58Encode('ClickHouse');

Response

┌─base58Encode('ClickHouse')─┐
│ 4nhk8K7GHXf6zx             │
└────────────────────────────┘

base64Decode

引入版本：v18.16.0 根据 RFC 4648，对 Base64 表示的字符串进行解码。如果出错，则会抛出异常。语法

base64Decode(encoded)

别名: FROM_BASE64 参数

encoded — 要解码的 String 类型列或常量。如果该字符串不是有效的 Base64 编码，则会抛出异常。String

返回值 返回解码后的字符串。String 示例 使用示例

Query

SELECT base64Decode('Y2xpY2tob3VzZQ==')

Response

┌─base64Decode('Y2xpY2tob3VzZQ==')─┐
│ clickhouse                       │
└──────────────────────────────────┘

base64Encode

引入版本：v18.16.0 根据 RFC 4648，使用 Base64 表示形式对字符串进行编码。语法

base64Encode(plaintext)

别名: TO_BASE64 参数

plaintext — 要解码的明文列或常量。String

返回值 返回包含该参数编码值的字符串。String 示例 使用示例

Query

SELECT base64Encode('clickhouse')

Response

┌─base64Encode('clickhouse')─┐
│ Y2xpY2tob3VzZQ==           │
└────────────────────────────┘

base64URLDecode

引入版本：v24.6.0 根据 RFC 4648，使用 URL 安全字母表对 Base64 表示的字符串进行解码。出错时会抛出异常。语法

base64URLDecode(encoded)

参数

encoded — 要进行编码的 String 类型列或常量。如果该字符串不是有效的 Base64 编码字符串，则会抛出异常。String

返回值 返回一个包含该参数解码后值的字符串。String 示例 用法示例

Query

SELECT base64URLDecode('aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ')

Response

┌─base64URLDecode('aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ')─┐
│ https://clickhouse.com                            │
└───────────────────────────────────────────────────┘

base64URLEncode

引入版本：v18.16.0 使用 URL 安全字母表按 Base64 (RFC 4648) 表示形式对字符串进行编码。语法

base64URLEncode(plaintext)

参数

plaintext — 要编码的明文列或常量。String

返回值 返回一个字符串，其中包含该参数编码后的值。String 示例 使用示例

Query

SELECT base64URLEncode('https://clickhouse.com')

Response

┌─base64URLEncode('https://clickhouse.com')─┐
│ aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ            │
└───────────────────────────────────────────┘

basename

Introduced in：v20.1.0 提取字符串中最后一个斜杠或反斜杠之后的部分。此函数通常用于从路径中提取文件名。语法

basename(expr)

参数

expr — 字符串表达式。反斜杠必须转义。String

返回值 返回输入字符串中最后一个斜杠或反斜杠之后的部分。如果输入字符串以斜杠或反斜杠结尾，则函数返回空字符串。如果输入字符串中没有斜杠或反斜杠，则返回原始字符串。String 示例 从 Unix 路径中提取文件名

Query

SELECT 'some/long/path/to/file' AS a, basename(a)

Response

┌─a──────────────────────┬─basename('some/long/path/to/file')─┐
│ some/long/path/to/file │ file                               │
└────────────────────────┴────────────────────────────────────┘

从 Windows 路径提取文件名

Query

SELECT 'some\\long\\path\\to\\file' AS a, basename(a)

Response

┌─a──────────────────────┬─basename('some\\long\\path\\to\\file')─┐
│ some\long\path\to\file │ file                                   │
└────────────────────────┴────────────────────────────────────────┘

不含路径分隔符的 String

Query

SELECT 'some-file-name' AS a, basename(a)

Response

┌─a──────────────┬─basename('some-file-name')─┐
│ some-file-name │ some-file-name             │
└────────────────┴────────────────────────────┘

byteHammingDistance

引入版本：v23.9.0 计算两个字节字符串之间的 Hamming 距离。语法

byteHammingDistance(s1, s2)

别名: mismatches 参数

s1 — 第一个输入字符串。String
s2 — 第二个输入字符串。String

返回值 返回这两个字符串之间的 Hamming 距离。UInt64 示例 使用示例

Query

SELECT byteHammingDistance('karolin', 'kathrin')

Response

┌─byteHammingDistance('karolin', 'kathrin')─┐
│                                         3 │
└───────────────────────────────────────────┘

caseFoldUTF8

Introduced in: v26.3.0 对 UTF-8 字符串应用 Unicode 大小写折叠，将其转换为适合进行不区分大小写比较的类似小写的规范化结果。应用标准的 Unicode 大小写折叠。保留不受大小写折叠影响的兼容字符 (例如罗马数字、带圈数字) ，但请注意，像 ﬃ 这样的某些连字仍会被分解，因为 Unicode 大小写折叠本身就会将其展开。 Syntax

caseFoldUTF8(str)

参数

str — UTF-8 编码的输入字符串。String

返回值 进行大小写折叠后的 UTF-8 字符串。String 示例 基本的大小写折叠

Query

SELECT caseFoldUTF8('Straße')

Response

┌─caseFoldUTF8('Straße')─┐
│ strasse                 │
└─────────────────────────┘

compareSubstrings

首次引入于：v25.2.0 按字典序比较两个字符串。语法

compareSubstrings(s1, s2, s1_offset, s2_offset, num_bytes)

参数

s1 — 要比较的第一个字符串。String
s2 — 要比较的第二个字符串。String
s1_offset — 在 s1 中开始比较的位置 (从零开始) 。UInt*
s2_offset — 在 s2 中开始比较的位置 (索引从零开始) 。UInt*
num_bytes — 两个字符串中参与比较的最大字节数。如果 s1_offset (或 s2_offset) + num_bytes 超过输入字符串末尾，num_bytes 会相应减小。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

示例 使用示例

Query

SELECT compareSubstrings('Saxony', 'Anglo-Saxon', 0, 6, 5) AS result

Response

┌─result─┐
│      0 │
└────────┘

concat

Introduced in: v1.1.0 将给定的参数拼接起来。不属于 String 或 FixedString 类型的参数，会使用其默认序列化方式转换为字符串。由于这会降低性能，因此不建议使用非 String/FixedString 参数。语法

concat([s1, s2, ...])

参数

s1, s2, ... — 任意数量、任意类型的值。Any

返回值 返回将这些参数连接后生成的 String。如果任一参数为 NULL，函数将返回 NULL。如果没有参数，则返回空字符串。Nullable(String) 示例 字符串拼接

Query

SELECT concat('Hello, ', 'World!')

Response

┌─concat('Hello, ', 'World!')─┐
│ Hello, World!               │
└─────────────────────────────┘

数字串联

Query

SELECT concat(42, 144)

Response

┌─concat(42, 144)─┐
│ 42144           │
└─────────────────┘

concatAssumeInjective

Introduced in：v1.1.0 与 concat 类似，但假定 concat(s1, s2, ...) → sn 是单射，也就是说，对于不同的参数会返回不同的结果。可用于优化 GROUP BY。 Syntax

concatAssumeInjective([s1, s2, ...])

参数

s1, s2, ... — 任意数量、任意类型的值。String 或 FixedString

返回值 返回将各参数拼接后得到的字符串。如果任一参数值为 NULL，函数返回 NULL。如果未传入任何参数，则返回空字符串。String 示例 Group By 优化

Query

SELECT concat(key1, key2), sum(value) FROM key_val GROUP BY concatAssumeInjective(key1, key2)

Response

┌─concat(key1, key2)─┬─sum(value)─┐
│ Hello, World!      │          3 │
│ Hello, World!      │          2 │
│ Hello, World       │          3 │
└────────────────────┴────────────┘

concatWithSeparator

引入于：v22.12.0 将提供的字符串拼接起来，并以指定的分隔符分隔。语法

concatWithSeparator(sep[, exp1, exp2, ...])

别名: concat_ws 参数

sep — 使用的分隔符。const String 或 const FixedString
exp1, exp2, ... — 要拼接的表达式。不属于 String 或 FixedString 类型的参数会通过其默认序列化转换为字符串。由于这会降低性能，因此不建议使用非 String/FixedString 参数。Any

返回值 返回由拼接这些参数得到的 String。如果任一参数值为 NULL，函数将返回 NULL。String 示例 使用示例

Query

SELECT concatWithSeparator('a', '1', '2', '3', '4')

Response

┌─concatWithSeparator('a', '1', '2', '3', '4')─┐
│ 1a2a3a4                                      │
└──────────────────────────────────────────────┘

concatWithSeparatorAssumeInjective

Introduced in：v22.12.0 与 concatWithSeparator 类似，但假定 concatWithSeparator(sep[,exp1, exp2, ... ]) → result 是单射。如果一个函数对不同参数返回不同结果，则称该函数为单射函数。可用于优化 GROUP BY。语法

concatWithSeparatorAssumeInjective(sep[, exp1, exp2, ... ])

参数

sep — 使用的分隔符。const String 或 const FixedString
exp1, exp2, ... — 要拼接的表达式。不属于 String 或 FixedString 类型的参数会使用其默认序列化方式转换为字符串。由于这会降低性能，因此不建议使用非 String/FixedString 参数。String 或 FixedString

返回值 返回由参数拼接而成的 String。如果任一参数值为 NULL，则函数返回 NULL。String 示例 使用示例

Query

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

┌─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() 函数兼容。语法

conv(number, from_base, to_base)

参数

number — 要转换的数字。可以是字符串或数值类型。 - from_base — 源进制 (2-36) 。必须是整数。 - to_base — 目标进制 (2-36) 。必须是整数。

返回值 该数字在目标进制中的字符串表示形式。示例 将十进制转换为二进制

Query

SELECT conv('10', 10, 2)

Response

将十六进制转换为十进制

Query

SELECT conv('FF', 16, 10)

Response

用负数转换

Query

SELECT conv('-1', 10, 16)

Response

FFFFFFFFFFFFFFFF

将二进制转换为八进制

Query

SELECT conv('1010', 2, 8)

Response

convertCharset

引入版本：v1.1.0 返回将字符串 s 从编码 from 转换为编码 to 后的结果。语法

convertCharset(s, from, to)

参数

s — 输入的字符串。String
from — 源字符编码。String
to — 目标字符编码。String

返回值 返回将字符串 s 从编码 from 转换为编码 to 后的结果。String 示例 用法示例

Query

SELECT convertCharset('Café', 'UTF-8', 'ISO-8859-1');

Response

┌─convertChars⋯SO-8859-1')─┐
│ Caf�                     │
└──────────────────────────┘

damerauLevenshteinDistance

引入版本：v24.1.0 计算两个字节字符串之间的 Damerau-Levenshtein 距离。语法

damerauLevenshteinDistance(s1, s2)

参数

s1 — 第一个输入字符串。String
s2 — 第二个输入字符串。String

返回值 返回两个字符串之间的 Damerau-Levenshtein 距离。UInt64 示例 使用示例

Query

SELECT damerauLevenshteinDistance('clickhouse', 'mouse')

Response

┌─damerauLevenshteinDistance('clickhouse', 'mouse')─┐
│                                                 6 │
└───────────────────────────────────────────────────┘

decodeHTMLComponent

引入版本：v23.9.0 将字符串中的 HTML 实体解码为对应的字符。语法

decodeHTMLComponent(s)

参数

s — 包含要解码的 HTML 实体的 String。String

返回值 返回将 HTML 实体解码后的字符串。String 示例 使用示例

Query

SELECT decodeHTMLComponent('&lt;div&gt;Hello &amp; &quot;World&quot;&lt;/div&gt;')

Response

┌─decodeHTMLComponent('&lt;div&gt;Hello &amp; &quot;World&quot;&lt;/div&gt;')─┐
│ <div>Hello & "World"</div>                                                  │
└─────────────────────────────────────────────────────────────────────────────┘

decodeXMLComponent

自 v21.2.0 引入将字符串中的 XML 实体解码为对应的字符。语法

decodeXMLComponent(s)

参数

s — 包含待解码 XML 实体的 String。String

返回值 返回对所提供字符串中的 XML 实体解码后的结果。String 示例 使用示例

Query

SELECT decodeXMLComponent('&lt;tag&gt;Hello &amp; World&lt;/tag&gt;')

Response

┌─decodeXMLCom⋯;/tag&gt;')─┐
│ <tag>Hello & World</tag> │
└──────────────────────────┘

editDistance

自 v23.9.0 引入计算两个字节字符串之间的编辑距离。语法

editDistance(s1, s2)

别名: levenshteinDistance 参数

s1 — 第一个输入字符串。String
s2 — 第二个输入字符串。String

返回值 返回这两个字符串之间的编辑距离。UInt64 示例 使用示例

Query

SELECT editDistance('clickhouse', 'mouse')

Response

┌─editDistance('clickhouse', 'mouse')─┐
│                                   6 │
└─────────────────────────────────────┘

editDistanceUTF8

引入版本：v24.6.0 计算两个 UTF8 字符串之间的编辑距离。语法

editDistanceUTF8(s1, s2)

别名: levenshteinDistanceUTF8 参数

s1 — 第一个输入字符串。String
s2 — 第二个输入字符串。String

返回值 返回两个 UTF8 字符串之间的编辑距离。UInt64 示例 用法示例

Query

SELECT editDistanceUTF8('我是谁', '我是我')

Response

┌─editDistanceUTF8('我是谁', '我是我')──┐
│                                   1 │
└─────────────────────────────────────┘

encodeXMLComponent

引入版本：v21.1.0 对字符进行转义，以便将字符串置于 XML 文本节点或属性中。语法

encodeXMLComponent(s)

参数

s — 待转义的 String。String

返回值 返回转义后的 String。String 示例 用法示例

Query

SELECT
    '<tag>Hello & "World"</tag>' AS original,
    encodeXMLComponent('<tag>Hello & "World"</tag>') AS xml_encoded;

Response

┌─original───────────────────┬─xml_encoded──────────────────────────────────────────┐
│ <tag>Hello & "World"</tag> │ &lt;tag&gt;Hello &amp; &quot;World&quot;&lt;/tag&gt; │
└────────────────────────────┴──────────────────────────────────────────────────────┘

endsWith

引入版本：v1.1.0 检查字符串是否以给定的后缀结尾。语法

endsWith(s, suffix)

参数

s — 要检查的字符串。String
suffix — 要检查的后缀。String

返回值 如果 s 以 suffix 结尾，则返回 1；否则返回 0。UInt8 示例 用法示例

Query

SELECT endsWith('ClickHouse', 'House');

Response

┌─endsWith('Cl⋯', 'House')─┐
│                        1 │
└──────────────────────────┘

endsWithCaseInsensitive

引入版本：v25.10.0 检查字符串是否以给定的、不区分大小写的后缀结尾。语法

endsWithCaseInsensitive(s, suffix)

参数

s — 要检查的字符串。String
suffix — 要检查的、不区分大小写的后缀。String

返回值 如果 s 以不区分大小写的 suffix 结尾，则返回 1，否则返回 0。UInt8 示例 用法示例

Query

SELECT endsWithCaseInsensitive('ClickHouse', 'HOUSE');

Response

┌─endsWithCaseInsensitive('Cl⋯', 'HOUSE')─┐
│                                       1 │
└─────────────────────────────────────────┘

endsWithCaseInsensitiveUTF8

首次引入于：v25.10.0 返回字符串 s 是否以不区分大小写的 suffix 结尾。假定该字符串包含有效的 UTF-8 编码文本。如果不满足这一假定，不会抛出异常，结果未定义。语法

endsWithCaseInsensitiveUTF8(s, suffix)

参数

s — 要检查的字符串。String
suffix — 要检查的、不区分大小写的后缀。String

返回值 如果 s 以不区分大小写的 suffix 结尾，则返回 1；否则返回 0。UInt8 示例 使用示例

Query

SELECT endsWithCaseInsensitiveUTF8('данных', 'ых');

Response

┌─endsWithCaseInsensitiveUTF8('данных', 'ых')─┐
│                                           1 │
└─────────────────────────────────────────────┘

endsWithUTF8

引入版本：v23.8.0 返回字符串 s 是否以 suffix 结尾。假定该字符串包含有效的 UTF-8 编码文本。如果不满足这一假定，不会抛出异常，结果未定义。语法

endsWithUTF8(s, suffix)

参数

s — 要检查的字符串。String
suffix — 要检查的后缀。String

返回值 如果 s 以 suffix 结尾，则返回 1，否则返回 0。UInt8 示例 使用示例

Query

SELECT endsWithUTF8('данных', 'ых');

Response

┌─endsWithUTF8('данных', 'ых')─┐
│                            1 │
└──────────────────────────────┘

extractTextFromHTML

Introduced in：v21.3.0 从 HTML 或 XHTML 中提取文本内容。此函数会移除 HTML 标签、注释以及 script/style 元素，仅保留文本内容。它支持：

移除所有 HTML/XML 标签
移除注释 ({/* */})
移除 script 和 style 元素及其内容
处理 CDATA 区段 (按原样复制)
正确处理并规范化空白字符

注意：HTML 实体不会被解码，如有需要，应使用单独的函数处理。 Syntax

extractTextFromHTML(html)

参数

html — 包含要从中提取文本的 HTML 内容的 String。String

返回值 返回提取出的文本内容，其中空白字符会被归一化。String 示例 使用示例

Query

SELECT extractTextFromHTML('
<html>
    <head><title>Page Title</title></head>
    <body>
        <p>Hello <b>World</b>!</p>
        <script>alert("test");</script>
        <!-- comment -->
    </body>
</html>
');

Response

┌─extractTextFromHTML('<html><head>...')─┐
│ Page Title Hello World!                │
└────────────────────────────────────────┘

firstLine

引入版本：v23.7.0 返回多行字符串中的第一行。语法

firstLine(s)

参数

s — 输入的字符串。String

返回值 返回输入字符串的第一行；如果没有行分隔符，则返回整个字符串。String 示例 用法示例

Query

SELECT firstLine('foo\\nbar\\nbaz')

Response

┌─firstLine('foo\nbar\nbaz')─┐
│ foo                        │
└────────────────────────────┘

idnaDecode

引入版本：v24.1.0 根据 Internationalized Domain Names in Applications (IDNA) 机制，返回域名的 Unicode (UTF-8) 表示形式 (ToUnicode 算法) 。如果发生错误 (例如输入无效) ，则返回输入字符串。请注意，由于大小写规范化，反复应用 idnaEncode() 和 idnaDecode() 后，返回的结果不一定是原始字符串。语法

idnaDecode(s)

参数

s — 输入字符串。String

返回值 根据输入值的 IDNA 机制，返回输入字符串的 Unicode (UTF-8) 形式。String 示例 用法示例

Query

SELECT idnaDecode('xn--strae-oqa.xn--mnchen-3ya.de')

Response

┌─idnaDecode('xn--strae-oqa.xn--mnchen-3ya.de')─┐
│ straße.münchen.de                             │
└───────────────────────────────────────────────┘

idnaEncode

引入版本：v24.1.0 根据 Internationalized Domain Names in Applications (IDNA) 机制，返回域名的 ASCII 表示形式 (ToASCII 算法) 。输入字符串必须采用 UTF 编码，且能够转换为 ASCII 字符串，否则将抛出异常。

不会执行百分号解码，也不会去除制表符、空格或控制字符。

语法

idnaEncode(s)

参数

s — 输入字符串。String

返回值 根据输入值的 IDNA 机制，返回输入字符串的 ASCII 表示形式。String 示例 用法示例

Query

SELECT idnaEncode('straße.münchen.de')

Response

┌─idnaEncode('straße.münchen.de')─────┐
│ xn--strae-oqa.xn--mnchen-3ya.de     │
└─────────────────────────────────────┘

initcap

Introduced in: v23.7.0 将每个单词的首字母转换为大写，其余字母转换为小写。单词是由非字母数字字符分隔的字母数字字符序列。

由于 initcap 只会将每个单词的首字母转换为大写，因此对于包含撇号或大写字母的单词，结果可能不符合预期。这是已知行为，目前暂无修复计划。

Syntax

initcap(s)

参数

s — 输入字符串。String

返回值 返回将 s 中每个单词的首字母转换为大写后的结果。String 示例 使用示例

Query

SELECT initcap('building for fast')

Response

┌─initcap('building for fast')─┐
│ Building For Fast            │
└──────────────────────────────┘

包含撇号或大写字母的单词的已知行为示例

Query

SELECT initcap('John''s cat won''t eat.');

Response

┌─initcap('Joh⋯n\'t eat.')─┐
│ John'S Cat Won'T Eat.    │
└──────────────────────────┘

initcapUTF8

引入版本：v23.7.0 与 initcap 类似，initcapUTF8 会将每个单词的首字母转换为大写，其余字母转换为小写。假定该字符串包含有效的 UTF-8 编码文本。如果不满足这一假设，不会抛出异常，结果未定义。

此函数不会检测语言，例如对于土耳其语，结果可能并不完全正确 (i/İ 与 i/I) 。如果某个码点的大写和小写形式对应的 UTF-8 字节序列长度不同，则该码点的结果可能不正确。

语法

initcapUTF8(s)

参数

s — 输入字符串。String

返回值 返回将 s 中每个单词的首字母转换为大写后的结果。String 示例 用法示例

Query

SELECT initcapUTF8('не тормозит')

Response

┌─initcapUTF8('не тормозит')─┐
│ Не Тормозит                │
└────────────────────────────┘

isValidASCII

引入版本：v25.9.0 如果输入的 String 或 FixedString 仅包含 ASCII 字节 (0x00–0x7F) ，则返回 1，否则返回 0。针对正向场景 (即输入是有效 ASCII) 进行了优化。语法

isValidASCII(str)

别名：isASCII 参数

无。

返回值 示例 isValidASCII

Query

SELECT isValidASCII('hello') AS is_ascii, isValidASCII('你好') AS is_not_ascii

Response

isValidUTF8

引入版本：v20.1.0 检查这组字节是否为有效的 UTF-8 编码文本。语法

isValidUTF8(s)

参数

s — 要检查是否为有效 UTF-8 编码的字符串。String

返回值 如果该字节序列构成有效的 UTF-8 编码文本，则返回 1；否则返回 0。UInt8 示例 使用示例

Query

SELECT isValidUTF8('\\xc3\\xb1') AS valid, isValidUTF8('\\xc3\\x28') AS invalid

Response

┌─valid─┬─invalid─┐
│     1 │       0 │
└───────┴─────────┘

jaroSimilarity

引入版本：v24.1.0 计算两个字节字符串之间的 Jaro 相似度。语法

jaroSimilarity(s1, s2)

参数

s1 — 第一个输入字符串。String
s2 — 第二个输入字符串。String

返回值 返回这两个字符串之间的 Jaro 相似度。Float64 示例 使用示例

Query

SELECT jaroSimilarity('clickhouse', 'click')

Response

┌─jaroSimilarity('clickhouse', 'click')─┐
│                    0.8333333333333333 │
└───────────────────────────────────────┘

jaroWinklerSimilarity

首次引入版本：v24.1.0 计算两个字节字符串之间的 Jaro-Winkler 相似性。语法

jaroWinklerSimilarity(s1, s2)

参数

s1 — 第一个输入字符串。String
s2 — 第二个输入字符串。String

返回值 返回两个字符串之间的 Jaro-Winkler 相似度。Float64 示例 使用示例

Query

SELECT jaroWinklerSimilarity('clickhouse', 'click')

Response

┌─jaroWinklerSimilarity('clickhouse', 'click')─┐
│                           0.8999999999999999 │
└──────────────────────────────────────────────┘

left

版本引入：v22.1.0 返回字符串 s 中从左侧按指定 offset 开始的子串。语法

left(s, offset)

参数

s — 要从中提取子串的字符串。String 或 FixedString
offset — 偏移量的字节数。(U)Int*

返回值 返回：

当 offset 为正数时，返回从字符串左侧开始、长度为 offset 字节的 s 的子串。
当 offset 为负数时，返回从字符串左侧开始、长度为 length(s) - |offset| 字节的 s 的子串。
如果 length 为 0，则返回空字符串。 String

示例 正偏移量

Query

SELECT left('Hello World', 5)

Response

Hello

负偏移量

Query

SELECT left('Hello World', -6)

Response

Hello

leftPad

引入版本：v21.8.0 从左侧使用空格或指定字符串 (如有需要可重复多次) 填充字符串，直到结果字符串达到指定的 length。语法

leftPad(string, length[, pad_string])

别名: lpad 参数

string — 要进行填充的输入字符串。String
length — 结果字符串的长度。如果该值小于输入字符串的长度，则输入字符串会被截断为 length 个字符。(U)Int*
pad_string — 可选。用于填充输入字符串的字符串。如果未指定，则使用空格对输入字符串进行填充。String

返回值 返回一个左侧填充到指定长度的字符串。String 示例 用法示例

Query

SELECT leftPad('abc', 7, '*'), leftPad('def', 7)

Response

┌─leftPad('abc', 7, '*')─┬─leftPad('def', 7)─┐
│ ****abc                │     def           │
└────────────────────────┴───────────────────┘

leftPadUTF8

Introduced in：v21.8.0 从左侧用空格或指定字符串填充 UTF8 字符串 (如有需要可重复多次) ，直到结果字符串达到给定长度。不同于按字节计算字符串长度的 leftPad，此处的字符串长度按码点计算。语法

leftPadUTF8(string, length[, pad_string])

参数

string — 需要填充的输入字符串。String
length — 结果字符串的长度。如果该值小于输入字符串的长度，则输入字符串会被截短为 length 个字符。(U)Int*
pad_string — 可选。用于填充输入字符串的字符串。如果未指定，则使用空格填充输入字符串。String

返回值 返回一个左侧填充到给定长度的字符串。String 示例 用法示例

Query

SELECT leftPadUTF8('абвг', 7, '*'), leftPadUTF8('дежз', 7)

Response

┌─leftPadUTF8('абвг', 7, '*')─┬─leftPadUTF8('дежз', 7)─┐
│ ***абвг                     │    дежз                │
└─────────────────────────────┴────────────────────────┘

leftUTF8

引入版本：v22.1.0 返回 UTF-8 编码字符串 s 中从左侧开始、指定 offset 的子串。语法

leftUTF8(s, offset)

参数

s — 用于计算子串的 UTF-8 编码字符串。String 或 FixedString
offset — 偏移的字节数。(U)Int*

返回值 返回：

当 offset 为正数时，返回 s 的子串，长度为 offset 个字节，从字符串左侧开始。\n”
当 offset 为负数时，返回 s 的子串，长度为 length(s) - |offset| 个字节，从字符串左侧开始。\n”
如果 length 为 0，则返回空字符串。 String

示例 正偏移量

Query

SELECT leftUTF8('Привет', 4)

Response

Прив

负数偏移量

Query

SELECT leftUTF8('Привет', -4)

Response

Пр

lengthUTF8

引入版本：v1.1.0 返回字符串的长度，以 Unicode 码点数计，而不是以字节数或字符数计。它假定字符串包含有效的 UTF-8 编码文本。如果这一假定不成立，不会抛出异常，结果未定义。语法

lengthUTF8(s)

别名: CHARACTER_LENGTH, CHAR_LENGTH 参数

s — 包含有效 UTF-8 编码文本的 String。String

返回值 字符串 s 的长度 (以 Unicode 码点数计) 。UInt64 示例 使用示例

Query

SELECT lengthUTF8('Здравствуй, мир!')

Response

┌─lengthUTF8('Здравствуй, мир!')─┐
│                             16 │
└────────────────────────────────┘

lower

引入版本：v1.1.0 将 ASCII 字符串转换为小写。语法

lower(s)

别名: lcase 参数

s — 要转换为小写的字符串。String

返回值 返回将 s 转换为小写后的字符串。String 示例 用法示例

Query

SELECT lower('CLICKHOUSE')

Response

┌─lower('CLICKHOUSE')─┐
│ clickhouse          │
└─────────────────────┘

lowerUTF8

引入版本：v1.1.0 将字符串转换为小写，前提是字符串包含有效的 UTF-8 编码文本。如果不满足此前提，则不会抛出异常，返回结果未定义。语法

lowerUTF8(input)

参数

input — 要转换为小写的输入字符串。String

返回值 返回小写字符串。String 示例 第一个

Query

SELECT lowerUTF8('München') as Lowerutf8;

Response

münchen

naturalSortKey

引入版本：v26.3.0 该函数用于自然排序。语法

naturalSortKey(s)

别名: NATURAL_SORT_KEY 参数

s — 要转换为自然排序键的字符串。String

返回值 返回由 s 转换得到的自然排序键字符串。String 示例 使用示例

Query

SELECT s FROM t ORDER BY naturalSortKey(s)

Response

┌─s───┐
│ a1  │
| a02 │
└─────┘

normalizeUTF8NFC

引入版本：v21.11.0 根据 NFC 规范化形式对 UTF-8 字符串进行规范化。语法

normalizeUTF8NFC(str)

参数

str — UTF-8 编码的输入字符串。String

返回值 返回 UTF-8 字符串的 NFC 规范化结果。String 示例 用法示例

Query

SELECT
'é' AS original, -- e + 组合尖音符 (U+0065 + U+0301)
length(original),
normalizeUTF8NFC('é') AS nfc_normalized, -- é (U+00E9)
length(nfc_normalized);

Response

┌─original─┬─length(original)─┬─nfc_normalized─┬─length(nfc_normalized)─┐
│ é        │                2 │ é              │                      2 │
└──────────┴──────────────────┴────────────────┴────────────────────────┘

normalizeUTF8NFD

引入版本：v21.11.0 按照 NFD 规范化结果对 UTF-8 字符串进行规范化。语法

normalizeUTF8NFD(str)

参数

str — UTF-8 编码的输入字符串。String

返回值 返回 UTF-8 字符串的 NFD 规范化结果。String 示例 使用示例

Query

SELECT
    'é' AS original, -- é (U+00E9)
    length(original),
    normalizeUTF8NFD('é') AS nfd_normalized, -- e + 组合重音符（U+0065 + U+0301）
    length(nfd_normalized);

Response

┌─original─┬─length(original)─┬─nfd_normalized─┬─length(nfd_normalized)─┐
│ é        │                2 │ é              │                      3 │
└──────────┴──────────────────┴────────────────┴────────────────────────┘

normalizeUTF8NFKC

首次引入于：v21.11.0 按照 NFKC 规范化结果对 UTF-8 字符串进行规范化。语法

normalizeUTF8NFKC(str)

参数

str — UTF-8 编码的输入字符串。String

返回值 返回 UTF-8 字符串的 NFKC 规范化结果。String 示例 使用示例

Query

SELECT
    '① ② ③' AS original,                            -- 带圆圈的数字字符
    normalizeUTF8NFKC('① ② ③') AS nfkc_normalized;  -- 转换为 1 2 3

Response

┌─original─┬─nfkc_normalized─┐
│ ① ② ③  │ 1 2 3           │
└──────────┴─────────────────┘

normalizeUTF8NFKCCasefold

引入版本：v26.3.0 根据 NFKC_Casefold 规范化结果对 UTF-8 字符串进行规范化，即先执行 NFKC 规范化，再进行大小写折叠。这对于不区分大小写地匹配标识符非常有用。语法

normalizeUTF8NFKCCasefold(str)

参数

str — UTF-8 编码的输入字符串。String

返回值 返回 UTF-8 字符串的 NFKC_Casefold 规范化结果。String 示例 使用示例

Query

SELECT
    'Ä ① Hello' AS original,
    normalizeUTF8NFKCCasefold('Ä ① Hello') AS nfkc_cf_normalized;

Response

┌─original───┬─nfkc_cf_normalized─┐
│ Ä ① Hello │ ä 1 hello           │
└────────────┴────────────────────┘

normalizeUTF8NFKD

引入版本：v21.11.0 按照 NFKD 规范化形式对 UTF-8 字符串进行规范化。语法

normalizeUTF8NFKD(str)

参数

str — UTF-8 编码的输入字符串。String

返回值 返回该 UTF-8 字符串的 NFKD 规范化结果。String 示例 使用示例

Query

SELECT
    'H₂O²' AS original,                            -- H + 下标 2 + O + 上标 2
    normalizeUTF8NFKD('H₂O²') AS nfkd_normalized;  -- 转换为 H 2 O 2

Response

┌─original─┬─nfkd_normalized─┐
│ H₂O²     │ H2O2            │
└──────────┴─────────────────┘

punycodeDecode

引入版本：v24.1.0 返回 Punycode 编码字符串对应的 UTF8 编码明文。如果给定的不是有效的 Punycode 编码字符串，则会抛出异常。语法

punycodeDecode(s)

参数

s — 采用 Punycode 编码的字符串。String

返回值 返回输入值的明文形式。String 示例 用法示例

Query

SELECT punycodeDecode('Mnchen-3ya')

Response

┌─punycodeDecode('Mnchen-3ya')─┐
│ München                      │
└──────────────────────────────┘

punycodeEncode

引入版本：v24.1.0 返回字符串的 Punycode 表示。字符串必须采用 UTF8 编码，否则行为未定义。语法

punycodeEncode(s)

参数

s — 输入值。String

返回值 返回输入值的 Punycode 表示。String 示例 使用示例

Query

SELECT punycodeEncode('München')

Response

┌─punycodeEncode('München')─┐
│ Mnchen-3ya                │
└───────────────────────────┘

regexpExtract

引入版本：v23.2.0 从 haystack 中提取第一个匹配正则表达式模式且对应指定正则分组索引的字符串。语法

regexpExtract(haystack, pattern[, index])

别名: REGEXP_EXTRACT, REGEXP_SUBSTR 参数

haystack — String，待进行正则表达式模式匹配的字符串。String
pattern — String，正则表达式模式。pattern 可以包含多个正则分组，index 指定要提取的正则分组。索引为 0 表示匹配整个正则表达式。const String
index — 可选。一个非负整数，表示要提取的正则分组。如果 pattern 至少包含一个捕获分组，则默认值为 1；如果 pattern 不包含捕获分组，则默认值为 0 (整个匹配) 。(U)Int*

返回值 返回匹配到的字符串。String 示例 使用示例

Query

SELECT
    regexpExtract('100-200', '(\\d+)-(\\d+)', 1),
    regexpExtract('100-200', '(\\d+)-(\\d+)', 2),
    regexpExtract('100-200', '(\\d+)-(\\d+)', 0),
    regexpExtract('100-200', '(\\d+)-(\\d+)'),
    regexpExtract('100-200', '\\d+');

Response

┌─regexpExtract('100-200', '(\\d+)-(\\d+)', 1)─┬─regexpExtract('100-200', '(\\d+)-(\\d+)', 2)─┬─regexpExtract('100-200', '(\\d+)-(\\d+)', 0)─┬─regexpExtract('100-200', '(\\d+)-(\\d+)')─┬─regexpExtract('100-200', '\\d+')─┐
│ 100                                          │ 200                                          │ 100-200                                      │ 100                                       │ 100                              │
└──────────────────────────────────────────────┴──────────────────────────────────────────────┴──────────────────────────────────────────────┴───────────────────────────────────────────┴──────────────────────────────────┘

regexpPosition

引入版本：v26.5.0 返回 pattern 在 haystack 中第 occurrence 次匹配的字节位置 (从 1 开始) ，搜索从字节位置 position 开始。如果 return_option 为 0 (默认值) ，则返回匹配结果第一个字节的位置；如果为 1，则返回匹配结束后第一个字节的位置。如果 subexpression 大于 0，则返回相应捕获组的位置，而不是整个匹配的位置。如果未找到匹配，或所请求的捕获组未参与匹配，则返回 0。此函数用于兼容 PostgreSQL 的 regexp_instr (也以该别名提供) 。请注意，这里的位置按字节计算，与其他 ClickHouse 正则函数一致；而 PostgreSQL 的 regexp_instr 按字符计算。语法

regexpPosition(haystack, pattern[, position[, occurrence[, return_option[, flags[, subexpression]]]]])

别名: regexpInstr, regexp_instr 参数

haystack — 待搜索的字符串。String
pattern — 正则表达式模式。const String
position — 可选。开始搜索的字节位置，从 1 开始计数。默认值：1。(U)Int*
occurrence — 可选。返回第几个匹配项。默认值：1。(U)Int*
return_option — 可选。0 返回匹配的起始位置，1 返回匹配结束后紧接着的位置。默认值：0。(U)Int*
flags — 可选。正则标志。支持：i (不区分大小写) 、c (区分大小写) 、m/n (多行锚点) 、s (点号匹配换行符) 。默认值：空字符串。const String
subexpression — 可选。要返回其位置的捕获组索引。0 表示整个匹配。默认值：0。(U)Int*

返回值 返回匹配的字节位置；如果未找到，则返回 0。UInt64 示例 基本用法

Query

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

┌─...─┬─...─┬─...─┬─...─┬─...─┐
│   7 │   4 │   5 │   7 │  10 │
└─────┴─────┴─────┴─────┴─────┘

removeDiacriticsUTF8

Introduced in: v26.3.0 通过先使用 NFD 分解字符、去除组合附加符号 (Unicode 类别 Mn) ，再使用 NFC 重新组合，从 UTF-8 字符串中移除变音符号 (重音) 。 Syntax

removeDiacriticsUTF8(str)

别名: removeAccentsUTF8 参数

str — UTF-8 编码的输入字符串。String

返回值 移除变音符号后的 UTF-8 字符串。String 示例 基本重音去除

Query

SELECT removeDiacriticsUTF8('café résumé naïve')

Response

┌─removeDiacriticsUTF8('café résumé naïve')─┐
│ cafe resume naive                          │
└────────────────────────────────────────────┘

repeat

引入版本：v20.1.0 按指定次数将一个字符串与自身连接。语法

repeat(s, n)

参数

s — 要重复的字符串。String
n — 字符串的重复次数。(U)Int*

返回值 将字符串 s 重复 n 次后得到的字符串。如果 n 为负数，函数将返回空字符串。String 示例 用法示例

Query

SELECT repeat('abc', 10)

Response

┌─repeat('abc', 10)──────────────┐
│ abcabcabcabcabcabcabcabcabcabc │
└────────────────────────────────┘

reverseUTF8

引入版本：v1.1.0 反转字符串中的 Unicode 码点序列。假定该字符串包含有效的 UTF-8 编码文本。如果不满足这一假定，则不会抛出异常，结果未定义。语法

reverseUTF8(s)

参数

s — 包含有效 UTF-8 编码文本的 String。String

返回值 返回一个将 Unicode 码点序列倒序后的字符串。String 示例 使用示例

Query

SELECT reverseUTF8('ClickHouse')

Response

esuoHkcilC

right

首次引入版本：v22.1.0 返回字符串 s 中从右侧开始、以指定 offset 为起点的子串。语法

right(s, offset)

参数

s — 要从中提取子串的字符串。String 或 FixedString
offset — 偏移量的字节数。(U)Int*

返回值 返回：

当 offset 为正数时，返回从字符串右侧开始、长度为 offset 字节的 s 的子串。
当 offset 为负数时，返回从字符串右侧开始、长度为 length(s) - |offset| 字节的 s 的子串。
如果 length 为 0，则返回空字符串。 String

示例 正偏移量

Query

SELECT right('Hello', 3)

Response

llo

负偏移

Query

SELECT right('Hello', -3)

Response

lo

rightPad

Introduced in: v21.8.0 在字符串右侧填充空格或指定字符串 (如有需要可重复多次) ，直到结果字符串达到指定的 length。语法

rightPad(string, length[, pad_string])

别名: rpad 参数

string — 需要填充的输入字符串。String
length — 结果字符串的长度。如果该值小于输入字符串的长度，则输入字符串会被截断为 length 个字符。(U)Int*
pad_string — 可选。用于填充输入字符串的字符串。若未指定，则使用空格填充输入字符串。String

返回值 返回一个右侧填充到给定长度的字符串。String 示例 用法示例

Query

SELECT rightPad('abc', 7, '*'), rightPad('abc', 7)

Response

┌─rightPad('abc', 7, '*')─┬─rightPad('abc', 7)─┐
│ abc****                 │ abc                │
└─────────────────────────┴────────────────────┘

rightPadUTF8

引入版本：v21.8.0 从右侧用空格或指定字符串 (如有需要可重复多次) 填充该字符串，直到结果字符串达到给定长度。不同于按字节计算字符串长度的 rightPad，这里的字符串长度按码点计算。语法

rightPadUTF8(string, length[, pad_string])

参数

string — 需要填充的输入字符串。String
length — 结果字符串的长度。如果该值小于输入字符串的长度，则输入字符串会被截断为 length 个字符。(U)Int*
pad_string — 可选。用于填充输入字符串的字符串。如果未指定，则使用空格填充输入字符串。String

返回值 返回一个右侧填充至给定长度的字符串。String 示例 使用示例

Query

SELECT rightPadUTF8('абвг', 7, '*'), rightPadUTF8('абвг', 7)

Response

┌─rightPadUTF8('абвг', 7, '*')─┬─rightPadUTF8('абвг', 7)─┐
│ абвг***                      │ абвг                    │
└──────────────────────────────┴─────────────────────────┘

rightUTF8

版本引入：v22.1.0 返回 UTF-8 编码字符串 s 中从右侧开始、指定 offset 的子串。语法

rightUTF8(s, offset)

参数

s — 用于计算子串的 UTF-8 编码字符串。String 或 FixedString
offset — 偏移量的字节数。(U)Int*

返回值 返回：

当 offset 为正数时，返回 s 的一个子串，长度为 offset 字节，从字符串右侧开始截取。
当 offset 为负数时，返回 s 的一个子串，长度为 length(s) - |offset| 字节，从字符串右侧开始截取。
如果 length 为 0，则返回空字符串。 String

示例 正偏移量

Query

SELECT rightUTF8('Привет', 4)

Response

ивет

负 OFFSET

Query

SELECT rightUTF8('Привет', -4)

Response

ет

soundex

引入版本：v23.4.0 返回字符串的 Soundex 编码。语法

soundex(s)

参数

s — 输入字符串。String

返回值 返回输入字符串的 Soundex 编码。String 示例 用法示例

Query

SELECT soundex('aksel')

Response

┌─soundex('aksel')─┐
│ A240             │
└──────────────────┘

space

首次引入版本：v23.5.0 按指定次数重复拼接空格 ( ) 。语法

space(n)

参数

n — 空格重复的次数。(U)Int*

返回值 返回一个由 n 个空格组成的字符串。如果 n <= 0，函数将返回空字符串。String 示例 用法示例

Query

SELECT space(3) AS res, length(res);

Response

┌─res─┬─length(res)─┐
│     │           3 │
└─────┴─────────────┘

sparseGrams

引入版本：v25.5.0 在给定字符串中查找所有长度至少为 n 的子字符串，其中该子字符串边界上的 (n-1)-gram 的哈希值严格大于其内部任意 (n-1)-gram 的哈希值。使用 CRC32 作为哈希函数。语法

sparseGrams(s[, min_ngram_length[, max_ngram_length[, min_cutoff_length]]])

参数

s — 输入的字符串。String
min_ngram_length — 可选。提取的 ngram 的最小长度。默认值和最小值均为 3。UInt*
max_ngram_length — 可选。提取的 ngram 的最大长度。默认值为 100。不得小于 min_ngram_length。UInt*
min_cutoff_length — 可选。如果指定，则仅返回长度大于或等于 min_cutoff_length 的 n-grams。默认值与 min_ngram_length 相同。不得小于 min_ngram_length，也不得大于 max_ngram_length。UInt*

返回值 返回所选子字符串的数组。Array(String) 示例 使用示例

Query

SELECT sparseGrams('alice', 3)

Response

┌─sparseGrams('alice', 3)────────────┐
│ ['ali','lic','lice','ice']         │
└────────────────────────────────────┘

sparseGramsHashes

引入版本：v25.5.0 查找给定字符串中所有长度至少为 n 的子字符串的哈希值，其中该子字符串边界上的 (n-1)-gram 的哈希值严格大于该子字符串内部任意 (n-1)-gram 的哈希值。使用 CRC32 作为哈希函数。语法

sparseGramsHashes(s[, min_ngram_length, max_ngram_length])

参数

s — 输入字符串。String
min_ngram_length — 可选。提取的 ngram 的最小长度。默认值和最小值均为 3。UInt*
max_ngram_length — 可选。提取的 ngram 的最大长度。默认值为 100。不应小于 min_ngram_length。UInt*
min_cutoff_length — 可选。若指定，则仅返回长度大于或等于 min_cutoff_length 的 n-grams。默认值与 min_ngram_length 相同。不应小于 min_ngram_length，也不应大于 max_ngram_length。UInt*

返回值 返回由选定子字符串的 CRC32 哈希值组成的数组。Array(UInt32) 示例 使用示例

Query

SELECT sparseGramsHashes('alice', 3)

Response

┌─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

sparseGramsHashesUTF8(s[, min_ngram_length, max_ngram_length])

参数

s — 输入字符串。String
min_ngram_length — 可选。提取的 ngram 的最小长度。默认值和最小值均为 3。UInt*
max_ngram_length — 可选。提取的 ngram 的最大长度。默认值为 100。不能小于 min_ngram_length。UInt*
min_cutoff_length — 可选。如果指定，则仅返回长度大于等于 min_cutoff_length 的 n-grams。默认值与 min_ngram_length 相同。不能小于 min_ngram_length，也不能大于 max_ngram_length。UInt*

返回值 返回所选 UTF-8 子字符串的 CRC32 哈希数组。Array(UInt32) 示例 使用示例

Query

SELECT sparseGramsHashesUTF8('алиса', 3)

Response

┌─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

sparseGramsUTF8(s[, min_ngram_length[, max_ngram_length[, min_cutoff_length]]])

参数

s — 输入字符串。String
min_ngram_length — 可选。提取的 ngram 的最小长度。默认值和最小值均为 3。UInt*
max_ngram_length — 可选。提取的 ngram 的最大长度。默认值为 100。不得小于 min_ngram_length。UInt*
min_cutoff_length — 可选。如果指定，则仅返回长度大于或等于 min_cutoff_length 的 n-grams。默认值与 min_ngram_length 相同。不得小于 min_ngram_length，也不得大于 max_ngram_length。UInt*

返回值 返回由选定的 UTF-8 子字符串组成的数组。Array(String) 示例 使用示例

Query

SELECT sparseGramsUTF8('алиса', 3)

Response

┌─sparseGramsUTF8('алиса', 3)─┐
│ ['али','лис','иса']         │
└─────────────────────────────┘

startsWith

首次引入于：v1.1.0 检查字符串是否以给定字符串开头。语法

startsWith(s, prefix)

参数

s — 要检查的字符串。String
prefix — 要检查的前缀。String

返回值 如果 s 以 prefix 开头，则返回 1；否则返回 0。UInt8 示例 使用示例

Query

SELECT startsWith('ClickHouse', 'Click');

Response

┌─startsWith('⋯', 'Click')─┐
│                        1 │
└──────────────────────────┘

startsWithCaseInsensitive

引入版本：v25.10.0 检查字符串是否以给定的不区分大小写字符串开头。语法

startsWithCaseInsensitive(s, prefix)

参数

s — 要检查的字符串。String
prefix — 要检查的、不区分大小写的前缀。String

返回值 如果 s 以不区分大小写的 prefix 开头，则返回 1，否则返回 0。UInt8 示例 使用示例

Query

SELECT startsWithCaseInsensitive('ClickHouse', 'CLICK');

Response

┌─startsWithCaseInsensitive('⋯', 'CLICK')─┐
│                                       1 │
└─────────────────────────────────────────┘

startsWithCaseInsensitiveUTF8

引入版本：v25.10.0 检查字符串是否以给定的不区分大小写的前缀开头。假定该字符串包含有效的 UTF-8 编码文本。如果不满足这一假定，不会抛出异常，结果未定义。语法

startsWithCaseInsensitiveUTF8(s, prefix)

参数

s — 要检查的 String。String
prefix — 要检查的、不区分大小写的前缀。String

返回值 如果 s 以不区分大小写的 prefix 开头，则返回 1，否则返回 0。UInt8 示例 使用示例

Query

SELECT startsWithCaseInsensitiveUTF8('приставка', 'при')

Response

┌─startsWithUT⋯ка', 'при')─┐
│                        1 │
└──────────────────────────┘

startsWithUTF8

引入版本：v23.8.0 检查字符串是否以给定的前缀开头。假定字符串包含有效的 UTF-8 编码文本。如果不满足这一假定，则不会抛出异常，结果未定义。语法

startsWithUTF8(s, prefix)

参数

s — 要检查的字符串。String
prefix — 要检查的前缀。String

返回值 如果 s 以 prefix 开头，则返回 1；否则返回 0。UInt8 示例 使用示例

Query

SELECT startsWithUTF8('приставка', 'при')

Response

┌─startsWithUT⋯ка', 'при')─┐
│                        1 │
└──────────────────────────┘

stringBytesEntropy

引入版本：v25.6.0 计算字符串中字节分布的香农熵。语法

stringBytesEntropy(s)

参数

s — 要分析的字符串。String

返回值 返回该字符串中字节分布的香农熵。Float64 示例 用法示例

Query

SELECT stringBytesEntropy('Hello, world!')

Response

┌─stringBytesEntropy('Hello, world!')─┐
│                         3.07049960  │
└─────────────────────────────────────┘

stringBytesUniq

引入于：v25.6.0 统计字符串中不同字节的个数。语法

stringBytesUniq(s)

参数

s — 要分析的字符串。String

返回值 返回字符串中不同字节的个数。UInt16 示例 用法示例

Query

SELECT stringBytesUniq('Hello')

Response

┌─stringBytesUniq('Hello')─┐
│                        4 │
└──────────────────────────┘

stringJaccardIndex

引入版本：v23.11.0 计算两个字节字符串之间的 Jaccard 相似系数。语法

stringJaccardIndex(s1, s2)

参数

s1 — 第一个输入字符串。String
s2 — 第二个输入字符串。String

返回值 返回两个字符串之间的 Jaccard 相似系数。Float64 示例 使用示例

Query

SELECT stringJaccardIndex('clickhouse', 'mouse')

Response

┌─stringJaccardIndex('clickhouse', 'mouse')─┐
│                                       0.4 │
└───────────────────────────────────────────┘

stringJaccardIndexUTF8

引入版本：v23.11.0 与 stringJaccardIndex 类似，但适用于 UTF-8 编码的字符串。语法

stringJaccardIndexUTF8(s1, s2)

参数

s1 — 第一个输入的 UTF8 字符串。String
s2 — 第二个输入的 UTF8 字符串。String

返回值 返回这两个 UTF8 字符串之间的 Jaccard 相似系数。Float64 示例 使用示例

Query

SELECT stringJaccardIndexUTF8('我爱你', '我也爱你')

Response

┌─stringJaccardIndexUTF8('我爱你', '我也爱你')─┐
│                                       0.75 │
└─────────────────────────────────────────────┘

substring

引入版本：v1.1.0 返回字符串 s 中从指定字节索引 offset 开始的子串。字节计数从 1 开始，规则如下：

如果 offset 为 0，则返回空字符串。
如果 offset 为负数，则子串从字符串末尾向前数 |offset| 个字符处开始，而不是从开头开始。

可选参数 length 用于指定返回子串的最大字节数。语法

substring(s, offset[, length])

别名: byteSlice, mid, substr 参数

s — 要从中提取子串的字符串。String 或 FixedString 或 Enum
offset — s 中子串的起始位置。(U)Int*
length — 可选。子串的最大长度。(U)Int*

返回值 返回 s 中从索引 offset 开始、长度为 length 字节的子串。String 示例 基本用法

Query

SELECT 'database' AS db, substr(db, 5), substr(db, 5, 1)

Response

┌─db───────┬─substring('database', 5)─┬─substring('database', 5, 1)─┐
│ database │ base                     │ b                           │
└──────────┴──────────────────────────┴─────────────────────────────┘

substringIndex

引入于：v23.7.0 返回 s 中位于分隔符 delim 第 count 次出现之前的子串，与 Spark 或 MySQL 中的行为一致。语法

substringIndex(s, delim, count)

别名: SUBSTRING_INDEX 参数

s — 要从中提取子串的字符串。String
delim — 用于分割的字符。String
count — 提取子串前要计数的分隔符出现次数。如果 count 为正，则返回从左开始计数的最后一个分隔符左侧的所有内容。如果 count 为负，则返回从右开始计数的最后一个分隔符右侧的所有内容。UInt 或 Int

返回值 返回 s 中 delim 出现 count 次之前的子串。String 示例 用法示例

Query

SELECT substringIndex('www.clickhouse.com', '.', 2)

Response

┌─substringIndex('www.clickhouse.com', '.', 2)─┐
│ www.clickhouse                               │
└──────────────────────────────────────────────┘

substringIndexUTF8

首次引入版本：v23.7.0 返回 s 中位于分隔符 delim 出现 count 次之前的子串，按 Unicode 码点处理。假定该字符串包含有效的 UTF-8 编码文本。如果不满足这一假定，不会抛出异常，结果未定义。语法

substringIndexUTF8(s, delim, count)

参数

s — 要从中提取子串的字符串。String
delim — 用于分割的字符。String
count — 提取子串前需要计数的分隔符出现次数。如果 count 为正，则返回最后一个分隔符左侧的所有内容 (从左开始计数) 。如果 count 为负，则返回最后一个分隔符右侧的所有内容 (从右开始计数) 。UInt 或 Int

返回值 返回 s 中第 count 次出现 delim 之前的子串。String 示例 UTF8 示例

Query

SELECT substringIndexUTF8('www.straßen-in-europa.de', '.', 2)

Response

www.straßen-in-europa

substringUTF8

Introduced in: v1.1.0 返回字符串 s 中从指定码点索引 offset 开始的子串。码点从 1 开始计数，规则如下：

如果 offset 为 0，则返回空字符串。
如果 offset 为负数，则子串从字符串末尾向前数 offset 个码点处开始，而不是从开头开始。

可选参数 length 指定返回子串可包含的最大码点数。

该函数假定字符串包含有效的 UTF-8 编码文本。如果这一假设不成立，不会抛出异常，结果未定义。

Syntax

substringUTF8(s, offset[, length])

参数

s — 要从中提取子串的字符串。String 或 FixedString 或 Enum
offset — s 中子串的起始位置。Int 或 UInt
length — 子串的最大长度。可选。Int 或 UInt

返回值 返回从码点索引 offset 开始、长度为 length 个码点的 s 的子串。String 示例 用法示例

Query

SELECT 'Täglich grüßt das Murmeltier.' AS str, substringUTF8(str, 9), substringUTF8(str, 9, 5)

Response

Täglich grüßt das Murmeltier.    grüßt das Murmeltier.    grüßt

toValidUTF8

引入版本：v20.1.0 将字符串转换为有效的 UTF-8 编码：任何无效的 UTF-8 字符都会被替换为替换字符 � (U+FFFD) 。如果存在多个连续的无效字符，它们会合并为一个替换字符。语法

toValidUTF8(s)

参数

s — 以 String 数据类型对象表示的任意字节序列。String

返回值 返回有效的 UTF-8 字符串。String 示例 使用示例

Query

SELECT toValidUTF8('\\x61\\xF0\\x80\\x80\\x80b')

Response

c
┌─toValidUTF8('a����b')─┐
│ a�b                   │
└───────────────────────┘

trimBoth

引入版本：v20.1.0 移除字符串开头和结尾处的指定字符。默认情况下，会移除常见的空白 (ASCII) 字符。语法

trimBoth(s[, trim_characters])

别名: trim 参数

s — 要去除首尾字符的 String。String
trim_characters — 可选。要去除的字符。如果未指定，则会移除常见的空白字符。String

返回值 返回去除两端指定字符后的字符串。String 示例 使用示例

Query

SELECT trimBoth('$$ClickHouse$$', '$')

Response

┌─trimBoth('$$⋯se$$', '$')─┐
│ ClickHouse               │
└──────────────────────────┘

trimLeft

引入版本：v20.1.0 移除字符串开头的指定字符。默认会移除常见的空白 (ASCII) 字符。语法

trimLeft(input[, trim_characters])

别名: ltrim 参数

input — 要裁剪的字符串。String
trim_characters — 可选。要裁剪的字符。如果未指定，则会移除常见的空白字符。String

返回值 返回从左侧裁剪掉指定字符后的字符串。String 示例 使用示例

Query

SELECT trimLeft('ClickHouse', 'Click');

Response

┌─trimLeft('Cl⋯', 'Click')─┐
│ House                    │
└──────────────────────────┘

trimRight

引入版本：v20.1.0 从字符串末尾移除指定字符。默认会移除常见的空白 (ASCII) 字符。语法

trimRight(s[, trim_characters])

别名：rtrim 参数

s — 要修剪的字符串。String
trim_characters — 可选，要修剪的字符。如果未指定，则会移除常见的空白字符。String

返回值 返回从右侧修剪掉指定字符后的字符串。String 示例 用法示例

Query

SELECT trimRight('ClickHouse','House');

Response

┌─trimRight('C⋯', 'House')─┐
│ Click                    │
└──────────────────────────┘

tryBase32Decode

引入版本：v25.6.0 接受一个字符串，并使用 Base32 编码方案将其解码。语法

tryBase32Decode(encoded)

参数

encoded — 要解码的 String 类型列或常量。如果该字符串不是有效的 Base32 编码，则在出错时返回空字符串。String

返回值 返回一个包含参数解码后值的字符串。String 示例 使用示例

Query

SELECT tryBase32Decode('IVXGG33EMVSA====');

Response

┌─tryBase32Decode('IVXGG33EMVSA====')─┐
│ Encoded                             │
└─────────────────────────────────────┘

tryBase58Decode

自 v22.10.0 引入与 base58Decode 类似，但发生错误时会返回空字符串。语法

tryBase58Decode(encoded[, expected_size])

参数

encoded — String 类型的列或常量。如果该字符串不是有效的 Base58 编码，出错时将返回空字符串。String
expected_size — 可选。预期的解码后大小 (以字节为单位) 。当值为 32 或 64 时，使用优化解码器；其他值则使用通用解码器。UInt8, UInt16, UInt32, or UInt64

返回值 返回一个字符串，其中包含参数解码后的值。String 示例 使用示例

Query

SELECT tryBase58Decode('3dc8KtHrwM') AS res, tryBase58Decode('invalid') AS res_invalid;

Response

┌─res─────┬─res_invalid─┐
│ Encoded │             │
└─────────┴─────────────┘

tryBase64Decode

首次引入版本：v18.16.0 与 base64Decode 类似，但发生错误时会返回空字符串。语法

tryBase64Decode(encoded)

参数

encoded — 要解码的 String 类型列或常量。如果字符串不是有效的 Base64 编码，发生错误时将返回空字符串。String

返回值 返回一个包含该参数解码后值的字符串。String 示例 使用示例

Query

SELECT tryBase64Decode('Y2xpY2tob3VzZQ==')

Response

┌─tryBase64Decode('Y2xpY2tob3VzZQ==')─┐
│ clickhouse                          │
└─────────────────────────────────────┘

tryBase64URLDecode

首次引入版本：v18.16.0 与 base64URLDecode 类似，但发生错误时返回空字符串。语法

tryBase64URLDecode(encoded)

参数

encoded — 要解码的 String 类型列或常量。如果该字符串不是有效的 Base64 编码，出错时返回空字符串。String

返回值 返回一个字符串，其中包含该参数解码后的值。String 示例 用法示例

Query

SELECT tryBase64URLDecode('aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ')

Response

┌─tryBase64URLDecode('aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ')─┐
│ https://clickhouse.com                               │
└──────────────────────────────────────────────────────┘

tryIdnaEncode

引入版本：v24.1.0 根据 Internationalized Domain Names in Applications (IDNA) 机制，返回域名的 Unicode (UTF-8) 表示 (ToUnicode 算法) 。如果发生错误，则返回空字符串，而不是抛出异常。语法

tryIdnaEncode(s)

参数

s — 输入字符串。String

返回值 返回输入字符串按输入值的 IDNA 机制转换后的 ASCII 表示形式；如果输入无效，则返回空字符串。String 示例 使用示例

Query

SELECT tryIdnaEncode('straße.münchen.de')

Response

┌─tryIdnaEncode('straße.münchen.de')──┐
│ xn--strae-oqa.xn--mnchen-3ya.de     │
└─────────────────────────────────────┘

tryPunycodeDecode

引入版本：v24.1.0 与 punycodeDecode 类似，但如果给定的字符串不是有效的 Punycode 编码字符串，则返回空字符串。语法

tryPunycodeDecode(s)

参数

s — 经过 Punycode 编码的字符串。String

返回值 返回输入值的明文；如果输入无效，则返回空字符串。String 示例 使用示例

Query

SELECT tryPunycodeDecode('Mnchen-3ya')

Response

┌─tryPunycodeDecode('Mnchen-3ya')─┐
│ München                         │
└─────────────────────────────────┘

upper

引入版本：v1.1.0 将字符串中的 ASCII 拉丁字母转换为大写。语法

upper(s)

别名: ucase 参数

s — 要转换为大写的字符串。String

返回值 返回将 s 转换为大写后的字符串。String 示例 使用示例

Query

SELECT upper('clickhouse')

Response

┌─upper('clickhouse')─┐
│ CLICKHOUSE          │
└─────────────────────┘

upperUTF8

推出版本：v1.1.0 将字符串转换为大写，前提是字符串包含有效的 UTF-8 编码文本。如果不满足此前提，也不会抛出异常，结果未定义。

此函数不会检测语言，例如对于土耳其语，结果可能并不完全正确 (i/İ 与 i/I) 。如果某个代码点的大写和小写形式的 UTF-8 字节序列长度不同 (例如 ẞ 和 ß) ，则该代码点的转换结果可能不正确。

语法

upperUTF8(s)

参数

s — String 类型。String

返回值 String 类型的值。String 示例 使用示例

Query

SELECT upperUTF8('München') AS Upperutf8

Response

┌─Upperutf8─┐
│ MÜNCHEN   │
└───────────┘

​CRC32

​CRC32IEEE

​CRC64

​appendTrailingCharIfAbsent

​ascii

​base32Decode

​base32Encode

​base58Decode

​base58Encode

​base64Decode

​base64Encode

​base64URLDecode

​base64URLEncode

​basename

​byteHammingDistance

​caseFoldUTF8

​compareSubstrings

​concat

​concatAssumeInjective

​concatWithSeparator

​concatWithSeparatorAssumeInjective

​conv

​convertCharset

​damerauLevenshteinDistance

​decodeHTMLComponent

​decodeXMLComponent

​editDistance

​editDistanceUTF8

​encodeXMLComponent

​endsWith

​endsWithCaseInsensitive

​endsWithCaseInsensitiveUTF8

​endsWithUTF8

​extractTextFromHTML

​firstLine

​idnaDecode

​idnaEncode

​initcap

​initcapUTF8

​isValidASCII

​isValidUTF8

​jaroSimilarity

​jaroWinklerSimilarity

​left

​leftPad

​leftPadUTF8

​leftUTF8

​lengthUTF8

​lower

​lowerUTF8

​naturalSortKey

​normalizeUTF8NFC

​normalizeUTF8NFD

​normalizeUTF8NFKC

​normalizeUTF8NFKCCasefold

​normalizeUTF8NFKD

​punycodeDecode

​punycodeEncode

​regexpExtract

​regexpPosition

​removeDiacriticsUTF8

​repeat

​reverseUTF8

​right

​rightPad

​rightPadUTF8

​rightUTF8

​soundex

​space

​sparseGrams

​sparseGramsHashes

​sparseGramsHashesUTF8

​sparseGramsUTF8

​startsWith

​startsWithCaseInsensitive

​startsWithCaseInsensitiveUTF8

​startsWithUTF8

​stringBytesEntropy

​stringBytesUniq

​stringJaccardIndex

CRC32

CRC32IEEE

CRC64

appendTrailingCharIfAbsent

ascii

base32Decode

base32Encode

base58Decode

base58Encode

base64Decode

base64Encode

base64URLDecode

base64URLEncode

basename

byteHammingDistance

caseFoldUTF8

compareSubstrings

concat

concatAssumeInjective

concatWithSeparator

concatWithSeparatorAssumeInjective

conv

convertCharset

damerauLevenshteinDistance

decodeHTMLComponent

decodeXMLComponent

editDistance

editDistanceUTF8

encodeXMLComponent

endsWith

endsWithCaseInsensitive

endsWithCaseInsensitiveUTF8

endsWithUTF8

extractTextFromHTML

firstLine

idnaDecode

idnaEncode

initcap

initcapUTF8

isValidASCII

isValidUTF8

jaroSimilarity

jaroWinklerSimilarity

left

leftPad

leftPadUTF8

leftUTF8

lengthUTF8

lower

lowerUTF8

naturalSortKey

normalizeUTF8NFC

normalizeUTF8NFD

normalizeUTF8NFKC

normalizeUTF8NFKCCasefold

normalizeUTF8NFKD

punycodeDecode

punycodeEncode

regexpExtract

regexpPosition

removeDiacriticsUTF8

repeat

reverseUTF8

right

rightPad

rightPadUTF8

rightUTF8

soundex

space

sparseGrams

sparseGramsHashes

sparseGramsHashesUTF8

sparseGramsUTF8

startsWith

startsWithCaseInsensitive

startsWithCaseInsensitiveUTF8

startsWithUTF8

stringBytesEntropy

stringBytesUniq

stringJaccardIndex