用于处理字符串的函数

用于在字符串中搜索和替换的函数在单独的章节中进行说明。

注意

以下文档是从 system.functions 系统表生成的。

CRC32

在 v20.1 中引入

使用 CRC-32-IEEE 802.3 多项式和初始值 0xffffffff（zlib 实现）计算字符串的 CRC32 校验和。

语法

CRC32(s)

参数

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

返回值

返回该字符串的 CRC32 校验和。UInt32

示例

使用示例

SELECT CRC32('ClickHouse')

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

CRC32IEEE

自 v20.1 引入

使用 CRC-32-IEEE 802.3 多项式计算字符串的 CRC32 校验和。

语法

CRC32IEEE(s)

参数

s — 用于计算 CRC32 的字符串。String

返回值

返回该字符串的 CRC32 校验和。UInt32

示例

使用示例

SELECT CRC32IEEE('ClickHouse');

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

CRC64

自 v20.1 起引入

使用 CRC-64-ECMA 多项式计算字符串的 CRC64 校验和。

语法

CRC64(s)

参数

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

返回值

返回该字符串的 CRC64 校验和。UInt64

示例

使用示例

SELECT CRC64('ClickHouse');

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

appendTrailingCharIfAbsent

引入版本：v1.1

如果字符串 s 非空且末尾不是字符 c，则将字符 c 追加到字符串 s 的末尾。

语法

appendTrailingCharIfAbsent(s, c)

参数

s — 输入字符串。String
c — 当 s 不以该字符结尾时要追加的字符。String

返回值

返回字符串 s：如果 s 不以字符 c 结尾，则在末尾追加字符 c。String

示例

用法示例

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

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

ascii

自 v22.11 引入

返回字符串 s 的第一个字符的 ASCII 码点，类型为 Int32。

语法

ascii(s)

参数

s — 字符串输入。String

返回值

返回第一个字符的 ASCII 码点。如果 s 为空，结果为 0。如果第一个字符不是 ASCII 字符，或者不属于 UTF-16 的 Latin-1 补充区，则结果未定义。Int32

示例

使用示例

SELECT ascii('234')

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

base32Decode

引入于：v25.6

对 Base32（RFC 4648）字符串进行解码。如果字符串不是有效的 Base32 编码格式，将抛出异常。

语法

base32Decode(encoded)

参数

encoded — 字符串类型的列或常量。String

返回值

返回一个字符串，包含参数解码后的值。String

示例

使用示例

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

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

base32Encode

自 v25.6 版本引入。

使用 Base32 对字符串进行编码。

语法

base32Encode(plaintext)

参数

plaintext — 要编码的明文。String

返回值

返回一个字符串，包含参数的编码结果。String 或 FixedString

示例

用法示例

SELECT base32Encode('Encoded')

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

base58Decode

自 v22.7 引入

对 Base58 字符串进行解码。如果字符串不是有效的 Base58 编码字符串，则会抛出异常。

语法

base58Decode(encoded)

参数

encoded — 要解码的字符串类型列或常量值。String

返回值

返回一个包含参数解码结果的字符串。String

示例

用法示例

SELECT base58Decode('JxF12TrwUP45BMd');

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

base58Encode

自 v22.7 引入

使用 Base58 对字符串进行编码。

语法

base58Encode(plaintext)

参数

plaintext — 要编码的明文。String

返回值

返回一个包含该参数编码后值的字符串。String

示例

使用示例

SELECT base58Encode('ClickHouse');

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

base64Decode

自 v18.16 引入

根据 RFC 4648，将 Base64 表示形式的字符串解码。在发生错误时抛出异常。

语法

base64Decode(encoded)

别名: FROM_BASE64

参数

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

返回值

返回解码后的字符串。String

示例

用法示例

SELECT base64Decode('Y2xpY2tob3VzZQ==')

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

base64Encode

引入版本：v18.16

按照 RFC 4648，对字符串进行 Base64 编码。

语法

base64Encode(plaintext)

别名: TO_BASE64

参数

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

返回值

返回一个包含参数编码值的字符串。String

示例

使用示例

SELECT base64Encode('clickhouse')

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

base64URLDecode

引入版本：v24.6

根据 RFC 4648，使用 URL 安全字母表，对 Base64 表示形式的字符串进行解码。如果发生错误，则抛出异常。

语法

base64URLDecode(encoded)

参数

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

返回值

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

示例

用法示例

SELECT base64URLDecode('aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ')

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

base64URLEncode

自 v18.16 引入

采用 URL 安全字母表，对字符串进行 Base64（RFC 4648）编码。

语法

base64URLEncode(plaintext)

参数

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

返回值

返回一个包含参数编码后值的字符串。String

示例

用法示例

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

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

basename

引入于：v20.1

