跳转到主要内容
本节中的所有函数默认都执行区分大小写的搜索。不区分大小写的搜索通常由单独的函数变体提供。
不区分大小写的搜索遵循英语的大小写转换规则。例如,英语中的小写 i 的大写形式是 I,而土耳其语中则是 İ——对于英语以外的语言,结果可能不符合预期。
本节中的函数还假定被搜索的字符串 (本节中称为 haystack) 和搜索字符串 (本节中称为 needle) 都是单字节编码文本。如果这一假设 不成立,不会抛出异常,结果未定义。对 UTF-8 编码字符串的搜索通常由单独的函数 变体提供。同样,如果使用 UTF-8 函数变体,而输入字符串并非 UTF-8 编码文本,也不会抛出异常,且 结果未定义。请注意,不会自动执行 Unicode 规范化,不过你可以使用 normalizeUTF8*() 函数来实现这一点。 通用字符串函数 和 字符串替换函数 将单独介绍。
以下文档由 system.functions 系统表生成。

countMatches

引入版本:v21.1.0 返回字符串中正则表达式的匹配次数。
此函数的行为取决于 ClickHouse 版本:
  • 在 < v25.6 的版本中,即使模式能够匹配空字符串,函数也会在第一次空匹配时停止计数。
  • 在 >= 25.6 的版本中,发生空匹配时,函数会继续执行。可使用设置 count_matches_stop_at_empty_match = true 恢复旧版行为;
语法
参数
  • haystack — 要搜索的字符串。String
  • pattern — 正则表达式模式。String
返回值 返回找到的匹配次数。UInt64 示例 统计数字串的数量
Query
Response

countMatchesCaseInsensitive

引入版本:v21.1.0 与 countMatches 类似,但执行不区分大小写的匹配。 语法
参数
  • haystack — 要在其中搜索的字符串。String
  • pattern — 正则表达式模式。const String
返回值 返回找到的匹配次数。UInt64 示例 不区分大小写的计数
Query
Response

countSubstrings

引入版本:v21.1.0 返回子串 needle 在字符串 haystack 中出现的频次。 语法
参数
  • haystack — 要在其中执行搜索的 String。String 或 枚举。 - needle — 要搜索的子串。String。 - start_pos — 在 haystack 中开始搜索的位置 (从 1 开始计数) 。UInt。可选。
返回值 出现的次数。UInt64 示例 使用示例
Query
Response
使用 start_pos 参数
Query
Response

countSubstringsCaseInsensitive

引入版本:v21.1.0 与 countSubstrings 类似,但按不区分大小写的方式计数。 语法
参数
  • haystack — 执行搜索的字符串。String 或 枚举
  • needle — 要搜索的子串。String
  • start_pos — 可选。在 haystack 中开始搜索的位置 (从 1 开始计数) 。UInt*
返回值 返回 needle 在 haystack 中出现的次数。UInt64 示例 使用示例
Query
Response
使用 start_pos 参数
Query
Response

countSubstringsCaseInsensitiveUTF8

Introduced in: v21.1.0 与 countSubstrings 类似,但以不区分大小写的方式进行计数,并假定 haystack 为 UTF-8 字符串。 Syntax
参数
  • haystack — 执行搜索的 UTF-8 字符串。String 或 枚举
  • needle — 要搜索的子串。String
  • start_pos — 可选。在 haystack 中开始搜索的位置 (从 1 开始) 。UInt*
返回值 返回 needle 在 haystack 中出现的次数。UInt64 示例 使用示例
Query
Response
使用 start_pos 参数
Query
Response

extract

Introduced in:v1.1.0 提取字符串中第一个匹配正则表达式的内容。 如果 ‘haystack’ 与 ‘pattern’ 不匹配,则返回空字符串。 此函数使用 RE2 regular expression 库。支持的语法请参阅 re2。 如果正则表达式包含 捕获组 (子模式) ,则函数会返回输入字符串中与第一个 捕获组 匹配的内容。 Syntax
参数
  • haystack — 要从中提取内容的 String。String
  • pattern — 正则表达式,通常包含一个捕获组。const String
返回值 返回提取出的字符串片段。String 示例 从电子邮件地址中提取域名
Query
Response
未匹配时返回空字符串
Query
Response

extractAll

引入于:v1.1.0 与 extract 类似,但返回字符串中匹配正则表达式的所有结果组成的数组。 如果 ‘haystack’ 不匹配 ‘pattern’ 正则表达式,则返回空数组。 如果正则表达式包含捕获组 (子模式) ,则该函数会针对第一个捕获组匹配输入字符串。 语法
参数
  • haystack — 要从中提取片段的 String。String
  • pattern — 正则表达式,可包含捕获组。const String
返回值 返回提取出的片段数组。Array(String) 示例 提取所有数字
Query
Response
使用捕获组提取
Query
Response

extractAllGroupsHorizontal

引入版本:v20.5.0 使用提供的正则表达式匹配字符串中的所有组,并返回一个嵌套数组,其中每个数组包含同一捕获组的所有捕获结果,按组号排列。 语法
参数 返回值 返回一个嵌套数组,其中每个内部数组都包含某个捕获组在所有匹配结果中的全部捕获内容。第一个内部数组包含第 1 组的所有捕获,第二个包含第 2 组的所有捕获,依此类推。如果未找到匹配项,则返回空数组。Array(Array(String)) 示例 使用示例
Query
Response

extractGroups

引入版本: v20.5.0 从正则表达式匹配到的第一个子串中提取捕获组。要从所有匹配结果中提取捕获组,请使用 extractAllGroupsHorizontal 或 extractAllGroupsVertical。 语法
参数 返回值 如果正则表达式匹配,则返回一个数组,包含首次匹配中捕获的各组 (1 到 N,其中 N 为 regexp 中捕获组的数量) 。如果没有匹配,则返回空数组。Array(String) 示例 使用示例
Query
Response

hasAllTokens