提取字符串中最后一个正斜杠或反斜杠之后的末尾部分。该函数通常用于从路径中提取文件名。

语法

basename(expr)

参数

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

返回值

返回输入字符串中最后一个斜杠或反斜杠之后的部分。如果输入字符串以斜杠或反斜杠结尾，则函数返回空字符串。如果没有斜杠或反斜杠，则返回原始字符串。String

示例

从 Unix 路径中提取文件名

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

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

从 Windows 文件路径中提取文件名

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

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

不包含路径分隔符的字符串

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

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

byteHammingDistance

引入于：v23.9 版本

计算两个字节字符串之间的汉明距离。

语法

byteHammingDistance(s1, s2)

别名: mismatches

参数

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

返回值

返回两个字符串的汉明距离。UInt64

示例

使用示例

SELECT byteHammingDistance('karolin', 'kathrin')

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

compareSubstrings

在 v25.2 中引入

按字典序比较两个字符串。

语法

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

参数

s1 — 要比较的第一个字符串。String
s2 — 要比较的第二个字符串。String
s1_offset — 在 s1 中开始比较的位置（从 0 开始）。UInt*
s2_offset — 在 s2 中开始比较的位置（从 0 开始的索引）。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

示例

用法示例

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

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

concat

引入版本：v1.1

将给定的参数进行连接。

非 String 或 FixedString 类型的参数，会先使用其默认序列化方式转换为字符串。由于这会降低性能，不推荐使用非 String/FixedString 类型的参数。

语法

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

参数

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

返回值

返回由参数拼接得到的 String。如果任一参数为 NULL，则函数返回 NULL。如果没有参数，则返回空字符串。Nullable(String)

示例

字符串拼接

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

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

数字拼接

SELECT concat(42, 144)

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

concatAssumeInjective

引入于：v1.1

类似于 concat，但假设 concat(s1, s2, ...) → sn 是单射，也就是说，对不同的参数返回不同的结果。

可用于优化 GROUP BY。

语法

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

参数

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

返回值

返回通过连接各参数生成的字符串。如果任一参数值为 NULL，则函数返回 NULL。如果未传递任何参数，则返回空字符串。String

示例

GROUP BY 优化

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

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

concatWithSeparator

自 v22.12 起引入

将提供的字符串按指定的分隔符连接为一个字符串。

语法

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

别名: concat_ws

参数

sep — 要使用的分隔符。const String 或 const FixedString
exp1, exp2, ... — 要连接的表达式。类型不是 String 或 FixedString 的参数会通过其默认序列化方式转换为字符串。由于这会影响性能，不推荐使用非 String/FixedString 参数。Any

返回值

返回由参数连接生成的 String。如果任一参数值为 NULL，则函数返回 NULL。String

示例

使用示例

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

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

concatWithSeparatorAssumeInjective

引入版本：v22.12

与 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

返回值

返回由参数连接而成的字符串。如果任意参数值为 NULL，则函数返回 NULL。String

示例

用法示例

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);

┌─full_name───┬─total_score─┐
│ Jane-Smith  │         240 │
│ John-Doe    │         100 │
│ John-Wilson │         120 │
└─────────────┴─────────────┘

conv

引入版本：v1.1

在不同进制之间转换数字。

该函数将数字从一种进制转换为另一种进制。它支持从 2 到 36 的进制。对于大于 10 的进制，使用字母 A-Z（不区分大小写）表示数字 10-35。

此函数与 MySQL 的 CONV() 函数兼容。

语法

conv(number, from_base, to_base)

参数

number — 要转换的数值。可以是字符串或数值类型。 - from_base — 源基数（2–36）。必须是整数。 - to_base — 目标基数（2–36）。必须是整数。

返回值

目标基数下该数值的字符串表示形式。

示例

将十进制转换为二进制

SELECT conv('10', 10, 2)

将十六进制转换为十进制

SELECT conv('FF', 16, 10)

使用负数参数进行转换

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

FFFFFFFFFFFFFFFF

将二进制转换为八进制

SELECT conv('1010', 2, 8)

convertCharset

引入版本：v1.1

返回字符串 s 从编码 from 转换为编码 to 后的结果。

语法

convertCharset(s, from, to)

参数

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

返回值

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

示例

用法示例

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

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

damerauLevenshteinDistance

引入版本：v24.1

计算两个字节字符串之间的 Damerau-Levenshtein 距离。

语法

damerauLevenshteinDistance(s1, s2)

参数

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

返回值

返回两个字符串的 Damerau-Levenshtein 距离。UInt64

示例

用法示例

SELECT damerauLevenshteinDistance('clickhouse', 'mouse')

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

decodeHTMLComponent

自 v23.9 起引入

将字符串中的 HTML 实体解码为对应的字符。

语法

decodeHTMLComponent(s)

参数

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

返回值

返回一个字符串，其中的 HTML 实体已被解码。String

示例

使用示例

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

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

decodeXMLComponent

引入版本：v21.2

将字符串中的 XML 实体解码为对应的字符。

语法

decodeXMLComponent(s)

参数

s — 包含要解码的 XML 实体的字符串。String

返回值

返回对其中 XML 实体解码后的字符串。String

示例

使用示例

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

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

editDistance

于 v23.9 引入

计算两个字节串之间的编辑距离。

语法

editDistance(s1, s2)

别名: levenshteinDistance

参数

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

返回值

返回两个字符串之间的编辑距离。UInt64

示例

使用示例

SELECT editDistance('clickhouse', 'mouse')

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

editDistanceUTF8

引入版本：v24.6

计算两个 UTF-8 字符串之间的编辑距离。

语法

editDistanceUTF8(s1, s2)

别名：levenshteinDistanceUTF8

参数

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

返回值

返回两个 UTF-8 字符串之间的编辑距离。UInt64

示例

使用示例

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

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

encodeXMLComponent

自 v21.1 引入

对字符进行转义，以便将字符串放入 XML 文本节点或属性中。

语法

encodeXMLComponent(s)

参数

s — 要转义的字符串。String

返回值

返回转义后的字符串。String

示例

使用示例

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

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

endsWith

自 v1.1 版本引入

检查字符串是否以指定的后缀结尾。

语法

endsWith(s, suffix)

参数

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

返回值

如果 s 以 suffix 结尾，则返回 1，否则返回 0。UInt8

示例

使用示例

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

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

endsWithCaseInsensitive

引入于：v25.9

检查字符串的结尾是否为给定的不区分大小写的后缀。

语法

endsWithCaseInsensitive(s, suffix)

参数

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

返回值

如果 s 的结尾在不区分大小写的情况下等于 suffix，则返回 1，否则返回 0。UInt8

示例

用法示例

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

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

endsWithCaseInsensitiveUTF8

引入于：v25.9

返回字符串 s 是否以不区分大小写的 suffix 结尾。假定该字符串包含有效的 UTF-8 编码文本。如果该假设不成立，不会抛出异常，结果未定义。

语法

endsWithCaseInsensitiveUTF8(s, suffix)

参数

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

返回值

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

示例

使用示例

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

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

endsWithUTF8

引入版本：v23.8

返回字符串 s 是否以 suffix 结尾。假设该字符串包含有效的 UTF-8 编码文本。如果该假设不成立，则不会抛出异常，且结果未定义。

语法

endsWithUTF8(s, suffix)

参数

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

返回值

如果 s 以 suffix 结尾，则返回 1，否则返回 0。UInt8

示例

使用示例

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

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

extractTextFromHTML

引入版本：v21.3

从 HTML 或 XHTML 中提取文本内容。

该函数会移除 HTML 标签、注释以及 script/style 元素，只保留文本内容。它执行以下操作：

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

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

语法

extractTextFromHTML(html)

参数

html — 包含要提取文本内容的 HTML 字符串。String

返回值

返回提取出的文本内容，其中空白字符已规范化处理。String

示例

用法示例

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

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

firstLine

引入版本：v23.7

返回一个多行字符串的第一行。

语法

firstLine(s)

参数

s — 输入字符串。String

返回值

返回输入字符串的第一行；如果没有换行符，则返回整个字符串。String

示例

用法示例

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

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

idnaDecode

引入版本：v24.1

根据 Internationalized Domain Names in Applications（IDNA）机制，返回域名的 Unicode（UTF-8）表示（ToUnicode 算法）。如果发生错误（例如输入无效），则返回原始输入字符串。请注意，由于大小写归一化，多次调用 idnaEncode() 和 idnaDecode() 不一定会返回原始字符串。

语法

idnaDecode(s)

参数

s — 输入字符串。String

返回值

按照 IDNA 机制返回输入字符串的 Unicode（UTF-8）表示形式。String

示例

用法示例

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

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

idnaEncode

引入版本：v24.1

根据 Internationalized Domain Names in Applications（IDNA）机制，返回域名的 ASCII 表示形式（ToASCII 算法）。输入字符串必须是 UTF 编码（例如 UTF-8）且可转换为 ASCII 字符串，否则会抛出异常。

注意

不会对百分号编码进行解码，也不会修剪制表符、空格或控制字符。

语法

idnaEncode(s)

参数

s — 输入字符串。String

返回值

按照 IDNA 机制返回输入字符串的 ASCII 表示形式。String

示例

用法示例

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

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

initcap

自 v23.7 引入

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

注意

由于 initcap 仅将每个单词的首字母转换为大写，对于包含撇号或已有大写字母的单词，您可能会遇到意外行为。这是已知行为，目前没有修复计划。