引入版本:v25.10.0 与 hasAnyTokens 类似,但仅当 needle 字符串或数组中的所有标记都与 input 字符串匹配时返回 1,否则返回 0。如果 input 是一列,则返回满足此条件的所有行。
列 input 应定义一个文本索引以获得最佳性能。 如果未定义文本索引,该函数会对该列执行穷举列扫描,其速度比索引查找慢几个数量级。
在搜索之前,该函数会对文本进行分词处理
  • input 参数 (始终如此) 以及
  • needle 参数 (如果为 String) 会使用为文本索引指定的分词器进行处理。 如果该列未定义文本索引,则会改用 splitByNonAlpha 分词器。 如果 needle 参数的类型为 Array(String),则数组中的每个元素都会被视为一个标记——不会再进行额外的标记化。 如果文本索引配置了预处理器表达式,则会在标记化之前将预处理器应用到 needle (如果其类型为 String) 。 如果文本索引配置了后处理器表达式,则会将后处理器应用到 needle 标记和 input 标记 (即两者都在标记化之后处理) 。
重复的标记将被忽略。 例如,needles = [‘ClickHouse’, ‘ClickHouse’] 与 [‘ClickHouse’] 等效。
当文本索引定义了一个预处理器 (例如 lowerUTF8) 时,hasAllTokens 会将其应用于 input;如果 needles 是 String,则也会在标记化之前将其应用于 needles。当 needles 是 Array(String) 时,其元素会按原样传递,不会对其应用预处理器。 预处理器是索引定义的一部分,因此无论在何处对该函数求值,都会应用预处理器:无论是在 WHERE/PREWHERE 过滤器中还是在 SELECT 列表中,也无论是否读取索引 (例如 SETTINGS use_skip_indexes = 0) 。
语法
别名: hasAllToken 参数 返回值 如果所有 needle 都匹配,则返回 1;否则返回 0。UInt8 示例 使用字符串 needle 的基本用法
Query
Response
指定要在数组中按 AS-IS (不分词) 方式搜索的 needles
Query
Response
使用 tokens 函数生成 needles
Query
Response
通过第 3 个参数指定自定义分词器
Query
Response
数组列和 Map 列的使用示例
Query
数组列示例
Query
Response
使用 mapKeys 的示例
Query
Response
mapValues 示例
Query
Response

hasAnyTokens

引入版本:v25.10.0 如果 needle 字符串或数组中至少有一个标记与 input 字符串匹配,则返回 1,否则返回 0。如果 input 是一列,则返回满足此条件的所有行。
列 input 应定义 文本索引,以获得最佳性能。 如果未定义文本索引,该函数会对列执行穷举列扫描,其速度比索引查找慢几个数量级。
在搜索之前,该函数会对文本进行分词处理
  • input 参数 (始终如此) ,以及
  • needle 参数 (如果其类型为 String) 会使用为文本索引指定的分词器进行分词。 如果该列未定义文本索引,则会改用 splitByNonAlpha 分词器。 如果 needle 参数的类型为 Array(String),则会将数组中的每个元素视为一个标记——不会再进行额外标记化。 如果文本索引配置了 预处理器 表达式,则会在标记化前将预处理器应用于 needle (如果其类型为 String)。 如果文本索引配置了 后处理器 表达式,则会在标记化后将后处理器应用于 needle 标记和 input 标记 (即两者都会应用)。
重复的标记将被忽略。 例如,[‘ClickHouse’, ‘ClickHouse’] 与 [‘ClickHouse’] 的处理方式相同。
当文本索引定义了预处理器 (例如 lowerUTF8) 时,hasAnyTokens 会在标记化前将其应用于 input;当 needles 为 String 时,也会将其应用于 needles。当 needles 为 Array(String) 时,其元素会按原样传递,不会对其应用预处理器。 预处理器是索引定义的一部分,因此无论该函数在何处求值都会应用它:无论是在 WHERE/PREWHERE 过滤器中还是在 SELECT 列表中,也无论是否读取索引 (例如 SETTINGS use_skip_indexes = 0) 。
语法
别名: hasAnyToken 参数 返回值 如果至少有一个匹配项,则返回 1,否则返回 0。UInt8 示例 使用字符串 needle 的基本示例
Query
Response
在 array 中指定按 AS-IS 方式搜索的 needles (不进行标记化)
Query
Response
使用 tokens 函数生成 needles
Query
Response
数组列和 Map 列的使用示例
Query
数组列示例
Query
Response
使用 mapKeys 的示例
Query
Response
使用 mapValues 的示例
Query
Response

hasPhrase

引入版本:v26.4.0 检查 input 是否按连续顺序包含 phrase 中的所有标记。
为获得最佳性能,列 input 应定义 文本索引。 如果未定义 文本索引,该函数会执行穷举列扫描,其速度比索引查找慢几个数量级。
搜索前,该函数会使用为 文本索引 指定的分词器对 input 进行标记化;当 phrase 为 String 时,也会对其进行标记化。 如果该列未定义 文本索引,则改用 splitByNonAlpha 分词器——除非通过可选的第三个参数提供了分词器。 tokenizer 参数必须是 splitByNonAlpha、splitByString、splitByRegexp、array、ngrams、asciiCJK 或 icu 之一。 如果 input 是 Array(String),其元素会像其他输入一样进行标记化,且每行的所有标记组成一个序列,因此一个短语可以跨越两个元素。使用 array 分词器时,每个元素即为一个标记,可借此搜索由已标记化的值组成的列。 如果 phrase 是 Array(String),其元素即为要搜索的标记,按顺序匹配且 包括重复项。空的短语元素会被忽略,因为任何分词器都不会生成空标记。
当 文本索引 定义了 预处理器 (例如 lowerUTF8) 时,hasPhrase 会在标记化前将其应用于 input 和 phrase。 预处理器是索引定义的一部分,因此无论在何处对该函数求值,预处理器都会生效:无论是在 WHERE/PREWHERE 过滤器中还是在 SELECT 列表中,也无论是否读取索引 (例如 SETTINGS use_skip_indexes = 0) 。
与 hasToken、hasAnyTokens 和 hasAllTokens 不同,hasPhrase 要求这些标记按相同顺序连续出现, 中间不能有任何其他标记。例如,hasPhrase('the quick brown fox', 'quick fox') 返回 0, 因为 “brown” 出现在 “quick” 和 “fox” 之间。 语法
别名:matchPhrase 参数 返回值 如果找到该短语对应的连续标记序列,则返回 1;否则返回 0。UInt8 示例 短语匹配
Query
Response
不连续标记
Query
Response
以 array 形式指定的标记序列
Query
Response
跨越两个元素的短语
Query
Response

hasSubsequence

Introduced in: v23.7.0 检查 needle 是否是 haystack 的子序列。 字符串的子序列,是指在不改变其余字符顺序的前提下,通过删除另一个字符串中的部分字符或不删除任何字符得到的序列。 Syntax
参数
  • haystack — 在其中搜索子序列的 String。String
  • needle — 要搜索的子序列。String
返回值 如果 needle 是 haystack 的子序列,则返回 1,否则返回 0。UInt8 示例 基本的子序列检查
Query
Response
未找到子序列
Query
Response

hasSubsequenceCaseInsensitive

引入版本:v23.7.0 与 hasSubsequence 类似,但搜索时不区分大小写。 语法
参数
  • haystack — 在其中执行搜索的 String。String
  • needle — 要搜索的子序列。String
返回值 如果 needle 是 haystack 的子序列,则返回 1,否则返回 0。UInt8 示例 使用示例
Query
Response

hasSubsequenceCaseInsensitiveUTF8

引入版本:v23.7.0 与 hasSubsequenceUTF8 类似,但搜索时不区分大小写。 语法
参数
  • haystack — 执行搜索所在的 UTF8 编码字符串。String
  • needle — 要搜索的 UTF8 编码子序列字符串。String
返回值 如果 needle 是 haystack 的子序列,则返回 1;否则返回 0。UInt8 示例 使用示例
Query
Response

hasSubsequenceUTF8

引入版本:v23.7.0 与 hasSubsequence 类似,但假设 haystack 和 needle 是以 UTF-8 编码的字符串。 语法
参数
  • haystack — 要在其中进行搜索的字符串。String
  • needle — 要查找的子序列。String
返回值 如果 needle 是 haystack 的子序列,则返回 1;否则返回 0。UInt8 示例 用法示例
Query
Response
不匹配子序列
Query
Response

hasToken

引入版本:v20.1.0
在使用非 splitByNonAlpha 分词器和/或 预处理器/后处理器 表达式的文本索引中进行查找时,hasToken 存在一些隐患。 我们建议改用 hasAnyTokens 和 hasAllTokens。
检查给定的标记是否存在于 haystack 中。 使用 splitByNonAlpha 作为分词器,也就是说,标记被定义为由连续字符 [0-9A-Za-z_] (数字、ASCII 字符和下划线) 构成的最长子序列。 语法
参数 返回值 如果找到该标记,则返回 1;否则返回 0。UInt8 示例 标记搜索
Query
Response

hasTokenCaseInsensitive

引入版本:v20.1.0 使用 tokenbf_v1 索引在 haystack 中执行对 needle 的不区分大小写查找。
此函数在配合非 default 分词器以及预处理器或后处理器表达式时存在一些陷阱。 我们建议改用 hasAnyTokens 和 hasAllTokens。
语法
参数
  • 无。
返回值 示例

hasTokenCaseInsensitiveOrNull

引入版本:v23.1.0 使用 tokenbf_v1 索引在 haystack 中不区分大小写地查找 needle。如果 needle 的格式不合法,则返回 NULL。
该函数在使用非 default 分词器以及预处理器或后处理器表达式时有一些注意事项。 我们建议改用 hasAnyTokens 和 hasAllTokens。
语法
参数
  • 无。
返回值 示例

hasTokenOrNull

首次引入版本:v20.1.0 与 hasToken 类似,但如果标记格式不合法,则返回 NULL。 语法
参数
  • haystack — 要搜索的字符串。必须为常量。String
  • token — 要搜索的标记。const String
返回值 如果找到该标记,则返回 1;否则返回 0。如果 token 格式不合法,则返回 NULL。Nullable(UInt8) 示例 使用示例
Query
Response

highlight

引入版本:v26.4.0 使用 HTML 标签包裹文本字符串中搜索词的匹配项,从而将其高亮显示。 该函数执行 ASCII 不区分大小写匹配。如果多个搜索词在文本中重叠或彼此相邻,则匹配区域会合并为一个高亮 span。 语法
参数
  • haystack — 要搜索的文本。String 或 FixedString
  • needles — 要高亮显示的搜索词数组。const Array(String)
  • open_tag — 在每个匹配项前插入的起始标签。默认值:<em>。const String
  • close_tag — 在每个匹配项后插入的结束标签。默认值:</em>。const String
返回值 返回将匹配词用指定标签包裹后的输入文本。String 示例 基本高亮
Query
Response
自定义标签
Query
Response

ilike

引入版本:v20.6.0 与 like 类似,但以不区分大小写的方式进行搜索。支持可选的 ESCAPE 子句 (参见 like) 。 语法
参数
  • haystack — 执行搜索的字符串。String 或 FixedString
  • pattern — 用于匹配的 LIKE 模式。String
  • escape_character — 可选的单字符字符串,用作转义字符以替代 \。默认值:\。String
返回值 如果字符串与 LIKE 模式匹配 (不区分大小写) ,则返回 1,否则返回 0。UInt8 示例 使用示例
Query
Response

like

引入版本:v1.1.0 返回字符串 haystack 是否与 LIKE 表达式 pattern 匹配。 LIKE 表达式可以包含普通字符以及以下元符号:
  • % 表示任意数量的任意字符 (包括零个字符) 。
  • _ 表示单个任意字符。
  • \ 用于转义字面量 %、_ 和 \。