语法

initcap(s)

参数

s — 输入字符串。String

返回值

返回对 s 中每个单词的首字母转换为大写后的结果。String

示例

使用示例

SELECT initcap('building for fast')

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

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

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

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

initcapUTF8

引入版本：v23.7

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

注意

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

语法

initcapUTF8(s)

参数

s — 输入字符串。String

返回值

返回将 s 中每个单词首字母转换为大写后的字符串。String

示例

用法示例

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

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

isValidASCII

引入版本：v25.9

如果输入的 String 或 FixedString 仅包含 ASCII 字节（0x00–0x7F），则返回 1，否则返回 0。针对正向场景（输入是有效 ASCII）进行了优化。

语法

别名: isASCII

参数

无。

返回值

示例

isValidASCII

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

isValidUTF8

引入版本：v20.1

检查某个字节序列是否构成有效的 UTF-8 编码文本。

语法

isValidUTF8(s)

参数

s — 用于检查其 UTF-8 编码是否有效的字符串。String

返回值

如果这组字节构成有效的 UTF-8 编码文本，则返回 1，否则返回 0。UInt8

示例

用法示例

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

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

jaroSimilarity

在 v24.1 中引入

计算两个字节字符串之间的 Jaro 相似度。

语法

jaroSimilarity(s1, s2)

参数

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

返回值

返回两个字符串之间的 Jaro 相似度。Float64

示例

用法示例

SELECT jaroSimilarity('clickhouse', 'click')

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

jaroWinklerSimilarity

自 v24.1 起引入

计算两个字节串之间的 Jaro-Winkler 相似度。

语法

jaroWinklerSimilarity(s1, s2)

参数

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

返回值

返回两个字符串之间的 Jaro-Winkler 相似度。Float64

示例

使用示例

SELECT jaroWinklerSimilarity('clickhouse', 'click')

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

left

引入版本：v22.1

返回字符串 s 中，从左侧起、在指定 offset 处开始的子字符串。

语法

left(s, offset)

参数

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

返回值

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

示例

正偏移量

SELECT left('Hello World', 5)

Hello

负偏移

SELECT left('Hello World', -6)

Hello

leftPad

引入于：v21.8

从左侧开始使用空格或指定字符串（必要时可重复多次）填充，直到结果字符串达到指定的 length。

语法

leftPad(string, length[, pad_string])

别名: lpad

参数

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

返回值

返回一个按指定长度左侧填充后的字符串。String

示例

用法示例

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

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

leftPadUTF8

引入于：v21.8

从左侧使用空格或指定字符串（必要时可重复多次）填充 UTF-8 字符串，直到结果字符串达到给定长度。与按字节数计算字符串长度的 leftPad 不同，这里的字符串长度按 Unicode 码点数计算。

语法

leftPadUTF8(string, length[, pad_string])

参数

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

返回值

返回指定长度的左侧填充字符串。String

示例

用法示例

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

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

leftUTF8

引入于：v22.1

返回 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

示例

正偏移量

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

Прив

负偏移量

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

Пр

lengthUTF8

引入版本：v1.1

返回字符串的长度，以 Unicode 码点数量计算，而不是以字节或字符计算。该函数假定字符串包含有效的 UTF-8 编码文本。如果这一假设不成立，则不会抛出异常，且结果未定义。

语法

lengthUTF8(s)

别名: CHARACTER_LENGTH, CHAR_LENGTH

参数

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

返回值

字符串 s 的长度，以 Unicode 码点计。UInt64

示例

用法示例

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

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

lower

首次引入于：v1.1

将 ASCII 字符串转换为小写形式。

语法

lower(s)

别名: lcase

参数

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

返回值

返回由 s 转换得到的小写字符串。String

示例

使用示例

SELECT lower('CLICKHOUSE')

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

lowerUTF8

引入版本：v1.1

将字符串转换为小写，假定该字符串包含有效的 UTF-8 编码文本。如果该假设不成立，则不会抛出异常，且结果未定义。

语法

lowerUTF8(input)

参数

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

返回值

返回一个小写形式的字符串。String

示例

第一个

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

münchen

normalizeUTF8NFC

引入于：v21.11

根据 NFC 规范化形式对 UTF-8 字符串进行规范化。

语法

normalizeUTF8NFC(str)

参数

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

返回值

返回该 UTF-8 字符串的 NFC 归一化形式。String

示例

用法示例

SELECT
'é' AS original, -- e + combining acute accent (U+0065 + U+0301)
length(original),
normalizeUTF8NFC('é') AS nfc_normalized, -- é (U+00E9)
length(nfc_normalized);

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

normalizeUTF8NFD

引入于：v21.11

根据 NFD 规范形式对 UTF-8 字符串进行规范化。