匹配基于 UTF-8 进行,例如 _ 可以匹配 Unicode 码点 ¥,该字符在 UTF-8 中占用两个字节。 如果 haystack 或 LIKE 表达式不是有效的 UTF-8,则行为未定义。 该函数不会自动执行 Unicode 规范化,如有需要,可使用 normalizeUTF8* 函数。 要匹配字面量 %、_ 和 \ (它们是 LIKE 元字符) ,请在其前面加上反斜杠:\%、\_ 和 \\。 如果反斜杠位于 %、_ 或 \ 以外的字符之前,则会失去其特殊含义 (即按字面量解释) 。
ClickHouse 要求字符串中的反斜杠同样需要转义,因此实际上需要写成 \\%、\\_ 和 \\\\。
对于 %needle% 形式的 LIKE 表达式,该函数的速度与 position 函数相当。 其他所有 LIKE 表达式都会在内部转换为正则表达式来执行,性能与 match 函数相近。 可选的 ESCAPE 子句用于指定自定义转义字符 (必须是单个 ASCII 字符) 。 提供后,自定义转义字符会替代默认的反斜杠,用于转义 % 和 _ 元字符。 转义字符可以转义三种内容:% (字面量百分号) 、_ (字面量下划线) 以及其自身 (字面量转义字符) 。 使用自定义转义字符时,反斜杠不再具有特殊含义,而是按字面量字符处理。 语法
参数
  • haystack — 要在其中执行搜索的 String。String 或 FixedString
  • pattern — 要匹配的 LIKE 模式。可包含 % (匹配任意数量的字符) 、_ (匹配单个字符) 以及用于转义的 \。String
  • escape_character — 可选的单字符字符串,用作 \ 的替代转义字符。默认值:\。String
返回值 如果字符串与 LIKE 模式匹配,则返回 1;否则返回 0。UInt8 示例 使用示例
Query
Response
单字符通配符
Query
Response
不匹配模式
Query
Response
ESCAPE 子句
Query
Response

locate

引入版本:v18.16.0 与 position 类似,但参数 haystack 和 locate 的顺序互换了。
此函数的行为取决于 ClickHouse 的版本:
  • 在 < v24.3 的版本中,locate 是函数 position 的别名,接受参数 (haystack, needle[, start_pos])。
  • 在 >= 24.3 的版本中,locate 是一个独立函数 (为了更好地兼容 MySQL) ,接受参数 (needle, haystack[, start_pos])。 可以通过设置 function_locate_has_mysql_compatible_argument_order = false 恢复之前的行为。
语法
参数
  • needle — 要搜索的子串。String
  • haystack — 要在其中进行搜索的字符串。String 或 Enum
  • start_pos — 可选。在 haystack 中开始搜索的位置 (从 1 开始计数) 。UInt
返回值 如果找到子串,则返回其起始位置 (按字节计数,且从 1 开始) ;如果未找到子串,则返回 0。UInt64 示例 基本用法
Query
Response

match

引入版本:v1.1.0 检查给定字符串是否与指定的 正则表达式 模式 匹配。 此函数使用 RE2 正则表达式 库。支持的语法请参阅 re2。 匹配基于 UTF-8 假设进行,例如 ¥ 在内部占用两个字节,但在匹配时会被视为单个码点。 正则表达式 不能包含 NULL 字节。 如果 haystack 或 模式 不是有效的 UTF-8,则其行为未定义。 与 re2 的默认行为不同,. 会匹配换行符。要禁用此行为,请在 模式 前添加 (?-s)。 模式 不会自动加上锚点。若要匹配整个字符串,请自行使用 ^ 和 $ 对 模式 加锚。 如果你只是想搜索子字符串,可以改用函数 like 或 position,它们的速度比此函数快得多。 可选的运算符语法:haystack REGEXP pattern 或 haystack ~ pattern (PostgreSQL 风格) 。 语法
别名: REGEXP_MATCHES, REGEXP_LIKE 参数
  • haystack — 在其中搜索模式的 String。String
  • pattern — 正则表达式模式。可以是常量,也可以来自列。String
返回值 如果匹配该模式,则返回 1,否则返回 0。UInt8 示例 基本模式匹配
Query
Response
模式不匹配
Query
Response
匹配子串
Query
Response

matchCaseInsensitive

引入版本:v26.8.0 与 match 类似,但进行不区分大小写的匹配。 此函数使用 RE2 正则表达式 库。支持的语法请参阅 re2。 可选的运算符语法:haystack ~* pattern (PostgreSQL 风格) 。 语法
参数
  • haystack — 在其中搜索模式的 String。String
  • pattern — 正则表达式模式。可以是常量,也可以来自列。String
返回值 如果不区分大小写地匹配该模式,则返回 1,否则返回 0。UInt8 示例 使用示例
Query
Response

multiFuzzyMatchAllIndices

引入版本:v20.1.0 与 multiFuzzyMatchAny 类似,但会返回在固定编辑距离内与 haystack 匹配的所有索引组成的数组,顺序不限。 语法
参数
  • haystack — 执行搜索的 String。String
  • distance — 模糊匹配允许的最大编辑距离。UInt8
  • pattern — 要匹配的模式数组。Array(String)
返回值 返回一个数组,包含在指定编辑距离内以任意顺序匹配 haystack 的所有索引 (从 1 开始) 。如果未找到匹配项,则返回空数组。Array(UInt64) 示例 使用示例
Query
Response

multiFuzzyMatchAny

引入版本:v20.1.0 与 multiMatchAny 类似,但如果任意模式在固定的编辑距离内匹配 haystack,则返回 1。 此函数依赖 hyperscan 库的 Experimental 功能,在某些边缘情况下可能较慢。 其性能取决于编辑距离的取值和所使用的模式,但与非模糊变体相比,开销始终更高。
由于 hyperscan 的限制,multiFuzzyMatch*() 函数家族不支持 UTF-8 正则表达式 (会将其视为字节序列) 。
语法
参数
  • haystack — 执行搜索的 String。String
  • distance — 模糊匹配 的最大编辑距离。UInt8
  • pattern — 可选。用于匹配的模式数组。Array(String)
返回值 如果任一模式在指定的 编辑距离 内与 haystack 匹配,则返回 1;否则返回 0。UInt8 示例 使用示例
Query
Response

multiFuzzyMatchAnyIndex

引入于:v20.1.0 与 multiFuzzyMatchAny 类似,但会返回在固定编辑距离内与 haystack 匹配的任意一个索引。 语法
参数
  • haystack — 执行搜索的字符串。String
  • distance — 模糊匹配允许的最大编辑距离。UInt8
  • pattern — 用于匹配的模式数组。Array(String)
返回值 返回在指定编辑距离内与 haystack 匹配的任意一个模式的索引 (从 1 开始) ;如果都不匹配,则返回 0。UInt64 示例 使用示例
Query
Response

multiMatchAllIndices

引入版本:v20.1.0 与 multiMatchAny 类似,但返回按任意顺序与 haystack 匹配的所有索引组成的数组。 语法
参数
  • haystack — 执行搜索的字符串。String
  • pattern — 用于匹配的正则表达式。String