语法

normalizeUTF8NFD(str)

参数

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

返回值

返回该 UTF-8 字符串的 NFD 规范化形式。String

示例

用法示例

SELECT
    'é' AS original, -- é (U+00E9)
    length(original),
    normalizeUTF8NFD('é') AS nfd_normalized, -- e + combining acute (U+0065 + U+0301)
    length(nfd_normalized);

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

normalizeUTF8NFKC

引入版本：v21.11

根据 NFKC 规范化形式对 UTF-8 字符串进行规范化处理。

语法

normalizeUTF8NFKC(str)

参数

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

返回值

返回该 UTF-8 字符串的 NFKC 规范化形式。String

示例

使用示例

SELECT
    '① ② ③' AS original,                            -- Circled number characters
    normalizeUTF8NFKC('① ② ③') AS nfkc_normalized;  -- Converts to 1 2 3

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

normalizeUTF8NFKD

新增于：v21.11

根据 NFKD 规范化形式对 UTF-8 字符串进行规范化。

语法

normalizeUTF8NFKD(str)

参数

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

返回值

返回该 UTF-8 字符串的 NFKD 规范化形式。String

示例

使用示例

SELECT
    'H₂O²' AS original,                            -- H + subscript 2 + O + superscript 2
    normalizeUTF8NFKD('H₂O²') AS nfkd_normalized;  -- Converts to H 2 O 2

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

punycodeDecode

自 v24.1 引入

返回由 Punycode 编码字符串解码得到的 UTF8 编码明文字符串。如果给定的字符串不是有效的 Punycode 编码字符串，则会抛出异常。

语法

punycodeDecode(s)

参数

s — Punycode 编码的字符串。String

返回值

返回输入值对应的明文字符串。String

示例

用法示例

SELECT punycodeDecode('Mnchen-3ya')

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

punycodeEncode

自 v24.1 起引入

返回字符串的 Punycode 编码表示。字符串必须为 UTF-8 编码，否则其行为未定义。

语法

punycodeEncode(s)

参数

s — 输入值。String

返回值

返回输入值的 Punycode 表示。String

示例

用法示例

SELECT punycodeEncode('München')

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

regexpExtract

引入版本：v23.2

从 haystack 中提取与正则表达式模式匹配且对应指定正则捕获组索引的第一个子串。

语法

regexpExtract(haystack, pattern[, index])

别名: REGEXP_EXTRACT

参数

haystack — 在其中进行正则表达式模式匹配的字符串。String
pattern — 正则表达式字符串。pattern 可以包含多个正则表达式分组，index 指示要提取哪个分组。索引为 0 表示匹配整个正则表达式。const String
index — 可选。一个大于等于 0 的整数，默认值为 1。表示要提取的正则表达式分组编号。(U)Int*

返回值

返回匹配的字符串 String

示例

用法示例

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+)-(\\d+)', 1)─┬─regexpExtract('100-200', '(\\d+)-(\\d+)', 2)─┬─regexpExtract('100-200', '(\\d+)-(\\d+)', 0)─┬─regexpExtract('100-200', '(\\d+)-(\\d+)')─┐
│ 100                                          │ 200                                          │ 100-200                                      │ 100                                       │
└──────────────────────────────────────────────┴──────────────────────────────────────────────┴──────────────────────────────────────────────┴───────────────────────────────────────────┘

repeat

自 v20.1 起引入

按指定次数将字符串与其自身拼接。

语法

repeat(s, n)

参数

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

返回值

一个字符串，其内容为将字符串 s 重复 n 次后的结果。如果 n 为负数，函数返回空字符串。String

示例

用法示例

SELECT repeat('abc', 10)

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

reverseUTF8

引入版本：v1.1

反转字符串中的一系列 Unicode 码点。假定字符串包含有效的 UTF-8 编码文本。如果该假设不成立，不会抛出异常，结果未定义。

语法

reverseUTF8(s)

参数

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

返回值

返回一个字符串，其中的 Unicode 码点序列被反转。String

示例

用法示例

SELECT reverseUTF8('ClickHouse')

esuoHkcilC

right

引入版本：v22.1

返回字符串 s 从右侧开始、长度为指定 offset 的子字符串。

语法

right(s, offset)

参数

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

返回值

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

示例

正偏移量

SELECT right('Hello', 3)

llo

负偏移

SELECT right('Hello', -3)

lo

rightPad

引入版本：v21.8

从右侧使用空格或指定字符串（必要时可重复多次）填充字符串，直到结果字符串达到指定的 length。

语法

rightPad(string, length[, pad_string])

别名: rpad

参数

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

返回值

返回指定长度的右侧填充后的字符串。String

示例

用法示例

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

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

rightPadUTF8

自 v21.8 起提供

从右侧开始使用空格或指定字符串（必要时可重复多次）对字符串进行填充，直到结果字符串达到给定长度。与按字节计算字符串长度的 rightPad 不同，这里的字符串长度按 Unicode 码点计量。

语法

rightPadUTF8(string, length[, pad_string])

参数

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

返回值

返回指定长度的右侧填充后的字符串。String

示例

用法示例

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

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

rightUTF8

引入版本：v22.1

返回 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

示例

正偏移量

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

ивет

负偏移量

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

ет

soundex

自 v23.4 引入

返回字符串的 Soundex 编码。

语法

soundex(s)

参数

s — 输入字符串。String

返回值

返回输入字符串的 Soundex 代码。String

示例

用法示例

SELECT soundex('aksel')

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

space

自 v23.5 起引入。

将空格字符（）按指定次数重复连接。

语法

space(n)

参数

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

返回值

返回一个由空格重复 n 次组成的字符串。如果 n <= 0，函数返回空字符串。String

示例

使用示例

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

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

sparseGrams

自 v25.5 起引入

查找给定字符串中所有长度至少为 n 的子串，其中子串边界处的 (n-1)-gram 的哈希值都严格大于该子串内部任意 (n-1)-gram 的哈希值。使用 CRC32 作为哈希函数。

语法

sparseGrams(s[, min_ngram_length, max_ngram_length])

参数

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

返回值

返回选取子字符串的数组。Array(String)

示例

用法示例

SELECT sparseGrams('alice', 3)

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

sparseGramsHashes

引入版本：v25.5

查找给定字符串中所有长度至少为 n 的子串的哈希值，其中该子串边界处的 (n-1)-gram 的哈希值都严格大于该子串内部任意 (n-1)-gram 的哈希值。使用 CRC32 作为哈希函数。

语法

sparseGramsHashes(s[, min_ngram_length, max_ngram_length])

参数

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

返回值

返回所选子字符串的 CRC32 哈希值数组。Array(UInt32)

示例

用法示例

SELECT sparseGramsHashes('alice', 3)

┌─sparseGramsHashes('alice', 3)──────────────────────┐
│ [1481062250,2450405249,4012725991,1918774096]      │
└────────────────────────────────────────────────────┘

sparseGramsHashesUTF8

引入版本：v25.5

查找给定 UTF-8 字符串中所有长度至少为 n 的子字符串的哈希，这些子字符串需满足：子字符串边界处的 (n-1)-gram 的哈希值都严格大于该子字符串内部任意 (n-1)-gram 的哈希值。要求输入为 UTF-8 编码的字符串，当遇到无效的 UTF-8 序列时会抛出异常。使用 CRC32 作为哈希函数。

语法

sparseGramsHashesUTF8(s[, min_ngram_length, max_ngram_length])

参数

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

返回值

返回选定 UTF-8 子字符串的 CRC32 哈希值数组。Array(UInt32)

示例

用法示例

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

┌─sparseGramsHashesUTF8('алиса', 3)─┐
│ [4178533925,3855635300,561830861] │
└───────────────────────────────────┘

sparseGramsUTF8

引入于：v25.5

查找给定 UTF-8 字符串中所有长度至少为 n 的子字符串，这些子字符串的边界处 (n-1)-gram 的哈希值严格大于该子字符串内部任意 (n-1)-gram 的哈希值。参数为 UTF-8 编码字符串，如果输入包含无效的 UTF-8 序列则抛出异常。使用 CRC32 作为哈希函数。

语法

sparseGramsUTF8(s[, min_ngram_length, max_ngram_length])

参数

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

返回值

返回选取的 UTF-8 子串数组。Array(String)

示例

用法示例

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

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

startsWith

自 v1.1 版本引入

检查字符串是否以指定字符串开头。

语法

startsWith(s, prefix)

参数

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

返回值

如果 s 以 prefix 开头，则返回 1，否则返回 0。UInt8

示例

用法示例

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

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

startsWithCaseInsensitive

自 v25.9 引入

检查字符串是否以给定字符串（不区分大小写）开头。

语法

startsWithCaseInsensitive(s, prefix)

参数

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

返回值

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

示例

使用示例

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

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

startsWithCaseInsensitiveUTF8

引入版本：v25.9

检查字符串是否以给定的不区分大小写的前缀开头。假设字符串包含有效的 UTF-8 编码文本。如果该假设不成立，则不会抛出异常，且结果未定义。

语法

startsWithCaseInsensitiveUTF8(s, prefix)

参数

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

返回值

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

示例

用法示例

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

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

startsWithUTF8

自 v23.8 引入

检查字符串是否以指定前缀开头。假定字符串包含有效的 UTF-8 编码文本。如果该假设不成立，则不会抛出异常，且结果未定义。