返回值 由按任意顺序与 haystack 匹配的所有索引 (从 1 开始) 组成的数组。如果未找到匹配项,则返回空数组。Array(UInt64) 示例 使用示例
Query
Response

multiMatchAny

引入版本:v20.1.0 检查多个正则表达式 模式 中是否至少有一个与 haystack 匹配。 如果你只想在一个字符串中搜索多个子字符串,可以改用函数 multiSearchAny——它的速度比此函数快得多。 语法
参数
  • haystack — 在其中搜索模式的 String。String
  • pattern1[, pattern2, ...] — 包含一个或多个正则表达式模式的数组。Array(String)
返回值 如果任意模式匹配则返回 1,否则返回 0。UInt8 示例 多个模式匹配
Query
Response
没有任何模式匹配
Query
Response

multiMatchAnyIndex

引入版本:v20.1.0 与 multiMatchAny 类似,但会返回任意一个与 haystack 匹配的索引。 语法
参数
  • haystack — 执行搜索的字符串。String
  • pattern — 用于匹配的正则表达式。Array(String)
返回值 返回第一个匹配 pattern 的索引 (从 1 开始) ;如果未找到匹配项,则返回 0。UInt64 示例 使用示例
Query
Response

multiSearchAllPositions

Introduced in: v20.1.0 与 position 类似,但它返回一个位置数组,表示 haystack 字符串中多个 needle 子字符串的位置 (以字节为单位,从 1 开始计数) 。 所有 multiSearch*() 函数最多仅支持 2^8 个 needle。 Syntax
参数
  • haystack — 执行搜索的字符串。String
  • needle1[, needle2, ...] — 由一个或多个待搜索子字符串组成的数组。Array(String)
返回值 如果找到子串,则返回由起始位置组成的数组,位置以字节为单位并从 1 开始计数;如果未找到子串,则返回 0。Array(UInt64) 示例 多个 needle 搜索
Query
Response

multiSearchAllPositionsCaseInsensitive

引入版本:v20.1.0 与 multiSearchAllPositions 类似,但不区分大小写。 语法
参数
  • haystack — 要在其中执行搜索的 String。String
  • needle1[, needle2, ...] — 由一个或多个待搜索子字符串组成的数组。Array(String)
返回值 返回一个数组,表示起始位置 (按字节计算,从 1 开始;如果找到了子串) ;如果未找到子串,则返回 0。Array(UInt64) 示例 不区分大小写的多重搜索
Query
Response

multiSearchAllPositionsCaseInsensitiveUTF8

引入版本:v20.1.0 与 multiSearchAllPositionsUTF8 类似,但不区分大小写。 语法
参数
  • haystack — 执行搜索的 UTF-8 编码字符串。String
  • needle — 要搜索的 UTF-8 编码子字符串。Array(String)
返回值 由起始位置组成的数组;位置按字节计算,从 1 开始 (如果找到了子字符串) 。如果未找到子字符串,则返回 0。Array 示例 不区分大小写的 UTF-8 搜索
Query
Response

multiSearchAllPositionsUTF8

引入版本:v20.1.0 与 multiSearchAllPositions 类似,但假定 haystack 和 needle 子串均为 UTF-8 编码的字符串。 语法
参数
  • haystack — 要在其中执行搜索的 UTF-8 编码字符串。String
  • needle1[, needle2, ...] — 要搜索的 UTF-8 编码子字符串数组。Array(String)
返回值 返回一个数组:如果找到子串,则返回其以字节为单位、从 1 开始计数的起始位置;如果未找到子串,则返回 0。Array 示例 UTF-8 多重搜索
Query
Response

multiSearchAny

引入版本:v20.1.0 检查多个 needle 字符串中是否至少有一个与 haystack 字符串匹配。 函数 multiSearchAnyCaseInsensitive、multiSearchAnyUTF8 和 multiSearchAnyCaseInsensitiveUTF8 提供了此函数的不区分大小写和/或 UTF-8 变体。 语法
参数
  • haystack — 在其中执行搜索的 String。String
  • needle1[, needle2, ...] — 要查找的子字符串数组。Array(String)
返回值 如果至少有一个匹配项,则返回 1;否则返回 0。UInt8 示例 任意匹配查找
Query
Response

multiSearchAnyCaseInsensitive

引入版本:v20.1.0 与 multiSearchAny 类似,但不区分大小写。 语法
参数
  • haystack — 在其中执行搜索的 String。String
  • needle — 要搜索的子字符串。Array(String)
返回值 如果至少有一个不区分大小写的匹配,则返回 1;否则返回 0。UInt8 示例 不区分大小写的搜索
Query
Response

multiSearchAnyCaseInsensitiveUTF8

首次引入于:v20.1.0 与 multiSearchAnyUTF8 类似,但不区分大小写。 语法
参数
  • haystack — 在其中执行搜索的 UTF-8 字符串。String
  • needle — 待搜索的 UTF-8 子字符串。Array(String)
返回值 如果至少有一个不区分大小写的匹配,则返回 1;否则返回 0。UInt8 示例 给定 UTF-8 字符串 ‘Здравствуйте’,检查是否包含字符 ‘з’ (小写)
Query
Response

multiSearchAnyUTF8

引入版本:v20.1.0 与 multiSearchAny 类似,但假定 haystack 和 needle 子串都是 UTF-8 编码的字符串。 语法
参数
  • haystack — 执行搜索的 UTF-8 字符串。String
  • needle — 要搜索的 UTF-8 子字符串。Array(String)
返回值 如果至少有一个匹配,则返回 1;否则返回 0。UInt8 示例 给定 UTF-8 字符串 ‘你好,世界’ (‘Hello, world’) ,检查该字符串中是否包含字符 你 或 界
Query
Response

multiSearchFirstIndex

引入版本:v20.1.0 在 haystack 字符串中搜索多个 needle 字符串 (区分大小写) ,并返回找到的第一个 needle 的从 1 开始的索引。 语法
参数
  • haystack — 要在其中搜索的字符串。String
  • needles — 要查找的字符串数组。Array(String)
返回值 返回在 haystack 中找到的第一个 needle 的从 1 开始的索引 (即其在 needles 数组中的位置) 。如果未找到任何 needle,则返回 0。搜索区分大小写。UInt64 示例 用法示例
Query
Response
区分大小写
Query
Response
未找到匹配项
Query
Response