语法

startsWithUTF8(s, prefix)

参数

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

返回值

如果 s 以 prefix 开头，则返回 1，否则返回 0。UInt8

示例

用法示例

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

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

stringBytesEntropy

引入版本：v25.6

计算字符串中字节分布的 Shannon 熵。

语法

stringBytesEntropy(s)

参数

s — 要分析的字符串。String

返回值

返回字符串中字节分布的 Shannon 熵值。Float64

示例

使用示例

SELECT stringBytesEntropy('Hello, world!')

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

stringBytesUniq

首次引入于：v25.6

统计字符串中不同字节的个数。

语法

stringBytesUniq(s)

参数

s — 要分析的字符串。String

返回值

返回字符串中唯一字节的数量。UInt16

示例

用法示例

SELECT stringBytesUniq('Hello')

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

stringJaccardIndex

自 v23.11 版本引入

计算两个字节字符串之间的 Jaccard 相似系数。

语法

stringJaccardIndex(s1, s2)

参数

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

返回值

返回两个字符串之间的 Jaccard 相似系数。Float64

示例

用法示例

SELECT stringJaccardIndex('clickhouse', 'mouse')

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

stringJaccardIndexUTF8

自 v23.11 引入

与 stringJaccardIndex 类似，但用于 UTF-8 编码的字符串。

语法

stringJaccardIndexUTF8(s1, s2)

参数

s1 — 第一个输入的 UTF-8 字符串。String
s2 — 第二个输入的 UTF-8 字符串。String

返回值

返回两个 UTF-8 字符串之间的 Jaccard 相似系数。Float64

示例

用法示例

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

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

substring

引入版本：v1.1

返回字符串 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*

返回值

返回从索引 offset 开始、长度最多为 length 个字节的 s 的子字符串。String

示例

基本用法

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

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

substringIndex

引入于：v23.7

返回字符串 s 中在分隔符 delim 出现 count 次之前的子串，其行为与 Spark 或 MySQL 中相同。

语法

substringIndex(s, delim, count)

别名: SUBSTRING_INDEX

参数

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

返回值

返回 s 中在第 count 次出现的 delim 之前的子串。String

示例

用法示例

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

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

substringIndexUTF8

引入于：v23.7

返回在分隔符 delim 第 count 次出现之前的 s 的子字符串，专门按 Unicode 码点进行处理。假定该字符串包含有效的 UTF-8 编码文本。如果该假设不成立，则不会抛出异常，结果未定义。

语法

substringIndexUTF8(s, delim, count)

参数

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

返回值

返回 s 中第 count 次出现 delim 之前的子字符串。String

示例

UTF8 示例

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

www.straßen-in-europa

substringUTF8

引入版本：v1.1

返回字符串 s 的子字符串，该子字符串从指定的码点索引 offset 处开始。码点计数从 1 开始，遵循以下逻辑：

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

可选参数 length 指定返回的子字符串允许拥有的最大码点数。

注意

此函数假定字符串包含有效的 UTF-8 编码文本。如果不满足该假设，则不会抛出异常，且结果未定义。

语法

substringUTF8(s, offset[, length])

参数

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

返回值

返回从码点索引 offset 开始，长度为 length 个码点的 s 的子串。String

示例

用法示例

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

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

toValidUTF8

自 v20.1 引入

将字符串中的任意无效 UTF-8 字符替换为替换字符 �（U+FFFD），从而转换为有效的 UTF-8 编码。当遇到多个连续的无效字符时，会合并为单个替换字符。

语法

toValidUTF8(s)

参数

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

返回值

返回一个有效的 UTF-8 字符串。String

示例

使用示例

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

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

trimBoth

自 v20.1 引入

从字符串的开头和结尾移除指定的字符。默认情况下，会移除常见的空白字符（ASCII）。

语法

trimBoth(s[, trim_characters])

别名: trim

参数

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

返回值

返回在字符串两端移除指定字符后的结果。String

示例

用法示例

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

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

trimLeft

自 v20.1 起引入

从字符串开头移除指定字符。默认情况下，会移除常见的空白（ASCII）字符。

语法

trimLeft(input[, trim_characters])

别名: ltrim

参数

input — 要处理的字符串。String
trim_characters — 可选。要去除的字符。如果未指定，则会删除常见空白字符。String

返回值

返回从左侧去除了指定字符的字符串。String

示例

用法示例

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

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

trimRight

引入于：v20.1

从字符串末尾移除指定字符。默认会移除常见的空白（ASCII）字符。

语法

trimRight(s[, trim_characters])

别名: rtrim

参数

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

返回值

返回从右侧去除了指定字符的字符串。String

示例

使用示例

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

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

tryBase32Decode

自 v25.6 引入

接收一个字符串，并使用 Base32 编码方案对其进行解码。

语法

tryBase32Decode(encoded)

参数

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

返回值

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

示例

用法示例

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

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

tryBase58Decode

自 v22.10 引入

类似于 base58Decode，但在出错时返回空字符串。

语法

tryBase58Decode(encoded)

参数

encoded — 字符串列或常量。如果字符串不是有效的 Base58 编码，出错时返回空字符串。String

返回值

返回一个包含参数解码结果的字符串。String

示例

用法示例

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

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

tryBase64Decode

自 v18.16 起引入

与 base64Decode 类似，但在发生错误时返回空字符串。

语法

tryBase64Decode(encoded)

参数

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

返回值

返回一个包含该参数解码结果的字符串。String

示例

使用示例

SELECT tryBase64Decode('Y2xpY2tob3VzZQ==')

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

tryBase64URLDecode

引入自：v18.16

与 base64URLDecode 类似，但在发生错误时返回空字符串。

语法

tryBase64URLDecode(encoded)

参数

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

返回值

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

示例

用法示例

SELECT tryBase64URLDecode('aHR0cHM6Ly9jbGlja2hvdXNlLmNvbQ')

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

tryIdnaEncode

引入版本：v24.1

根据 Internationalized Domain Names in Applications（IDNA）机制，返回域名的 Unicode（UTF-8）表示形式（使用 ToUnicode 算法）。在发生错误时，它会返回空字符串，而不是抛出异常。

语法

tryIdnaEncode(s)

参数

s — 输入字符串。String

返回值

根据输入值的 IDNA 规则返回输入字符串的 ASCII 表示形式，如果输入无效则返回空字符串。String

示例

用法示例

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

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

tryPunycodeDecode

自 v24.1 起引入

类似于 punycodeDecode，但如果给定的字符串不是有效的 Punycode 编码，则返回空字符串。

语法

tryPunycodeDecode(s)

参数

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

返回值

返回输入值解码后的字符串，如果输入无效则返回空字符串。String

示例

用法示例

SELECT tryPunycodeDecode('Mnchen-3ya')

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

upper

引入于：v1.1

将字符串中的 ASCII 拉丁字符转换为大写形式。

语法

upper(s)

别名：ucase

参数

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

返回值

返回由 s 转换得到的大写字符串。String

示例

用法示例

SELECT upper('clickhouse')

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

upperUTF8

引入版本：v1.1

在假定字符串包含有效 UTF-8 编码文本的前提下，将字符串转换为大写。如果这一假设不成立，则不会抛出异常，且结果未定义。

注意

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

语法

upperUTF8(s)

参数

s — 字符串类型。String

返回值

返回一个 String 数据类型的值。String

示例

用法示例

SELECT upperUTF8('München') AS Upperutf8

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

CRC32​

CRC32IEEE​

CRC64​

appendTrailingCharIfAbsent​

ascii​

base32Decode​

base32Encode​

base58Decode​

base58Encode​

base64Decode​

base64Encode​

base64URLDecode​

base64URLEncode​

basename​

byteHammingDistance​

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​

normalizeUTF8NFC​

normalizeUTF8NFD​

normalizeUTF8NFKC​

normalizeUTF8NFKD​

punycodeDecode​

punycodeEncode​

regexpExtract​

repeat​

reverseUTF8​

right​

rightPad​

rightPadUTF8​

rightUTF8​

soundex​

space​

sparseGrams​

sparseGramsHashes​

sparseGramsHashesUTF8​

sparseGramsUTF8​

startsWith​

startsWithCaseInsensitive​

startsWithCaseInsensitiveUTF8​

startsWithUTF8​

stringBytesEntropy​

stringBytesUniq​

stringJaccardIndex​

stringJaccardIndexUTF8​

substring​

substringIndex​

substringIndexUTF8​

substringUTF8​

CRC32

CRC32IEEE

CRC64

appendTrailingCharIfAbsent

ascii

base32Decode

base32Encode

base58Decode

base58Encode

base64Decode

base64Encode

base64URLDecode

base64URLEncode

basename

byteHammingDistance

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

normalizeUTF8NFC

normalizeUTF8NFD

normalizeUTF8NFKC

normalizeUTF8NFKD

punycodeDecode

punycodeEncode

regexpExtract

repeat

reverseUTF8

right

rightPad

rightPadUTF8

rightUTF8

soundex

space

sparseGrams

sparseGramsHashes

sparseGramsHashesUTF8

sparseGramsUTF8

startsWith

startsWithCaseInsensitive

startsWithCaseInsensitiveUTF8

startsWithUTF8

stringBytesEntropy

stringBytesUniq

stringJaccardIndex

stringJaccardIndexUTF8

substring

substringIndex

substringIndexUTF8

substringUTF8