multiSearchFirstIndexCaseInsensitive

引入版本:v20.1.0 返回字符串 haystack 中最左侧匹配到的 needle_i 的索引 i (从 1 开始) ,否则返回 0。 不区分大小写。 语法
参数
  • haystack — 执行搜索的 String。String
  • needle — 要搜索的子字符串。Array(String)
返回值 返回最靠左匹配到的 needle 的索引 (从 1 开始) 。如果没有匹配项,则返回 0。UInt8 示例 使用示例
Query
Response

multiSearchFirstIndexCaseInsensitiveUTF8

引入版本:v20.1.0 在支持 UTF-8 编码的情况下,以不区分大小写的方式在 haystack 字符串中搜索多个 needle 字符串,并返回第一个匹配到的 needle 的从 1 开始的索引。 语法
参数
  • haystack — 要搜索的字符串。String
  • needles — 要查找的字符串数组。Array(String)
返回值 返回在 haystack 中找到的第一个 needle 的从 1 开始的索引 (即其在 needles 数组中的位置) 。如果未找到任何 needle,则返回 0。搜索不区分大小写,并遵循 UTF-8 字符编码。UInt64 示例 用法示例
Query
Response
UTF-8 字母大小写处理
Query
Response
未找到匹配结果
Query
Response

multiSearchFirstIndexUTF8

引入版本:v20.1.0 返回字符串 haystack 中最靠左匹配到的 needle_i 的索引 i (从 1 开始) ,否则返回 0。 假定 haystack 和 needle 是采用 UTF-8 编码的字符串。 语法
参数
  • haystack — 在其中进行搜索的 UTF-8 字符串。String
  • needle — 要搜索的 UTF-8 子字符串数组。Array(String)
返回值 返回最先找到的、最靠左的 needle 的索引 (从 1 开始计数) 。如果没有匹配,则返回 0。UInt8 示例 使用示例
Query
Response

multiSearchFirstPosition

引入版本:v20.1.0 与 position 类似,但返回 haystack 字符串中与多个 needle 字符串里任意一个匹配的最左偏移量。 函数 multiSearchFirstPositionCaseInsensitive、multiSearchFirstPositionUTF8 和 multiSearchFirstPositionCaseInsensitiveUTF8 提供了此函数的不区分大小写和/或 UTF-8 变体。 语法
参数
  • haystack — 执行搜索的 String。String
  • needle1[, needle2, ...] — 由一个或多个待搜索子字符串组成的数组。Array(String)
返回值 返回 haystack 字符串中与多个 needle 字符串中的任意一个匹配的最左侧偏移量;如果没有匹配,则返回 0。UInt64 示例 搜索首个位置
Query
Response

multiSearchFirstPositionCaseInsensitive

引入版本:v20.1.0 与 multiSearchFirstPosition 类似,但不区分大小写。 语法
参数
  • haystack — 执行搜索的字符串。String
  • needle — 要搜索的子字符串数组。Array(String)
返回值 返回 haystack 字符串中与多个 needle 字符串中的任意一个匹配的最左侧偏移量。如果没有匹配,则返回 0。UInt64 示例 大小写不敏感的第一个位置
Query
Response

multiSearchFirstPositionCaseInsensitiveUTF8

引入版本:v20.1.0 与 multiSearchFirstPosition 类似,但假定 haystack 和 needle 均为 UTF-8 字符串,且不区分大小写。 语法
参数
  • haystack — 执行搜索的 UTF-8 字符串。String
  • needle — 要搜索的 UTF-8 子字符串数组。Array(String)
返回值 返回 haystack 字符串中与多个 needle 字符串中的任意一个匹配的最左侧偏移量,忽略大小写。如果没有匹配,则返回 0。UInt64 示例 查找 UTF-8 字符串 ‘Здравствуй, мир’ (‘Hello, world’) 中与给定 needle 中任意一个匹配的最左侧偏移量
Query
Response

multiSearchFirstPositionUTF8

引入版本:v20.1.0 与 multiSearchFirstPosition 类似,但假设 haystack 和 needle 都是 UTF-8 字符串。 语法
参数
  • haystack — 执行搜索的 UTF-8 字符串。String
  • needle — 要搜索的 UTF-8 子字符串数组。Array(String)
返回值 haystack 字符串中与多个 needle 字符串中任意一个匹配的最左侧偏移量。如果没有匹配,则返回 0。UInt64 示例 查找 UTF-8 字符串 ‘Здравствуй, мир’ (‘Hello, world’) 中与给定任意一个 needle 匹配的最左侧偏移量
Query
Response

ngramDistance

引入版本:v20.1.0 计算两个字符串之间的 4-gram 距离。 为此,它会统计两个 4-gram 多重集合之间的对称差,并用它们的基数之和对结果进行归一化。 返回值越小,字符串越相似。 如需进行不区分大小写的搜索和/或使用 UTF8 格式,请使用函数 ngramDistanceCaseInsensitive、ngramDistanceUTF8、ngramDistanceCaseInsensitiveUTF8。 语法
参数
  • haystack — 用于比较的字符串。String
  • needle — 用于比较的字符串。String
返回值 返回一个介于 0 和 1 之间的 Float32 数值。返回值越小,字符串越相似。Float32 示例 计算 4-gram 距离
Query
Response

ngramDistanceCaseInsensitive

引入版本:v20.1.0 提供 ngramDistance 的不区分大小写 Variant。 计算两个字符串之间的 4-gram 距离,忽略大小写。 返回值越小,字符串越相似。 语法
参数
  • haystack — 第一个比较字符串。String
  • needle — 第二个比较字符串。String
返回值 返回一个介于 0 和 1 之间的 Float32 数值。Float32 示例 不区分大小写的 4-gram 距离
Query
Response

ngramDistanceCaseInsensitiveUTF8

引入版本:v20.1.0 提供 ngramDistance 的不区分大小写 UTF-8 Variant。 假定 needle 和 haystack 字符串均为 UTF-8 编码,并忽略大小写。 计算两个 UTF-8 字符串之间不区分大小写的 3-gram 距离。 返回值越小,字符串越相似。 语法
参数
  • haystack — 第一个采用 UTF-8 编码的比较字符串。String
  • needle — 第二个采用 UTF-8 编码的比较字符串。String
返回值 返回一个介于 0 和 1 之间的 Float32 数值。Float32 示例 不区分大小写的 UTF-8 3-gram 距离
Query
Response

ngramDistanceUTF8

引入版本:v20.1.0 提供 ngramDistance 的 UTF-8 Variant。 假定 needle 和 haystack 字符串均为 UTF-8 编码。 计算两个 UTF-8 字符串之间的 3-gram 距离。 返回值越小,字符串越相似。 语法
参数
  • haystack — 第一个 UTF-8 编码的比较字符串。String
  • needle — 第二个 UTF-8 编码的比较字符串。String
返回值 返回 0 到 1 之间的 Float32 数值。Float32 示例 UTF-8 3-gram 距离
Query
Response

ngramSearch

引入版本:v20.1.0 检查两个字符串之间的 4-gram 距离是否小于或等于给定的阈值。 如需进行不区分大小写的搜索和/或使用 UTF8 格式,请使用函数 ngramSearchCaseInsensitive、ngramSearchUTF8、ngramSearchCaseInsensitiveUTF8。 语法
参数
  • haystack — 用于比较的字符串。String
  • needle — 用于比较的字符串。String
返回值 如果两个字符串之间的 4-gram 距离小于或等于阈值 (默认为 1.0) ,则返回 1;否则返回 0。UInt8 示例 使用 4-gram 进行搜索
Query
Response

ngramSearchCaseInsensitive

引入版本:v20.1.0 提供 ngramSearch 的不区分大小写 Variant。 计算 needle 字符串与 haystack 字符串之间的非对称差,即用 needle 中的 n-gram 数量减去共有的 n-gram 数量,再按 needle 的 n-gram 数量进行归一化。 检查两个字符串之间的 4-gram 距离是否小于或等于给定的阈值,并忽略大小写。 语法
参数
  • haystack — 用于比较的 String。String
  • needle — 用于比较的 String。String
返回值 如果两个字符串之间的 4-gram 距离小于或等于阈值 (默认值为 1.0) ,则返回 1;否则返回 0。UInt8 示例 使用 4-gram 的不区分大小写搜索
Query
Response

ngramSearchCaseInsensitiveUTF8

引入版本:v20.1.0 提供 ngramSearch 的不区分大小写 UTF-8 Variant。 假定 haystack 和 needle 为 UTF-8 字符串,并且不区分大小写。 检查两个 UTF-8 字符串之间的 3-gram 距离是否小于或等于给定阈值,且不区分大小写。 语法
参数
  • haystack — 用于比较的 UTF-8 字符串。String
  • needle — 用于比较的 UTF-8 字符串。String
返回值 如果两个字符串之间的 3-gram 距离小于或等于阈值 (默认为 1.0) ,则返回 1;否则返回 0。UInt8 示例 使用 3-gram 的不区分大小写 UTF-8 搜索
Query
Response

ngramSearchUTF8

引入版本:v20.1.0 提供 ngramSearch 的 UTF-8 Variant。 假定 haystack 和 needle 为 UTF-8 字符串。 检查两个 UTF-8 字符串之间的 3-gram 距离是否小于或等于给定阈值。 语法
参数
  • haystack — 用于比较的 UTF-8 字符串。String
  • needle — 用于比较的 UTF-8 字符串。String
返回值 如果两个字符串之间的 3-gram 距离小于或等于阈值 (默认为 1.0) ,则返回 1;否则返回 0。UInt8 示例 使用 3-gram 进行 UTF-8 搜索
Query
Response

notILike

引入版本:v20.6.0 检查字符串是否不匹配某个模式,且不区分大小写。该模式可包含用于 SQL LIKE 匹配的特殊字符 % 和 _。支持可选的 ESCAPE 子句 (参见 like) 。 语法
参数
  • haystack — 待搜索的输入字符串。String 或 FixedString
  • pattern — 要匹配的 SQL LIKE 模式。% 匹配任意数量的字符 (包括零个) ,_ 恰好匹配一个字符。String
  • escape_character — 可选的单字符字符串,用作转义字符来替代 \。默认值:\。String
返回值 如果字符串与模式不匹配 (不区分大小写) ,则返回 1,否则返回 0。UInt8 示例 用法示例
Query
Response

notLike

Introduced in:v1.1.0 与 like 类似,但会返回相反的结果。支持可选的 ESCAPE 子句 (参见 like) 。 语法
参数
  • haystack — 要在其中执行搜索的字符串。String 或 FixedString
  • pattern — 用于匹配的 LIKE 模式。String
  • escape_character — 可选的单字符字符串,用作转义字符,以替代 \。默认值:\。String
返回值 如果字符串与 LIKE 模式不匹配,则返回 1;否则返回 0。UInt8 示例 使用示例
Query
Response
不匹配的模式
Query
Response

notMatch

引入版本:v26.8.0 与 match 类似,但会对结果取反:检查字符串是否不匹配正则表达式模式。 此函数使用 RE2 正则表达式 库。支持的语法请参阅 re2。 可选的运算符语法:haystack !~ pattern (PostgreSQL 风格) 。 语法
参数
  • haystack — 在其中搜索模式的 String。String
  • pattern — 正则表达式模式。可以是常量,也可以来自列。String
返回值 如果匹配该模式,则返回 0,否则返回 1。UInt8 示例 使用示例
Query
Response

notMatchCaseInsensitive

引入版本:v26.8.0 与 matchCaseInsensitive 类似,但会对结果取反:检查字符串是否不与正则表达式模式进行不区分大小写的匹配。 此函数使用 RE2 正则表达式库。支持的语法请参阅 re2。 可选的运算符语法:haystack !~* pattern (PostgreSQL 风格) 。 语法
参数
  • haystack — 在其中搜索模式的 String。String
  • pattern — 正则表达式模式。可以是常量,也可以来自列。String
返回值 如果不区分大小写地匹配该模式,则返回 0,否则返回 1。UInt8 示例 使用示例
Query
Response

notSimilarTo

引入版本:v26.10.0 与 similarTo 类似,但对结果取反。 与 similarTo 一样,它支持可选的 ESCAPE 子句,用于指定自定义转义字符 (单个 ASCII 字符) 来替代默认的反斜杠。有关模式语法和转义规则,请参阅 similarTo。 语法
参数
  • haystack — 在其中执行搜索的字符串。String 或 FixedString
  • pattern — 用于匹配的 SIMILAR TO 模式。可包含 % (匹配任意数量的字符) 、_ (匹配单个字符) 、用于转义的 \,以及除 ^、$ 和 . 之外的正则表达式元字符;这三个字符在方括号表达式之外均按字面值处理 ([...] 内位于开头的 ^ 仍表示对字符类取反) 。String
  • escape_character — 可选,用于替代 \ 作为转义字符的单字符字符串。默认值:\。String
返回值 如果字符串与 SIMILAR TO 模式不匹配,则返回 1,否则返回 0。UInt8 示例 使用示例
Query
Response

position

引入版本:v1.1.0 返回子串 needle 在字符串 haystack 中的位置 (以字节为单位,从 1 开始计数) 。 如果子串 needle 为空,则适用以下规则:
  • 如果未指定 start_pos:返回 1
  • 如果 start_pos = 0:返回 1
  • 如果 start_pos >= 1 且 start_pos <= length(haystack) + 1:返回 start_pos
  • 否则:返回 0
同样的规则也适用于函数 locate、positionCaseInsensitive、positionUTF8 和 positionCaseInsensitiveUTF8。 语法
参数
  • haystack — 执行搜索的字符串。String 或 枚举
  • needle — 要搜索的子串。String
  • start_pos — haystack 中开始搜索的位置 (从 1 开始计数) 。可选。UInt
返回值 如果找到子串,则返回其起始位置 (以字节为单位,从 1 开始计数) ;如果未找到,则返回 0。UInt64 示例 基本用法
Query
Response
带有 start_pos 参数
Query
Response
Needle IN haystack 语法
Query
Response
空 needle 的子串
Query
Response

positionCaseInsensitive

引入版本:v1.1.0 与 position 类似,但不区分大小写。 语法
别名: instr 参数
  • haystack — 执行搜索的字符串。String 或 枚举
  • needle — 要搜索的子串。String
  • start_pos — 可选。haystack 中开始搜索的位置 (从 1 开始计数) 。UInt*
返回值 如果找到子串,则返回其起始位置 (以字节为单位,从 1 开始计数) ;如果未找到子串,则返回 0。UInt64 示例 不区分大小写的搜索
Query
Response

positionCaseInsensitiveUTF8

引入版本:v1.1.0 与 positionUTF8 类似,但按不区分大小写的方式搜索。 语法
参数
  • haystack — 执行搜索的字符串。String 或 枚举
  • needle — 要搜索的子串。String
  • start_pos — 可选。haystack 中开始搜索的位置 (从 1 开始) 。UInt*
返回值 如果找到子串,则返回其起始位置 (以字节为单位,从 1 开始计数) ;如果未找到,则返回 0。UInt64 示例 不区分大小写的 UTF-8 搜索
Query
Response

positionUTF8

引入版本:v1.1.0 与 position 类似,但假定 haystack 和 needle 为 UTF-8 编码的字符串。 语法
参数
  • haystack — 执行搜索的字符串。String 或 枚举
  • needle — 要搜索的子串。String
  • start_pos — 可选。haystack 中开始搜索的位置 (从 1 开始计数) 。UInt*
返回值 如果找到子串,则返回其起始位置 (以字节为单位,从 1 开始计数) ;如果未找到,则返回 0。UInt64 示例 按 UTF-8 字符计数
Query
Response

similarTo

引入版本:v26.10.0 返回字符串 haystack 是否与 SIMILAR TO 表达式 pattern 匹配。 SIMILAR TO 表达式可以包含普通字符以及以下元符号:
  • % 表示任意数量的任意字符 (包括零个字符) 。
  • _ 表示单个任意字符。
  • |、*、+、?、{、}、(、)、[ 和 ] 的含义与正则表达式中相同。
  • \ 用于转义上述任意字符及其自身。
正则表达式元字符 ^、$ 和 . 不属于 SIMILAR TO 语法, 在方括号表达式之外表示其对应的字面字符。在方括号表达式内部, 位于开头的 ^ 仍保持其常规含义,表示对字符类取反,例如 [^aeiou] 匹配单个 非元音字符。模式必须匹配整个 haystack,而不仅仅是其中的某个子串。

ESCAPE 子句

可选的 ESCAPE 子句用于指定自定义转义字符 (必须是单个 ASCII 字符) 。 指定后,自定义转义字符将取代默认的反斜杠,用于转义上面列出的 元符号,此时反斜杠失去特殊含义 (即被视为 字面字符) 。 自定义转义字符之后只能紧跟 SIMILAR TO 特殊字符 (%、_、|、*、+、 ?、{、}、(、)、[、]) 或其自身;后跟任何其他字符 (包括 ^、$、. 以及反斜杠, 这些字符在方括号表达式之外均为普通字符) 都会报错,因为对 普通字符进行转义没有任何作用。这种严格性 仅适用于自定义转义字符:默认的反斜杠沿用旧版 LIKE 的行为, 位于普通字符之前时表示字面反斜杠。因此,'\\mabc' SIMILAR TO '%\\mabc%' 返回 1,而 'mabc' SIMILAR TO '%#mabc%' ESCAPE '#' 会被拒绝。在方括号 表达式 (如 [...]) 内部,转义字符不具有特殊含义,仅表示其自身,这与 POSIX 和 PostgreSQL 的行为一致。 语法
参数
  • haystack — 要在其中执行搜索的字符串。String 或 FixedString
  • pattern — 用于匹配的 SIMILAR TO 模式。可以包含 % (匹配任意数量的字符) 、_ (匹配单个字符) 、用于转义的 \,以及除 ^、$ 和 . 之外的正则表达式元字符;这三个字符在方括号表达式之外均按字面值处理 ([...] 内开头的 ^ 仍表示对字符类取反) 。String
  • escape_character — 可选,单字符字符串,用作转义字符以代替 \。默认值:\。String
返回值 如果字符串与 SIMILAR TO 模式匹配,则返回 1,否则返回 0。UInt8 示例 使用示例
Query
Response