> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> 字符串搜索函数文档
# 字符串搜索函数
本节中的所有函数默认都执行区分大小写的搜索。不区分大小写的搜索通常由单独的函数变体提供。
不区分大小写的搜索遵循英语的大小写转换规则。例如，英语中的小写 `i` 的大写形式是
`I`，而土耳其语中则是 `İ`——对于英语以外的语言，结果可能不符合预期。
本节中的函数还假定被搜索的字符串 (本节中称为 `haystack`) 和搜索字符串 (本节中称为 `needle`) 都是单字节编码文本。如果这一假设
不成立，不会抛出异常，结果未定义。对 UTF-8 编码字符串的搜索通常由单独的函数
变体提供。同样，如果使用 UTF-8 函数变体，而输入字符串并非 UTF-8 编码文本，也不会抛出异常，且
结果未定义。请注意，不会自动执行 Unicode 规范化，不过你可以使用
[normalizeUTF8\*()](/zh/reference/functions/regular-functions/string-functions#normalizeUTF8NFC) 函数来实现这一点。
[通用字符串函数](/zh/reference/functions/regular-functions/string-functions) 和 [字符串替换函数](/zh/reference/functions/regular-functions/string-replace-functions) 将单独介绍。
以下文档由 `system.functions` 系统表生成。
{/*AUTOGENERATED_START*/}
## countMatches
引入版本：v21.1.0
返回字符串中正则表达式的匹配次数。
**与版本相关的行为**
此函数的行为取决于 ClickHouse 版本：
* 在 \< v25.6 的版本中，即使模式能够匹配空字符串，函数也会在第一次空匹配时停止计数。
* 在 >= 25.6 的版本中，发生空匹配时，函数会继续执行。可使用设置 `count_matches_stop_at_empty_match = true` 恢复旧版行为；
**语法**
```sql theme={null}
countMatches(haystack, pattern)
```
**参数**
* `haystack` — 要搜索的字符串。[`String`](/zh/reference/data-types/string)
* `pattern` — 正则表达式模式。[`String`](/zh/reference/data-types/string)
**返回值**
返回找到的匹配项数量。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**统计数字串的数量**
```sql title=Query theme={null}
SELECT countMatches('hello 123 world 456 test', '[0-9]+')
```
```response title=Response theme={null}
┌─countMatches('hello 123 world 456 test', '[0-9]+')─┐
│ 2 │
└─────────────────────────────────────────────────────┘
```
## countMatchesCaseInsensitive
引入版本：v21.1.0
与 [`countMatches`](#countMatches) 类似，但执行不区分大小写的匹配。
**语法**
```sql theme={null}
countMatchesCaseInsensitive(haystack, pattern)
```
**参数**
* `haystack` — 要在其中搜索的字符串。[`String`](/zh/reference/data-types/string)
* `pattern` — 正则表达式模式。[`const String`](/zh/reference/data-types/string)
**返回值**
返回找到的匹配次数。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**不区分大小写的计数**
```sql title=Query theme={null}
SELECT countMatchesCaseInsensitive('Hello HELLO world', 'hello')
```
```response title=Response theme={null}
┌─countMatchesCaseInsensitive('Hello HELLO world', 'hello')─┐
│ 2 │
└───────────────────────────────────────────────────────────┘
```
## countSubstrings
引入版本：v21.1.0
返回子串 `needle` 在字符串 `haystack` 中出现的频次。
**语法**
```sql theme={null}
countSubstrings(haystack, needle[, start_pos])
```
**参数**
* `haystack` — 要在其中执行搜索的 String。[String](/zh/reference/data-types/string) 或 [枚举](/zh/reference/data-types/enum)。 - `needle` — 要搜索的子串。[String](/zh/reference/data-types/string)。 - `start_pos` — 在 `haystack` 中开始搜索的位置 (从 1 开始计数) 。[UInt](/zh/reference/data-types/int-uint)。可选。
**返回值**
出现的次数。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT countSubstrings('aaaa', 'aa');
```
```response title=Response theme={null}
┌─countSubstrings('aaaa', 'aa')─┐
│ 2 │
└───────────────────────────────┘
```
**使用 start\_pos 参数**
```sql title=Query theme={null}
SELECT countSubstrings('abc___abc', 'abc', 4);
```
```response title=Response theme={null}
┌─countSubstrings('abc___abc', 'abc', 4)─┐
│ 1 │
└────────────────────────────────────────┘
```
## countSubstringsCaseInsensitive
引入版本：v21.1.0
与 [`countSubstrings`](#countSubstrings) 类似，但按不区分大小写的方式计数。
**语法**
```sql theme={null}
countSubstringsCaseInsensitive(haystack, needle[, start_pos])
```
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string) 或 [`枚举`](/zh/reference/data-types/enum)
* `needle` — 要搜索的子串。[`String`](/zh/reference/data-types/string)
* `start_pos` — 可选。在 `haystack` 中开始搜索的位置 (从 1 开始计数) 。[`UInt*`](/zh/reference/data-types/int-uint)
**返回值**
返回 `needle` 在 `haystack` 中出现的次数。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT countSubstringsCaseInsensitive('AAAA', 'aa');
```
```response title=Response theme={null}
┌─countSubstri⋯AAA', 'aa')─┐
│ 2 │
└──────────────────────────┘
```
**使用 start\_pos 参数**
```sql title=Query theme={null}
SELECT countSubstringsCaseInsensitive('abc___ABC___abc', 'abc', 4);
```
```response title=Response theme={null}
┌─countSubstri⋯, 'abc', 4)─┐
│ 2 │
└──────────────────────────┘
```
## countSubstringsCaseInsensitiveUTF8
Introduced in: v21.1.0
与 [`countSubstrings`](#countSubstrings) 类似，但以不区分大小写的方式进行计数，并假定 haystack 为 UTF-8 字符串。
**Syntax**
```sql theme={null}
countSubstringsCaseInsensitiveUTF8(haystack, needle[, start_pos])
```
**参数**
* `haystack` — 执行搜索的 UTF-8 字符串。[`String`](/zh/reference/data-types/string) 或 [`枚举`](/zh/reference/data-types/enum)
* `needle` — 要搜索的子串。[`String`](/zh/reference/data-types/string)
* `start_pos` — 可选。在 `haystack` 中开始搜索的位置 (从 1 开始) 。[`UInt*`](/zh/reference/data-types/int-uint)
**返回值**
返回 `needle` 在 `haystack` 中出现的次数。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT countSubstringsCaseInsensitiveUTF8('ложка, кошка, картошка', 'КА');
```
```response title=Response theme={null}
┌─countSubstri⋯шка', 'КА')─┐
│ 4 │
└──────────────────────────┘
```
**使用 start\_pos 参数**
```sql title=Query theme={null}
SELECT countSubstringsCaseInsensitiveUTF8('ложка, кошка, картошка', 'КА', 13);
```
```response title=Response theme={null}
┌─countSubstri⋯, 'КА', 13)─┐
│ 2 │
└──────────────────────────┘
```
Introduced in：v1.1.0
提取字符串中第一个匹配正则表达式的内容。
如果 'haystack' 与 'pattern' 不匹配，则返回空字符串。
此函数使用 RE2 regular expression 库。支持的语法请参阅 [re2](https://github.com/google/re2/wiki/Syntax)。
如果正则表达式包含 capturing group (子模式) ，则函数会返回输入字符串中与第一个 capturing group 匹配的内容。
**Syntax**
```sql theme={null}
extract(haystack, pattern)
```
**参数**
* `haystack` — 要从中提取内容的 String。[`String`](/zh/reference/data-types/string)
* `pattern` — 正则表达式，通常包含一个捕获组。[`const String`](/zh/reference/data-types/string)
**返回值**
返回提取出的字符串片段。[`String`](/zh/reference/data-types/string)
**示例**
**从电子邮件地址中提取域名**
```sql title=Query theme={null}
SELECT extract('test@clickhouse.com', '.*@(.*)$')
```
```response title=Response theme={null}
┌─extract('test@clickhouse.com', '.*@(.*)$')─┐
│ clickhouse.com │
└───────────────────────────────────────────┘
```
**未匹配时返回空字符串**
```sql title=Query theme={null}
SELECT extract('test@clickhouse.com', 'no_match')
```
```response title=Response theme={null}
┌─extract('test@clickhouse.com', 'no_match')─┐
│ │
└────────────────────────────────────────────┘
```
引入于：v1.1.0
与 [`extract`](#extract) 类似，但返回字符串中匹配正则表达式的所有结果组成的数组。
如果 'haystack' 不匹配 'pattern' 正则表达式，则返回空数组。
如果正则表达式包含捕获组 (子模式) ，则该函数会针对第一个捕获组匹配输入字符串。
**语法**
```sql theme={null}
extractAll(haystack, pattern)
```
**参数**
* `haystack` — 要从中提取片段的 String。[`String`](/zh/reference/data-types/string)
* `pattern` — 正则表达式，可包含捕获组。[`const String`](/zh/reference/data-types/string)
**返回值**
返回提取出的片段数组。[`Array(String)`](/zh/reference/data-types/array)
**示例**
**提取所有数字**
```sql title=Query theme={null}
SELECT extractAll('hello 123 world 456', '[0-9]+')
```
```response title=Response theme={null}
┌─extractAll('hello 123 world 456', '[0-9]+')─┐
│ ['123','456'] │
└─────────────────────────────────────────────┘
```
**使用捕获组提取**
```sql title=Query theme={null}
SELECT extractAll('test@example.com, user@domain.org', '([a-zA-Z0-9]+)@')
```
```response title=Response theme={null}
┌─extractAll('test@example.com, user@domain.org', '([a-zA-Z0-9]+)@')─┐
│ ['test','user'] │
└────────────────────────────────────────────────────────────────────┘
```
引入版本：v20.5.0
使用提供的正则表达式匹配字符串中的所有组，并返回一个嵌套数组，其中每个数组包含同一捕获组的所有捕获结果，按组号排列。
**语法**
```sql theme={null}
extractAllGroupsHorizontal(s, regexp)
```
**参数**
* `s` — 要从中提取内容的输入字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `regexp` — 用于匹配的正则表达式。[`const String`](/zh/reference/data-types/string) 或 [`const FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回一个嵌套数组，其中每个内部数组都包含某个捕获组在所有匹配结果中的全部捕获内容。第一个内部数组包含第 1 组的所有捕获，第二个包含第 2 组的所有捕获，依此类推。如果未找到匹配项，则返回空数组。[`Array(Array(String))`](/zh/reference/data-types/array)
**示例**
**用法示例**
```sql title=Query theme={null}
WITH '< Server: nginx
< Date: Tue, 22 Jan 2019 00:26:14 GMT
< Content-Type: text/html; charset=UTF-8
< Connection: keep-alive
' AS s
SELECT extractAllGroupsHorizontal(s, '< ([\\w\\-]+): ([^\\r\\n]+)');
```
```response title=Response theme={null}
[['Server','Date','Content-Type','Connection'],['nginx','Tue, 22 Jan 2019 00:26:14 GMT','text/html; charset=UTF-8','keep-alive']]
```
Introduced in: v20.5.0
从正则表达式匹配到的第一个子串中提取捕获组。要从所有匹配结果中提取捕获组，请使用 [`extractAllGroupsHorizontal`](#extractAllGroupsHorizontal) 或 [`extractAllGroupsVertical`](/zh/reference/functions/regular-functions/splitting-merging-functions#extractAllGroupsVertical)。
**Syntax**
```sql theme={null}
extractGroups(s, regexp)
```
**参数**
* `s` — 要从中提取内容的输入字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `regexp` — 正则表达式。必须至少包含一个捕获组。常量。[`const String`](/zh/reference/data-types/string) 或 [`const FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
如果正则表达式匹配，则返回一个数组，包含首次匹配中捕获的各组 (`1` 到 `N`，其中 `N` 为 `regexp` 中捕获组的数量) 。如果没有匹配，则返回空数组。[`Array(String)`](/zh/reference/data-types/array)
**示例**
**使用示例**
```sql title=Query theme={null}
WITH '< Server: nginx
< Date: Tue, 22 Jan 2019 00:26:14 GMT
< Content-Type: text/html; charset=UTF-8
< Connection: keep-alive
' AS s
SELECT extractGroups(s, '< ([\\w\\-]+): ([^\\r\\n]+)');
```
```response title=Response theme={null}
['Server','nginx']
```
## hasAllTokens
引入版本：v25.10.0
与 [`hasAnyTokens`](#hasAnyTokens) 类似，但仅当 `needle` 字符串或数组中的所有标记都与 `input` 字符串匹配时返回 1，否则返回 0。如果 `input` 是一列，则返回满足此条件的所有行。
为获得最佳性能，列 `input` 应定义一个[文本索引](/zh/reference/engines/table-engines/mergetree-family/textindexes)。
如果未定义文本索引，该函数会对该列执行暴力扫描，其速度比索引查找慢几个数量级。
在搜索之前，该函数会对文本进行标记化处理
* `input` 参数 (始终如此) 以及
* `needle` 参数 (如果为 [String](/zh/reference/data-types/string))
会使用为文本索引指定的分词器进行处理。
如果该列未定义文本索引，则会改用 `splitByNonAlpha` 分词器。
如果 `needle` 参数的类型为 [Array(String)](/zh/reference/data-types/array)，则数组中的每个元素都会被视为一个标记——不会再进行额外的分词。
重复的标记将被忽略。
例如，needles = \['ClickHouse', 'ClickHouse'] 与 \['ClickHouse'] 等效。
**语法**
```sql theme={null}
hasAllTokens(input, needles)
```
**别名**: `hasAllToken`
**参数**
* `input` — 输入列。[`String`](/zh/reference/data-types/string)、[`FixedString`](/zh/reference/data-types/fixedstring)、[`Array(String)`](/zh/reference/data-types/array) 或 [`Array(FixedString)`](/zh/reference/data-types/array)
* `needles` — 待搜索的标记。[`String`](/zh/reference/data-types/string) 或 [`Array(String)`](/zh/reference/data-types/array)
* `tokenizer` — 使用的分词器。有效参数包括 `splitByNonAlpha`、`splitByString`、`asciiCJK`、`ngrams`、`sparseGrams` 和 `array`。可选；如果未显式设置，默认为 `splitByNonAlpha`。[`const String`](/zh/reference/data-types/string)
**返回值**
如果所有 needle 都匹配，则返回 1；否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用字符串 needle 的基本用法**
```sql title=Query theme={null}
CREATE TABLE table (
id UInt32,
msg String,
INDEX idx(msg) TYPE text(tokenizer = splitByString(['()', '\\']))
)
ENGINE = MergeTree
ORDER BY id;
INSERT INTO table VALUES (1, '()a,\\bc()d'), (2, '()\\a()bc\\d'), (3, ',()a\\,bc,(),d,');
SELECT count() FROM table WHERE hasAllTokens(msg, 'a\\d()');
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**指定要在数组中按原样搜索的 needle (不进行标记化) **
```sql title=Query theme={null}
SELECT count() FROM table WHERE hasAllTokens(msg, ['a', 'd']);
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**使用 `tokens` 函数生成 needle**
```sql title=Query theme={null}
SELECT count() FROM table WHERE hasAllTokens(msg, tokens('a()d', 'splitByString', ['()', '\\']));
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**通过第三个参数使用自定义分词器**
```sql title=Query theme={null}
SELECT hasAllTokens('abcdef', 'abc', 'ngrams(3)');
```
```response title=Response theme={null}
┌─hasAllTokens('abcdef', 'abc', 'ngrams(3)')─┐
│ 1 │
└──────────────────────────────────────────────┘
```
**Array 和 Map 列的使用示例**
```sql title=Query theme={null}
CREATE TABLE log (
id UInt32,
tags Array(String),
attributes Map(String, String),
INDEX idx_tags (tags) TYPE text(tokenizer = splitByNonAlpha),
INDEX idx_attributes_keys mapKeys(attributes) TYPE text(tokenizer = array),
INDEX idx_attributes_vals mapValues(attributes) TYPE text(tokenizer = array)
)
ENGINE = MergeTree
ORDER BY id;
INSERT INTO log VALUES
(1, ['clickhouse', 'clickhouse cloud'], {'address': '192.0.0.1', 'log_level': 'INFO'}),
(2, ['chdb'], {'embedded': 'true', 'log_level': 'DEBUG'});
```
```response title=Response theme={null}
```
**数组列示例**
```sql title=Query theme={null}
SELECT count() FROM log WHERE hasAllTokens(tags, 'clickhouse');
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**mapKeys 示例**
```sql title=Query theme={null}
SELECT count() FROM log WHERE hasAllTokens(mapKeys(attributes), ['address', 'log_level']);
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**mapValues 示例**
```sql title=Query theme={null}
SELECT count() FROM log WHERE hasAllTokens(mapValues(attributes), ['192.0.0.1', 'DEBUG']);
```
```response title=Response theme={null}
┌─count()─┐
│ 0 │
└─────────┘
```
## hasAnyTokens
引入版本：v25.10.0
如果 `needle` 字符串或数组中至少有一个标记与 `input` 字符串匹配，则返回 1，否则返回 0。如果 `input` 是一列，则返回满足此条件的所有行。
列 `input` 应定义 [文本索引](/zh/reference/engines/table-engines/mergetree-family/textindexes)，以获得最佳性能。
如果未定义文本索引，该函数会对列执行暴力扫描，其速度比索引查找慢几个数量级。
在搜索之前，该函数会对文本进行标记化处理
* `input` 参数 (始终如此) ，以及
* `needle` 参数 (如果其类型为 [String](/zh/reference/data-types/string))
会使用为文本索引指定的分词器进行分词。
如果该列未定义文本索引，则会改用 `splitByNonAlpha` 分词器。
如果 `needle` 参数的类型为 [Array(String)](/zh/reference/data-types/array)，则会将数组中的每个元素视为一个标记——不会再进行额外分词。
重复的标记将被忽略。
例如，\['ClickHouse', 'ClickHouse'] 与 \['ClickHouse'] 的处理方式相同。
**语法**
```sql theme={null}
hasAnyTokens(input, needles)
```
**别名**: `hasAnyToken`
**参数**
* `input` — 输入列。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring) 或 [`Nullable(String)`](/zh/reference/data-types/nullable) 或 [`Nullable(FixedString)`](/zh/reference/data-types/nullable) 或 [`Array(String)`](/zh/reference/data-types/array) 或 [`Array(FixedString)`](/zh/reference/data-types/array) 或 [`Array(Nullable(String))`](/zh/reference/data-types/array) 或 [`Array(Nullable(FixedString))`](/zh/reference/data-types/array)
* `needles` — 待搜索的标记。[`String`](/zh/reference/data-types/string) 或 [`Array(String)`](/zh/reference/data-types/array)
* `tokenizer` — 使用的分词器。有效参数包括 `splitByNonAlpha`、`splitByString`、`asciiCJK`、`ngrams`、`sparseGrams` 和 `array`。该参数为可选项；如果未显式设置，则默认为 `splitByNonAlpha`。[`const String`](/zh/reference/data-types/string)
**返回值**
如果至少有一个匹配项，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用字符串 needle 的基本示例**
```sql title=Query theme={null}
CREATE TABLE table (
id UInt32,
msg String,
INDEX idx(msg) TYPE text(tokenizer = splitByString(['()', '\\']))
)
ENGINE = MergeTree
ORDER BY id;
INSERT INTO table VALUES (1, '()a,\\bc()d'), (2, '()\\a()bc\\d'), (3, ',()a\\,bc,(),d,');
SELECT count() FROM table WHERE hasAnyTokens(msg, 'a\\d()');
```
```response title=Response theme={null}
┌─count()─┐
│ 3 │
└─────────┘
```
**指定要在数组中按原样搜索的 needle (不进行标记化) **
```sql title=Query theme={null}
SELECT count() FROM table WHERE hasAnyTokens(msg, ['a', 'd']);
```
```response title=Response theme={null}
┌─count()─┐
│ 3 │
└─────────┘
```
**使用 `tokens` 函数生成 needle**
```sql title=Query theme={null}
SELECT count() FROM table WHERE hasAnyTokens(msg, tokens('a()d', 'splitByString', ['()', '\\']));
```
```response title=Response theme={null}
┌─count()─┐
│ 3 │
└─────────┘
```
**数组和 map 列的使用示例**
```sql title=Query theme={null}
CREATE TABLE log (
id UInt32,
tags Array(String),
attributes Map(String, String),
INDEX idx_tags (tags) TYPE text(tokenizer = splitByNonAlpha),
INDEX idx_attributes_keys mapKeys(attributes) TYPE text(tokenizer = array),
INDEX idx_attributes_vals mapValues(attributes) TYPE text(tokenizer = array)
)
ENGINE = MergeTree
ORDER BY id;
INSERT INTO log VALUES
(1, ['clickhouse', 'clickhouse cloud'], {'address': '192.0.0.1', 'log_level': 'INFO'}),
(2, ['chdb'], {'embedded': 'true', 'log_level': 'DEBUG'});
```
```response title=Response theme={null}
```
**数组列示例**
```sql title=Query theme={null}
SELECT count() FROM log WHERE hasAnyTokens(tags, 'clickhouse');
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**mapKeys 示例**
```sql title=Query theme={null}
SELECT count() FROM log WHERE hasAnyTokens(mapKeys(attributes), ['address', 'log_level']);
```
```response title=Response theme={null}
┌─count()─┐
│ 2 │
└─────────┘
```
**mapValues 示例**
```sql title=Query theme={null}
SELECT count() FROM log WHERE hasAnyTokens(mapValues(attributes), ['192.0.0.1', 'DEBUG']);
```
```response title=Response theme={null}
┌─count()─┐
│ 2 │
└─────────┘
```
## hasPhrase
引入版本：v26.4.0
检查 haystack 是否按连续顺序包含短语中的所有标记。
搜索前，该函数会使用可选的第三个参数指定的分词器，对 `input` 和 `phrase` 参数进行分词。
`tokenizer` 参数必须是 `splitByNonAlpha`、`splitByString`、`ngrams` 或 `asciiCJK` 之一。
如果未指定分词器，则默认使用 `splitByNonAlpha` 分词器。
与 [`hasToken`](#hasToken)、[`hasAnyTokens`](#hasAnyTokens) 和 [`hasAllTokens`](#hasAllTokens) 不同，`hasPhrase` 要求这些标记按相同顺序连续出现，
中间不能有任何其他标记。例如，`hasPhrase('the quick brown fox', 'quick fox')` 返回 0，
因为 "brown" 出现在 "quick" 和 "fox" 之间。
**语法**
```sql theme={null}
hasPhrase(input, phrase[, tokenizer])
```
**别名**：`matchPhrase`
**参数**
* `input` — 输入列。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `phrase` — 要搜索的短语。[`const String`](/zh/reference/data-types/string)
* `tokenizer` — 使用的分词器。可选，默认为 `splitByNonAlpha`。[`const String`](/zh/reference/data-types/string)
**返回值**
如果找到该短语对应的连续标记序列，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**短语匹配**
```sql title=Query theme={null}
SELECT hasPhrase('the quick brown fox jumps', 'quick brown')
```
```response title=Response theme={null}
┌─hasPhrase('the quick brown fox jumps', 'quick brown')─┐
│ 1 │
└────────────────────────────────────────────────────────┘
```
**不连续标记**
```sql title=Query theme={null}
SELECT hasPhrase('the quick brown fox jumps', 'quick fox')
```
```response title=Response theme={null}
┌─hasPhrase('the quick brown fox jumps', 'quick fox')─┐
│ 0 │
└──────────────────────────────────────────────────────┘
```
## hasSubsequence
Introduced in: v23.7.0
检查 needle 是否是 haystack 的子序列。
字符串的子序列，是指在不改变其余字符顺序的前提下，通过删除另一个字符串中的部分字符或不删除任何字符得到的序列。
**Syntax**
```sql theme={null}
hasSubsequence(haystack, needle)
```
**参数**
* `haystack` — 在其中搜索子序列的 String。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的子序列。[`String`](/zh/reference/data-types/string)
**返回值**
如果 needle 是 haystack 的子序列，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**基本的子序列检查**
```sql title=Query theme={null}
SELECT hasSubsequence('Hello World', 'HlWrd')
```
```response title=Response theme={null}
┌─hasSubsequence('Hello World', 'HlWrd')─┐
│ 1 │
└────────────────────────────────────────┘
```
**未找到子序列**
```sql title=Query theme={null}
SELECT hasSubsequence('Hello World', 'xyz')
```
```response title=Response theme={null}
┌─hasSubsequence('Hello World', 'xyz')─┐
│ 0 │
└──────────────────────────────────────┘
```
## hasSubsequenceCaseInsensitive
引入版本：v23.7.0
与 [`hasSubsequence`](#hasSubsequence) 类似，但搜索时不区分大小写。
**语法**
```sql theme={null}
hasSubsequenceCaseInsensitive(haystack, needle)
```
**参数**
* `haystack` — 在其中执行搜索的 String。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的子序列。[`String`](/zh/reference/data-types/string)
**返回值**
如果 needle 是 haystack 的子序列，则返回 1，否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT hasSubsequenceCaseInsensitive('garbage', 'ARG');
```
```response title=Response theme={null}
┌─hasSubsequenceCaseInsensitive('garbage', 'ARG')─┐
│ 1 │
└─────────────────────────────────────────────────┘
```
## hasSubsequenceCaseInsensitiveUTF8
引入版本：v23.7.0
与 [`hasSubsequenceUTF8`](#hasSubsequenceUTF8) 类似，但搜索时不区分大小写。
**语法**
```sql theme={null}
hasSubsequenceCaseInsensitiveUTF8(haystack, needle)
```
**参数**
* `haystack` — 执行搜索所在的 UTF8 编码字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的 UTF8 编码子序列字符串。[`String`](/zh/reference/data-types/string)
**返回值**
如果 `needle` 是 `haystack` 的子序列，则返回 1；否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT hasSubsequenceCaseInsensitiveUTF8('ClickHouse - столбцовая система управления базами данных', 'СИСТЕМА');
```
```response title=Response theme={null}
┌─hasSubsequen⋯ 'СИСТЕМА')─┐
│ 1 │
└──────────────────────────┘
```
## hasSubsequenceUTF8
引入版本：v23.7.0
与 [`hasSubsequence`](/zh/reference/functions/regular-functions/string-search-functions#hasSubsequence) 类似，但假设 haystack 和 needle 是以 UTF-8 编码的字符串。
**语法**
```sql theme={null}
hasSubsequenceUTF8(haystack, needle)
```
**参数**
* `haystack` — 要在其中进行搜索的字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 要查找的子序列。[`String`](/zh/reference/data-types/string)
**返回值**
如果 `needle` 是 `haystack` 的子序列，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT hasSubsequenceUTF8('картошка', 'кошка');
```
```response title=Response theme={null}
┌─hasSubsequen⋯', 'кошка')─┐
│ 1 │
└──────────────────────────┘
```
**不匹配子序列**
```sql title=Query theme={null}
SELECT hasSubsequenceUTF8('картошка', 'апельсин');
```
```response title=Response theme={null}
┌─hasSubsequen⋯'апельсин')─┐
│ 0 │
└──────────────────────────┘
```
## hasToken
引入版本：v20.1.0
检查给定的标记是否存在于 haystack 中。
使用 [splitByNonAlpha](/zh/reference/functions/regular-functions/splitting-merging-functions#splitByNonAlpha) 作为分词器，也就是说，标记被定义为由连续字符 `[0-9A-Za-z_]` (数字、ASCII 字符和下划线) 构成的最长子序列。
**语法**
```sql theme={null}
hasToken(haystack, token)
```
**参数**
* `haystack` — 被搜索的字符串。[`String`](/zh/reference/data-types/string)
* `token` — 要查找的标记。[`const String`](/zh/reference/data-types/string)
**返回值**
如果找到该标记，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**标记搜索**
```sql title=Query theme={null}
SELECT hasToken('clickhouse test', 'test')
```
```response title=Response theme={null}
┌─hasToken('clickhouse test', 'test')─┐
│ 1 │
└─────────────────────────────────────┘
```
## hasTokenCaseInsensitive
引入版本：v20.1.0
使用 tokenbf\_v1 索引在 haystack 中执行对 needle 的不区分大小写查找。
**语法**
```sql theme={null}
hasTokenCaseInsensitive(haystack, needle)
```
**参数**
* 无。
**返回值**
**示例**
## hasTokenCaseInsensitiveOrNull
引入版本：v23.1.0
使用 tokenbf\_v1 索引在 haystack 中不区分大小写地查找 needle。如果 needle 的格式不合法，则返回 NULL。
**语法**
```sql theme={null}
hasTokenCaseInsensitiveOrNull(haystack, needle)
```
**参数**
* 无。
**返回值**
**示例**
## hasTokenOrNull
首次引入版本：v20.1.0
与 [`hasToken`](#hasToken) 类似，但如果标记格式不合法，则返回 NULL。
**语法**
```sql theme={null}
hasTokenOrNull(haystack, token)
```
**参数**
* `haystack` — 要搜索的字符串。必须为常量。[`String`](/zh/reference/data-types/string)
* `token` — 要搜索的标记。[`const String`](/zh/reference/data-types/string)
**返回值**
如果找到该标记，则返回 `1`；否则返回 `0`。如果 `token` 格式不正确，则返回 NULL。[`Nullable(UInt8)`](/zh/reference/data-types/nullable)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT hasTokenOrNull('apple banana cherry', 'ban ana');
```
```response title=Response theme={null}
┌─hasTokenOrNu⋯ 'ban ana')─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────┘
```
## highlight
引入版本：v26.4.0
使用 HTML 标签包裹文本字符串中搜索词的匹配项，从而将其高亮显示。
该函数执行 ASCII 不区分大小写匹配。如果多个搜索词在文本中重叠或彼此相邻，则匹配区域会合并为一个高亮 span。
**语法**
```sql theme={null}
highlight(haystack, needles[, open_tag, close_tag])
```
**参数**
* `haystack` — 要搜索的文本。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `needles` — 要高亮显示的搜索词数组。[`const Array(String)`](/zh/reference/data-types/array)
* `open_tag` — 在每个匹配项前插入的起始标签。默认值：``。[`const String`](/zh/reference/data-types/string)
* `close_tag` — 在每个匹配项后插入的结束标签。默认值：``。[`const String`](/zh/reference/data-types/string)
**返回值**
返回将匹配词用指定标签包裹后的输入文本。[`String`](/zh/reference/data-types/string)
**示例**
**基本高亮**
```sql title=Query theme={null}
SELECT highlight('The quick brown fox', ['quick', 'fox'])
```
```response title=Response theme={null}
┌─highlight('The quick brown fox', ['quick', 'fox'])─┐
│ The quick brown fox │
└────────────────────────────────────────────────────┘
```
**自定义标签**
```sql title=Query theme={null}
SELECT highlight('Hello World', ['hello'], '', '')
```
```response title=Response theme={null}
┌─highlight('Hello World', ['hello'], '', '')─┐
│ Hello World │
└────────────────────────────────────────────────────┘
```
## ilike
引入版本：v20.6.0
与 [`like`](#like) 类似，但以不区分大小写的方式进行搜索。
**语法**
```sql theme={null}
ilike(haystack, pattern)
-- haystack ILIKE pattern（不区分大小写）
```
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `pattern` — 用于匹配的 LIKE 模式。[`String`](/zh/reference/data-types/string)
**返回值**
如果字符串与 LIKE 模式匹配 (不区分大小写) ，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT ilike('ClickHouse', '%house%');
```
```response title=Response theme={null}
┌─ilike('ClickHouse', '%house%')─┐
│ 1 │
└────────────────────────────────┘
```
## like
引入版本：v1.1.0
返回字符串 `haystack` 是否匹配 `LIKE` 表达式 `pattern`。
`LIKE` 表达式可以包含普通字符以及以下元符号：
* `%` 表示任意数量的任意字符 (包括零个字符) 。
* `_` 表示任意单个字符。
* `\` 用于转义字面量 `%`、`_` 和 `\`。
匹配基于 UTF-8，例如，`_` 可以匹配 Unicode 码点 `¥`，该字符在 UTF-8 中用两个字节表示。
如果 haystack 或 `LIKE` 表达式不是有效的 UTF-8，则其行为未定义。
不会自动执行 Unicode 规范化；你可以使用 `normalizeUTF8*` 函数来完成此操作。
要匹配字面量 `%`、`_` 和 `\` (它们是 `LIKE` 元字符) ，请在它们前面加上反斜杠：`\%`、`\_` 和 `\\`。
如果反斜杠后面的字符不是 `%`、`_` 或 `\`，则反斜杠会失去其特殊含义 (即按字面量解释) 。
ClickHouse 要求字符串中的反斜杠[也需要转义](/zh/reference/syntax#string)，因此实际需要写成 `\\%`、`\\_` 和 `\\\\`。
对于形如 `%needle%` 的 `LIKE` 表达式，该函数的速度与 `position` 函数一样快。
所有其他 `LIKE` 表达式在内部都会转换为正则表达式，并以与 `match` 函数相近的性能执行。
**语法**
```sql theme={null}
like(haystack, pattern)
-- haystack LIKE pattern
```
**参数**
* `haystack` — 要在其中执行搜索的 String。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `pattern` — 要匹配的 `LIKE` 模式。可包含 `%` (匹配任意数量的字符) 、`_` (匹配单个字符) 以及用于转义的 `\`。[`String`](/zh/reference/data-types/string)
**返回值**
如果字符串与 `LIKE` 模式匹配，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT like('ClickHouse', '%House');
```
```response title=Response theme={null}
┌─like('ClickHouse', '%House')─┐
│ 1 │
└──────────────────────────────┘
```
**单字符通配符**
```sql title=Query theme={null}
SELECT like('ClickHouse', 'Click_ouse');
```
```response title=Response theme={null}
┌─like('ClickH⋯lick_ouse')─┐
│ 1 │
└──────────────────────────┘
```
**不匹配模式**
```sql title=Query theme={null}
SELECT like('ClickHouse', '%SQL%');
```
```response title=Response theme={null}
┌─like('ClickHouse', '%SQL%')─┐
│ 0 │
└─────────────────────────────┘
```
## locate
引入版本：v18.16.0
与 [`position`](#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` 恢复之前的行为。
**语法**
```sql theme={null}
locate(needle, haystack[, start_pos])
```
**参数**
* `needle` — 要搜索的子串。[`String`](/zh/reference/data-types/string)
* `haystack` — 要在其中进行搜索的字符串。[`String`](/zh/reference/data-types/string) 或 [`Enum`](/zh/reference/data-types/enum)
* `start_pos` — 可选。在 `haystack` 中开始搜索的位置 (从 1 开始计数) 。[`UInt`](/zh/reference/data-types/int-uint)
**返回值**
如果找到子串，则返回其起始位置 (按字节计数，且从 1 开始) ；如果未找到子串，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**基本用法**
```sql title=Query theme={null}
SELECT locate('ca', 'abcabc')
```
```response title=Response theme={null}
┌─locate('ca', 'abcabc')─┐
│ 3 │
└────────────────────────┘
```
## match
引入版本：v1.1.0
检查给定字符串是否与指定的 正则表达式 模式 匹配。
此函数使用 RE2 正则表达式 库。支持的语法请参阅 [re2](https://github.com/google/re2/wiki/Syntax)。
匹配基于 UTF-8 假设进行，例如 `¥` 在内部占用两个字节，但在匹配时会被视为单个码点。
正则表达式 不能包含 NULL 字节。
如果 haystack 或 模式 不是有效的 UTF-8，则其行为未定义。
与 re2 的默认行为不同，`.` 会匹配换行符。要禁用此行为，请在 模式 前添加 `(?-s)`。
模式 不会自动加上锚点。若要匹配整个字符串，请自行使用 `^` 和 `$` 对 模式 加锚。
如果你只是想搜索子字符串，可以改用函数 [`like`](#like) 或 [`position`](#position)，它们的速度比此函数快得多。
可选的运算符语法：`haystack REGEXP pattern`。
**语法**
```sql theme={null}
match(haystack, pattern)
```
**别名**: `REGEXP_MATCHES`
**参数**
* `haystack` — 在其中搜索模式的 String。[`String`](/zh/reference/data-types/string)
* `pattern` — 正则表达式模式。[`const String`](/zh/reference/data-types/string)
**返回值**
如果匹配该模式，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**基本模式匹配**
```sql title=Query theme={null}
SELECT match('Hello World', 'Hello.*')
```
```response title=Response theme={null}
┌─match('Hello World', 'Hello.*')─┐
│ 1 │
└─────────────────────────────────┘
```
**模式不匹配**
```sql title=Query theme={null}
SELECT match('Hello World', 'goodbye.*')
```
```response title=Response theme={null}
┌─match('Hello World', 'goodbye.*')─┐
│ 0 │
└───────────────────────────────────┘
```
**匹配子串**
```sql title=Query theme={null}
SELECT match('abcde', 'b.*d'), match('abcde', '^b.*d$')
```
```response title=Response theme={null}
┌─match('abcde', 'b.*d')─┬─match('abcde', '^b.*d$')─┐
│ 1 │ 0 │
└─────────────────────────┴───────────────────────────┘
```
## multiFuzzyMatchAllIndices
引入版本：v20.1.0
与 [`multiFuzzyMatchAny`](#multiFuzzyMatchAny) 类似，但会返回在固定[编辑距离](https://en.wikipedia.org/wiki/Edit_distance)内与 haystack 匹配的所有索引组成的数组，顺序不限。
**语法**
```sql theme={null}
multiFuzzyMatchAllIndices(haystack, distance, [pattern1, pattern2, ..., patternN])
```
**参数**
* `haystack` — 执行搜索的 String。[`String`](/zh/reference/data-types/string)
* `distance` — 模糊匹配允许的最大编辑距离。[`UInt8`](/zh/reference/data-types/int-uint)
* `pattern` — 要匹配的模式数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回一个数组，包含在指定编辑距离内以任意顺序匹配 haystack 的所有索引 (从 1 开始) 。如果未找到匹配项，则返回空数组。[`Array(UInt64)`](/zh/reference/data-types/array)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT multiFuzzyMatchAllIndices('ClickHouse', 2, ['ClickHouse', 'ClckHouse', 'ClickHose', 'House']);
```
```response title=Response theme={null}
┌─multiFuzzyMa⋯, 'House'])─┐
│ [3,1,4,2] │
└──────────────────────────┘
```
## multiFuzzyMatchAny
引入版本：v20.1.0
与 [`multiMatchAny`](#multiMatchAny) 类似，但如果任意模式在固定的[编辑距离](https://en.wikipedia.org/wiki/Edit_distance)内匹配 haystack，则返回 1。
此函数依赖 [hyperscan](https://intel.github.io/hyperscan/dev-reference/compilation.html#approximate-matching) 库的 Experimental 功能，在某些边缘情况下可能较慢。
其性能取决于编辑距离的取值和所使用的模式，但与非模糊变体相比，开销始终更高。
由于 hyperscan 的限制，`multiFuzzyMatch*()` 函数家族不支持 UTF-8 正则表达式 (会将其视为字节序列) 。
**语法**
```sql theme={null}
multiFuzzyMatchAny(haystack, distance, [pattern1, pattern2, ..., patternN])
```
**参数**
* `haystack` — 执行搜索的 String。[`String`](/zh/reference/data-types/string)
* `distance` — fuzzy matching 的最大编辑距离。[`UInt8`](/zh/reference/data-types/int-uint)
* `pattern` — 可选。用于匹配的模式数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
如果任一模式在指定的 编辑距离 内与 haystack 匹配，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT multiFuzzyMatchAny('ClickHouse', 2, ['ClickHouse', 'ClckHouse', 'ClickHose']);
```
```response title=Response theme={null}
┌─multiFuzzyMa⋯lickHose'])─┐
│ 1 │
└──────────────────────────┘
```
## multiFuzzyMatchAnyIndex
引入于：v20.1.0
与 [`multiFuzzyMatchAny`](#multiFuzzyMatchAny) 类似，但会返回在固定[编辑距离](https://en.wikipedia.org/wiki/Edit_distance)内与 haystack 匹配的任意一个索引。
**语法**
```sql theme={null}
multiFuzzyMatchAnyIndex(haystack, distance, [pattern1, pattern2, ..., patternn])
```
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string)
* `distance` — 模糊匹配允许的最大编辑距离。[`UInt8`](/zh/reference/data-types/int-uint)
* `pattern` — 用于匹配的模式数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回在指定编辑距离内与 haystack 匹配的任意一个模式的索引 (从 1 开始) ；如果都不匹配，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT multiFuzzyMatchAnyIndex('ClickHouse', 2, ['ClckHouse', 'ClickHose', 'ClickHouse']);
```
```response title=Response theme={null}
┌─multiFuzzyMa⋯ickHouse'])─┐
│ 2 │
└──────────────────────────┘
```
## multiMatchAllIndices
引入版本：v20.1.0
与 [`multiMatchAny`](#multiMatchAny) 类似，但返回按任意顺序与 haystack 匹配的所有索引组成的数组。
**语法**
```sql theme={null}
multiMatchAllIndices(haystack, [pattern1, pattern2, ..., patternn])
```
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string)
* `pattern` — 用于匹配的正则表达式。[`String`](/zh/reference/data-types/string)
**返回值**
由按任意顺序与 haystack 匹配的所有索引 (从 1 开始) 组成的数组。如果未找到匹配项，则返回空数组。[`Array(UInt64)`](/zh/reference/data-types/array)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT multiMatchAllIndices('ClickHouse', ['[0-9]', 'House', 'Click', 'ouse']);
```
```response title=Response theme={null}
┌─multiMatchAl⋯', 'ouse'])─┐
│ [3, 2, 4] │
└──────────────────────────┘
```
## multiMatchAny
引入版本：v20.1.0
检查多个正则表达式 模式 中是否至少有一个与 haystack 匹配。
如果你只想在一个字符串中搜索多个子字符串，可以改用函数 [`multiSearchAny`](#multiSearchAny)——它的速度比此函数快得多。
**语法**
```sql theme={null}
multiMatchAny(haystack, pattern1[, pattern2, ...])
```
**参数**
* `haystack` — 在其中搜索模式的 String。[`String`](/zh/reference/data-types/string)
* `pattern1[, pattern2, ...]` — 包含一个或多个正则表达式模式的数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
如果任意模式匹配则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**多个模式匹配**
```sql title=Query theme={null}
SELECT multiMatchAny('Hello World', ['Hello.*', 'foo.*'])
```
```response title=Response theme={null}
┌─multiMatchAny('Hello World', ['Hello.*', 'foo.*'])─┐
│ 1 │
└────────────────────────────────────────────────────┘
```
**没有任何模式匹配**
```sql title=Query theme={null}
SELECT multiMatchAny('Hello World', ['goodbye.*', 'foo.*'])
```
```response title=Response theme={null}
┌─multiMatchAny('Hello World', ['goodbye.*', 'foo.*'])─┐
│ 0 │
└──────────────────────────────────────────────────────┘
```
## multiMatchAnyIndex
引入版本：v20.1.0
与 [`multiMatchAny`](#multiMatchAny) 类似，但会返回任意一个与 haystack 匹配的索引。
**语法**
```sql theme={null}
multiMatchAnyIndex(haystack, [pattern1, pattern2, ..., patternn])
```
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string)
* `pattern` — 用于匹配的正则表达式。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回第一个匹配 pattern 的索引 (从 1 开始) ；如果未找到匹配项，则返回 0。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT multiMatchAnyIndex('ClickHouse', ['[0-9]', 'House', 'Click']);
```
```response title=Response theme={null}
┌─multiMatchAn⋯, 'Click'])─┐
│ 3 │
└──────────────────────────┘
```
## multiSearchAllPositions
Introduced in: v20.1.0
与 [`position`](#position) 类似，但它返回一个位置数组，表示 `haystack` 字符串中多个 `needle` 子字符串的位置 (以字节为单位，从 1 开始计数) 。
所有 `multiSearch*()` 函数最多仅支持 2^8 个 `needle`。
**Syntax**
```sql theme={null}
multiSearchAllPositions(haystack, needle1[, needle2, ...])
```
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string)
* `needle1[, needle2, ...]` — 由一个或多个待搜索子字符串组成的数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
如果找到子串，则返回由起始位置组成的数组，位置以字节为单位并从 1 开始计数；如果未找到子串，则返回 `0`。[`Array(UInt64)`](/zh/reference/data-types/array)
**示例**
**多个 needle 搜索**
```sql title=Query theme={null}
SELECT multiSearchAllPositions('Hello, World!', ['hello', '!', 'world'])
```
```response title=Response theme={null}
┌─multiSearchAllPositions('Hello, World!', ['hello', '!', 'world'])─┐
│ [0,13,0] │
└───────────────────────────────────────────────────────────────────┘
```
## multiSearchAllPositionsCaseInsensitive
引入版本：v20.1.0
与 [`multiSearchAllPositions`](#multiSearchAllPositions) 类似，但不区分大小写。
**语法**
```sql theme={null}
multiSearchAllPositionsCaseInsensitive(haystack, needle1[, needle2, ...])
```
**参数**
* `haystack` — 要在其中执行搜索的 String。[`String`](/zh/reference/data-types/string)
* `needle1[, needle2, ...]` — 由一个或多个待搜索子字符串组成的数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回一个数组，表示起始位置 (按字节计算，从 1 开始；如果找到了子串) ；如果未找到子串，则返回 `0`。[`Array(UInt64)`](/zh/reference/data-types/array)
**示例**
**不区分大小写的多重搜索**
```sql title=Query theme={null}
SELECT multiSearchAllPositionsCaseInsensitive('ClickHouse',['c','h'])
```
```response title=Response theme={null}
┌─multiSearchA⋯['c', 'h'])─┐
│ [1,6] │
└──────────────────────────┘
```
## multiSearchAllPositionsCaseInsensitiveUTF8
引入版本：v20.1.0
与 [`multiSearchAllPositionsUTF8`](#multiSearchAllPositionsUTF8) 类似，但不区分大小写。
**语法**
```sql theme={null}
multiSearchAllPositionsCaseInsensitiveUTF8(haystack, [needle1, needle2, ..., needleN])
```
**参数**
* `haystack` — 执行搜索的 UTF-8 编码字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的 UTF-8 编码子字符串。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
由起始位置组成的数组；位置按字节计算，从 1 开始 (如果找到了子字符串) 。如果未找到子字符串，则返回 0。[`Array`](/zh/reference/data-types/array)
**示例**
**不区分大小写的 UTF-8 搜索**
```sql title=Query theme={null}
SELECT multiSearchAllPositionsCaseInsensitiveUTF8('Здравствуй, мир!', ['здравствуй', 'МИР']);
```
```response title=Response theme={null}
┌─multiSearchA⋯й', 'МИР'])─┐
│ [1, 13] │
└──────────────────────────┘
```
## multiSearchAllPositionsUTF8
引入版本：v20.1.0
与 [`multiSearchAllPositions`](#multiSearchAllPositions) 类似，但假定 `haystack` 和 `needle` 子串均为 UTF-8 编码的字符串。
**语法**
```sql theme={null}
multiSearchAllPositionsUTF8(haystack, needle1[, needle2, ...])
```
**参数**
* `haystack` — 要在其中执行搜索的 UTF-8 编码字符串。[`String`](/zh/reference/data-types/string)
* `needle1[, needle2, ...]` — 要搜索的 UTF-8 编码子字符串数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回一个数组：如果找到子串，则返回其以字节为单位、从 1 开始计数的起始位置；如果未找到子串，则返回 `0`。[`Array`](/zh/reference/data-types/array)
**示例**
**UTF-8 多重搜索**
```sql title=Query theme={null}
SELECT multiSearchAllPositionsUTF8('ClickHouse',['C','H'])
```
```response title=Response theme={null}
┌─multiSearchAllPositionsUTF8('ClickHouse', ['C', 'H'])─┐
│ [1,6] │
└───────────────────────────────────────────────────────┘
```
## multiSearchAny
引入版本：v20.1.0
检查多个 needle 字符串中是否至少有一个与 haystack 字符串匹配。
函数 [`multiSearchAnyCaseInsensitive`](#multiSearchAnyCaseInsensitive)、[`multiSearchAnyUTF8`](#multiSearchAnyUTF8) 和 [`multiSearchAnyCaseInsensitiveUTF8`](#multiSearchAnyCaseInsensitiveUTF8) 提供了此函数的不区分大小写和/或 UTF-8 变体。
**语法**
```sql theme={null}
multiSearchAny(haystack, needle1[, needle2, ...])
```
**参数**
* `haystack` — 在其中执行搜索的 String。[`String`](/zh/reference/data-types/string)
* `needle1[, needle2, ...]` — 要查找的子字符串数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
如果至少有一个匹配项，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**任意匹配查找**
```sql title=Query theme={null}
SELECT multiSearchAny('ClickHouse',['C','H'])
```
```response title=Response theme={null}
┌─multiSearchAny('ClickHouse', ['C', 'H'])─┐
│ 1 │
└──────────────────────────────────────────┘
```
## multiSearchAnyCaseInsensitive
引入版本：v20.1.0
与 [multiSearchAny](#multiSearchAny) 类似，但不区分大小写。
**语法**
```sql theme={null}
multiSearchAnyCaseInsensitive(haystack, [needle1, needle2, ..., needleN])
```
**参数**
* `haystack` — 在其中执行搜索的 String。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的子字符串。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
如果至少有一个不区分大小写的匹配，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**不区分大小写的搜索**
```sql title=Query theme={null}
SELECT multiSearchAnyCaseInsensitive('ClickHouse',['c','h'])
```
```response title=Response theme={null}
┌─multiSearchAnyCaseInsensitive('ClickHouse', ['c', 'h'])─┐
│ 1 │
└─────────────────────────────────────────────────────────┘
```
## multiSearchAnyCaseInsensitiveUTF8
首次引入于：v20.1.0
与 [multiSearchAnyUTF8](#multiSearchAnyUTF8) 类似，但不区分大小写。
**语法**
```sql theme={null}
multiSearchAnyCaseInsensitiveUTF8(haystack, [needle1, needle2, ..., needleN])
```
**参数**
* `haystack` — 在其中执行搜索的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 待搜索的 UTF-8 子字符串。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
如果至少有一个不区分大小写的匹配，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**给定 UTF-8 字符串 'Здравствуйте'，检查是否包含字符 'з' (小写) **
```sql title=Query theme={null}
SELECT multiSearchAnyCaseInsensitiveUTF8('Здравствуйте',['з'])
```
```response title=Response theme={null}
┌─multiSearchA⋯те', ['з'])─┐
│ 1 │
└──────────────────────────┘
```
## multiSearchAnyUTF8
引入版本：v20.1.0
与 [multiSearchAny](#multiSearchAny) 类似，但假定 `haystack` 和 `needle` 子串都是 UTF-8 编码的字符串。
**语法**
```sql theme={null}
multiSearchAnyUTF8(haystack, [needle1, needle2, ..., needleN])
```
**参数**
* `haystack` — 执行搜索的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的 UTF-8 子字符串。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
如果至少有一个匹配，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**给定 UTF-8 字符串 '你好，世界' ('Hello, world') ，检查该字符串中是否包含字符 你 或 界**
```sql title=Query theme={null}
SELECT multiSearchAnyUTF8('你好，世界', ['你', '界'])
```
```response title=Response theme={null}
┌─multiSearchA⋯你', '界'])─┐
│ 1 │
└──────────────────────────┘
```
## multiSearchFirstIndex
引入版本：v20.1.0
在 haystack 字符串中搜索多个 needle 字符串 (区分大小写) ，并返回找到的第一个 needle 的从 1 开始的索引。
**语法**
```sql theme={null}
multiSearchFirstIndex(haystack, [needle1, needle2, ..., needleN])
```
**参数**
* `haystack` — 要在其中搜索的字符串。[`String`](/zh/reference/data-types/string)
* `needles` — 要查找的字符串数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回在 haystack 中找到的第一个 needle 的从 1 开始的索引 (即其在 needles 数组中的位置) 。如果未找到任何 needle，则返回 0。搜索区分大小写。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT multiSearchFirstIndex('ClickHouse Database', ['Click', 'Database', 'Server']);
```
```response title=Response theme={null}
┌─multiSearchF⋯ 'Server'])─┐
│ 1 │
└──────────────────────────┘
```
**区分大小写**
```sql title=Query theme={null}
SELECT multiSearchFirstIndex('ClickHouse Database', ['CLICK', 'Database', 'Server']);
```
```response title=Response theme={null}
┌─multiSearchF⋯ 'Server'])─┐
│ 2 │
└──────────────────────────┘
```
**未找到匹配项**
```sql title=Query theme={null}
SELECT multiSearchFirstIndex('Hello World', ['goodbye', 'test']);
```
```response title=Response theme={null}
┌─multiSearchF⋯', 'test'])─┐
│ 0 │
└──────────────────────────┘
```
## multiSearchFirstIndexCaseInsensitive
引入版本：v20.1.0
返回字符串 `haystack` 中最左侧匹配到的 needle\_i 的索引 `i` (从 1 开始) ，否则返回 0。
不区分大小写。
**语法**
```sql theme={null}
multiSearchFirstIndexCaseInsensitive(haystack, [needle1, needle2, ..., needleN]
```
**参数**
* `haystack` — 执行搜索的 String。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的子字符串。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回最靠左匹配到的 needle 的索引 (从 1 开始) 。如果没有匹配项，则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT multiSearchFirstIndexCaseInsensitive('hElLo WoRlD', ['World', 'Hello']);
```
```response title=Response theme={null}
┌─multiSearchF⋯, 'Hello'])─┐
│ 1 │
└──────────────────────────┘
```
## multiSearchFirstIndexCaseInsensitiveUTF8
引入版本：v20.1.0
在支持 UTF-8 编码的情况下，以不区分大小写的方式在 haystack 字符串中搜索多个 needle 字符串，并返回第一个匹配到的 needle 的从 1 开始的索引。
**语法**
```sql theme={null}
multiSearchFirstIndexCaseInsensitiveUTF8(haystack, [needle1, needle2, ..., needleN])
```
**参数**
* `haystack` — 要搜索的字符串。[`String`](/zh/reference/data-types/string)
* `needles` — 要查找的字符串数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回在 haystack 中找到的第一个 needle 的从 1 开始的索引 (即其在 needles 数组中的位置) 。如果未找到任何 needle，则返回 0。搜索不区分大小写，并遵循 UTF-8 字符编码。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT multiSearchFirstIndexCaseInsensitiveUTF8('ClickHouse Database', ['CLICK', 'data', 'server']);
```
```response title=Response theme={null}
┌─multiSearchF⋯ 'server'])─┐
│ 1 │
└──────────────────────────┘
```
**UTF-8 字母大小写处理**
```sql title=Query theme={null}
SELECT multiSearchFirstIndexCaseInsensitiveUTF8('Привет Мир', ['мир', 'ПРИВЕТ']);
```
```response title=Response theme={null}
┌─multiSearchF⋯ 'ПРИВЕТ'])─┐
│ 1 │
└──────────────────────────┘
```
**未找到匹配结果**
```sql title=Query theme={null}
SELECT multiSearchFirstIndexCaseInsensitiveUTF8('Hello World', ['goodbye', 'test']);
```
```response title=Response theme={null}
┌─multiSearchF⋯', 'test'])─┐
│ 0 │
└──────────────────────────┘
```
## multiSearchFirstIndexUTF8
引入版本：v20.1.0
返回字符串 `haystack` 中最靠左匹配到的 needle\_i 的索引 `i` (从 1 开始) ，否则返回 0。
假定 `haystack` 和 `needle` 是采用 UTF-8 编码的字符串。
**语法**
```sql theme={null}
multiSearchFirstIndexUTF8(haystack, [needle1, needle2, ..., needleN])
```
**参数**
* `haystack` — 在其中进行搜索的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的 UTF-8 子字符串数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回最先找到的、最靠左的 `needle` 的索引 (从 1 开始计数) 。如果没有匹配，则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT multiSearchFirstIndexUTF8('Здравствуйте мир', ['мир', 'здравствуйте']);
```
```response title=Response theme={null}
┌─multiSearchF⋯вствуйте'])─┐
│ 1 │
└──────────────────────────┘
```
## multiSearchFirstPosition
引入版本：v20.1.0
与 [`position`](#position) 类似，但返回 `haystack` 字符串中与多个 `needle` 字符串里任意一个匹配的最左偏移量。
函数 [`multiSearchFirstPositionCaseInsensitive`](#multiSearchFirstPositionCaseInsensitive)、[`multiSearchFirstPositionUTF8`](#multiSearchFirstPositionUTF8) 和 [`multiSearchFirstPositionCaseInsensitiveUTF8`](#multiSearchFirstPositionCaseInsensitiveUTF8) 提供了此函数的不区分大小写和/或 UTF-8 变体。
**语法**
```sql theme={null}
multiSearchFirstPosition(haystack, needle1[, needle2, ...])
```
**参数**
* `haystack` — 执行搜索的 String。[`String`](/zh/reference/data-types/string)
* `needle1[, needle2, ...]` — 由一个或多个待搜索子字符串组成的数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回 `haystack` 字符串中与多个 `needle` 字符串中的任意一个匹配的最左侧偏移量；如果没有匹配，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**搜索首个位置**
```sql title=Query theme={null}
SELECT multiSearchFirstPosition('Hello World',['llo', 'Wor', 'ld'])
```
```response title=Response theme={null}
┌─multiSearchFirstPosition('Hello World', ['llo', 'Wor', 'ld'])─┐
│ 3 │
└───────────────────────────────────────────────────────────────┘
```
## multiSearchFirstPositionCaseInsensitive
引入版本：v20.1.0
与 [multiSearchFirstPosition](#multiSearchFirstPosition) 类似，但不区分大小写。
**语法**
```sql theme={null}
multiSearchFirstPositionCaseInsensitive(haystack, [needle1, needle2, ..., needleN])
```
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的子字符串数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回 `haystack` 字符串中与多个 `needle` 字符串中的任意一个匹配的最左侧偏移量。如果没有匹配，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**大小写不敏感的第一个位置**
```sql title=Query theme={null}
SELECT multiSearchFirstPositionCaseInsensitive('HELLO WORLD',['wor', 'ld', 'ello'])
```
```response title=Response theme={null}
┌─multiSearchFirstPositionCaseInsensitive('HELLO WORLD', ['wor', 'ld', 'ello'])─┐
│ 2 │
└───────────────────────────────────────────────────────────────────────────────┘
```
## multiSearchFirstPositionCaseInsensitiveUTF8
引入版本：v20.1.0
与 [multiSearchFirstPosition](#multiSearchFirstPosition) 类似，但假定 `haystack` 和 `needle` 均为 UTF-8 字符串，且不区分大小写。
**语法**
```sql theme={null}
multiSearchFirstPositionCaseInsensitiveUTF8(haystack, [needle1, needle2, ..., needleN])
```
**参数**
* `haystack` — 执行搜索的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的 UTF-8 子字符串数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
返回 `haystack` 字符串中与多个 `needle` 字符串中的任意一个匹配的最左侧偏移量，忽略大小写。如果没有匹配，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**查找 UTF-8 字符串 'Здравствуй, мир' ('Hello, world') 中与给定 `needle` 中任意一个匹配的最左侧偏移量**
```sql title=Query theme={null}
SELECT multiSearchFirstPositionCaseInsensitiveUTF8('Здравствуй, мир', ['МИР', 'вст', 'Здра'])
```
```response title=Response theme={null}
┌─multiSearchFirstPositionCaseInsensitiveUTF8('Здравствуй, мир', ['мир', 'вст', 'Здра'])─┐
│ 3 │
└────────────────────────────────────────────────────────────────────────────────────────┘
```
## multiSearchFirstPositionUTF8
引入版本：v20.1.0
与 [multiSearchFirstPosition](#multiSearchFirstPosition) 类似，但假设 `haystack` 和 `needle` 都是 UTF-8 字符串。
**语法**
```sql theme={null}
multiSearchFirstPositionUTF8(haystack, [needle1, needle2, ..., needleN])
```
**参数**
* `haystack` — 执行搜索的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 要搜索的 UTF-8 子字符串数组。[`Array(String)`](/zh/reference/data-types/array)
**返回值**
`haystack` 字符串中与多个 `needle` 字符串中任意一个匹配的最左侧偏移量。如果没有匹配，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**查找 UTF-8 字符串 'Здравствуй, мир' ('Hello, world') 中与给定任意一个 needle 匹配的最左侧偏移量**
```sql title=Query theme={null}
SELECT multiSearchFirstPositionUTF8('Здравствуй, мир',['мир', 'вст', 'авст'])
```
```response title=Response theme={null}
┌─multiSearchFirstPositionUTF8('Здравствуй, мир', ['мир', 'вст', 'авст'])─┐
│ 3 │
└─────────────────────────────────────────────────────────────────────────┘
```
## ngramDistance
引入版本：v20.1.0
计算两个字符串之间的 4-gram 距离。
为此，它会统计两个 4-gram 多重集合之间的对称差，并用它们的基数之和对结果进行归一化。
返回值越小，字符串越相似。
如需进行不区分大小写的搜索和/或使用 UTF8 格式，请使用函数 [`ngramDistanceCaseInsensitive`](#ngramDistanceCaseInsensitive)、[`ngramDistanceUTF8`](#ngramDistanceUTF8)、[`ngramDistanceCaseInsensitiveUTF8`](#ngramDistanceCaseInsensitiveUTF8)。
**语法**
```sql theme={null}
ngramDistance(haystack, needle)
```
**参数**
* `haystack` — 用于比较的字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 用于比较的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个介于 `0` 和 `1` 之间的 Float32 数值。返回值越小，字符串越相似。[`Float32`](/zh/reference/data-types/float)
**示例**
**计算 4-gram 距离**
```sql title=Query theme={null}
SELECT ngramDistance('ClickHouse', 'ClickHouses')
```
```response title=Response theme={null}
┌─ngramDistance('ClickHouse', 'ClickHouses')─┐
│ 0.1 │
└────────────────────────────────────────────┘
```
## ngramDistanceCaseInsensitive
引入版本：v20.1.0
提供 [`ngramDistance`](#ngramDistance) 的不区分大小写变体。
计算两个字符串之间的 4-gram 距离，忽略大小写。
返回值越小，字符串越相似。
**语法**
```sql theme={null}
ngramDistanceCaseInsensitive(haystack, needle)
```
**参数**
* `haystack` — 第一个比较字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 第二个比较字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个介于 `0` 和 `1` 之间的 Float32 数值。[`Float32`](/zh/reference/data-types/float)
**示例**
**不区分大小写的 4-gram 距离**
```sql title=Query theme={null}
SELECT ngramDistanceCaseInsensitive('ClickHouse','clickhouse')
```
```response title=Response theme={null}
┌─ngramDistanceCaseInsensitive('ClickHouse','clickhouse')─┐
│ 0 │
└─────────────────────────────────────────────────────────┘
```
## ngramDistanceCaseInsensitiveUTF8
引入版本：v20.1.0
提供 [`ngramDistance`](#ngramDistance) 的不区分大小写 UTF-8 变体。
假定 `needle` 和 `haystack` 字符串均为 UTF-8 编码，并忽略大小写。
计算两个 UTF-8 字符串之间不区分大小写的 3-gram 距离。
返回值越小，字符串越相似。
**语法**
```sql theme={null}
ngramDistanceCaseInsensitiveUTF8(haystack, needle)
```
**参数**
* `haystack` — 第一个采用 UTF-8 编码的比较字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 第二个采用 UTF-8 编码的比较字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个介于 `0` 和 `1` 之间的 Float32 数值。[`Float32`](/zh/reference/data-types/float)
**示例**
**不区分大小写的 UTF-8 3-gram 距离**
```sql title=Query theme={null}
SELECT ngramDistanceCaseInsensitiveUTF8('abcde','CDE')
```
```response title=Response theme={null}
┌─ngramDistanceCaseInsensitiveUTF8('abcde','CDE')─┐
│ 0.5 │
└─────────────────────────────────────────────────┘
```
## ngramDistanceUTF8
引入版本：v20.1.0
提供 [`ngramDistance`](#ngramDistance) 的 UTF-8 版本。
假定 `needle` 和 `haystack` 字符串均为 UTF-8 编码。
计算两个 UTF-8 字符串之间的 3-gram 距离。
返回值越小，字符串越相似。
**语法**
```sql theme={null}
ngramDistanceUTF8(haystack, needle)
```
**参数**
* `haystack` — 第一个 UTF-8 编码的比较字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 第二个 UTF-8 编码的比较字符串。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `0` 到 `1` 之间的 Float32 数值。[`Float32`](/zh/reference/data-types/float)
**示例**
**UTF-8 3-gram 距离**
```sql title=Query theme={null}
SELECT ngramDistanceUTF8('abcde','cde')
```
```response title=Response theme={null}
┌─ngramDistanceUTF8('abcde','cde')─┐
│ 0.5 │
└───────────────────────────────────┘
```
## ngramSearch
引入版本：v20.1.0
检查两个字符串之间的 4-gram 距离是否小于或等于给定的阈值。
如需进行不区分大小写的搜索和/或使用 UTF8 格式，请使用函数 `ngramSearchCaseInsensitive`、`ngramSearchUTF8`、`ngramSearchCaseInsensitiveUTF8`。
**语法**
```sql theme={null}
ngramSearch(haystack, needle)
```
**参数**
* `haystack` — 用于比较的字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 用于比较的字符串。[`String`](/zh/reference/data-types/string)
**返回值**
如果两个字符串之间的 4-gram 距离小于或等于阈值 (默认为 `1.0`) ，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用 4-gram 进行搜索**
```sql title=Query theme={null}
SELECT ngramSearch('ClickHouse', 'Click')
```
```response title=Response theme={null}
┌─ngramSearch('ClickHouse', 'Click')─┐
│ 1 │
└────────────────────────────────────┘
```
## ngramSearchCaseInsensitive
引入版本：v20.1.0
提供 [`ngramSearch`](#ngramSearch) 的不区分大小写版本。
计算 needle 字符串与 haystack 字符串之间的非对称差，即用 needle 中的 n-gram 数量减去共有的 n-gram 数量，再按 needle 的 n-gram 数量进行归一化。
检查两个字符串之间的 4-gram 距离是否小于或等于给定的阈值，并忽略大小写。
**语法**
```sql theme={null}
ngramSearchCaseInsensitive(haystack, needle)
```
**参数**
* `haystack` — 用于比较的 String。[`String`](/zh/reference/data-types/string)
* `needle` — 用于比较的 String。[`String`](/zh/reference/data-types/string)
**返回值**
如果两个字符串之间的 4-gram 距离小于或等于阈值 (默认值为 `1.0`) ，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用 4-gram 的不区分大小写搜索**
```sql title=Query theme={null}
SELECT ngramSearchCaseInsensitive('Hello World','hello')
```
```response title=Response theme={null}
┌─ngramSearchCaseInsensitive('Hello World','hello')─┐
│ 1 │
└────────────────────────────────────────────────────┘
```
## ngramSearchCaseInsensitiveUTF8
引入版本：v20.1.0
提供 [`ngramSearch`](#ngramSearch) 的不区分大小写 UTF-8 变体。
假定 `haystack` 和 `needle` 为 UTF-8 字符串，并且不区分大小写。
检查两个 UTF-8 字符串之间的 3-gram 距离是否小于或等于给定阈值，且不区分大小写。
**语法**
```sql theme={null}
ngramSearchCaseInsensitiveUTF8(haystack, needle)
```
**参数**
* `haystack` — 用于比较的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 用于比较的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
**返回值**
如果两个字符串之间的 3-gram 距离小于或等于阈值 (默认为 `1.0`) ，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用 3-gram 的不区分大小写 UTF-8 搜索**
```sql title=Query theme={null}
SELECT ngramSearchCaseInsensitiveUTF8('абвГДЕёжз', 'АбвгдЕЁжз')
```
```response title=Response theme={null}
┌─ngramSearchCaseInsensitiveUTF8('абвГДЕёжз', 'АбвгдЕЁжз')─┐
│ 1 │
└──────────────────────────────────────────────────────────┘
```
## ngramSearchUTF8
引入版本：v20.1.0
提供 `ngramSearch` 的 UTF-8 版本。
假定 `haystack` 和 `needle` 为 UTF-8 字符串。
检查两个 UTF-8 字符串之间的 3-gram distance 是否小于或等于给定阈值。
**语法**
```sql theme={null}
ngramSearchUTF8(haystack, needle)
```
**参数**
* `haystack` — 用于比较的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
* `needle` — 用于比较的 UTF-8 字符串。[`String`](/zh/reference/data-types/string)
**返回值**
如果两个字符串之间的 3-gram 距离小于或等于阈值 (默认为 `1.0`) ，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用 3-gram 进行 UTF-8 搜索**
```sql title=Query theme={null}
SELECT ngramSearchUTF8('абвгдеёжз', 'гдеёзд')
```
```response title=Response theme={null}
┌─ngramSearchUTF8('абвгдеёжз', 'гдеёзд')─┐
│ 1 │
└────────────────────────────────────────┘
```
## notILike
引入版本：v20.6.0
检查字符串是否不匹配某个模式，且不区分大小写。该模式可包含用于 SQL LIKE 匹配的特殊字符 `%` 和 `_`。
**语法**
```sql theme={null}
notILike(haystack, pattern)
```
**参数**
* `haystack` — 待搜索的输入字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `pattern` — 要匹配的 SQL LIKE 模式。`%` 匹配任意数量的字符 (包括零个) ，`_` 恰好匹配一个字符。[`String`](/zh/reference/data-types/string)
**返回值**
如果字符串与模式不匹配 (不区分大小写) ，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT notILike('ClickHouse', '%house%');
```
```response title=Response theme={null}
┌─notILike('Cl⋯ '%house%')─┐
│ 0 │
└──────────────────────────┘
```
## notLike
Introduced in：v1.1.0
与 [`like`](#like) 类似，但会返回相反的结果。
**Syntax**
```sql theme={null}
notLike(haystack, pattern)
-- haystack 不符合 LIKE 模式 pattern
```
**参数**
* `haystack` — 要在其中执行搜索的字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `pattern` — 用于匹配的 LIKE 模式。[`String`](/zh/reference/data-types/string)
**返回值**
如果字符串与 `LIKE` 模式不匹配，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT notLike('ClickHouse', '%House%');
```
```response title=Response theme={null}
┌─notLike('Cli⋯ '%House%')─┐
│ 0 │
└──────────────────────────┘
```
**不匹配的模式**
```sql title=Query theme={null}
SELECT notLike('ClickHouse', '%SQL%');
```
```response title=Response theme={null}
┌─notLike('Cli⋯', '%SQL%')─┐
│ 1 │
└──────────────────────────┘
```
## 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`](#locate)、[`positionCaseInsensitive`](#positionCaseInsensitive)、[`positionUTF8`](#positionUTF8) 和 [`positionCaseInsensitiveUTF8`](#positionCaseInsensitiveUTF8)。
**语法**
```sql theme={null}
position(haystack, needle[, start_pos])
```
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string) 或 [`枚举`](/zh/reference/data-types/enum)
* `needle` — 要搜索的子串。[`String`](/zh/reference/data-types/string)
* `start_pos` — `haystack` 中开始搜索的位置 (从 1 开始计数) 。可选。[`UInt`](/zh/reference/data-types/int-uint)
**返回值**
如果找到子串，则返回其起始位置 (以字节为单位，从 1 开始计数) ；如果未找到，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**基本用法**
```sql title=Query theme={null}
SELECT position('Hello, world!', '!')
```
```response title=Response theme={null}
┌─position('Hello, world!', '!')─┐
│ 13 │
└────────────────────────────────┘
```
**带有 start\_pos 参数**
```sql title=Query theme={null}
SELECT position('Hello, world!', 'o', 1), position('Hello, world!', 'o', 7)
```
```response title=Response theme={null}
┌─position('Hello, world!', 'o', 1)─┬─position('Hello, world!', 'o', 7)─┐
│ 5 │ 9 │
└───────────────────────────────────┴───────────────────────────────────┘
```
**Needle IN haystack 语法**
```sql title=Query theme={null}
SELECT 6 = position('/' IN s) FROM (SELECT 'Hello/World' AS s)
```
```response title=Response theme={null}
┌─equals(6, position(s, '/'))─┐
│ 1 │
└─────────────────────────────┘
```
**空 needle 的子串**
```sql title=Query theme={null}
SELECT position('abc', ''), position('abc', '', 0), position('abc', '', 1), position('abc', '', 2), position('abc', '', 3), position('abc', '', 4), position('abc', '', 5)
```
```response title=Response theme={null}
┌─position('abc', '')─┬─position('abc', '', 0)─┬─position('abc', '', 1)─┬─position('abc', '', 2)─┬─position('abc', '', 3)─┬─position('abc', '', 4)─┬─position('abc', '', 5)─┐
│ 1 │ 1 │ 1 │ 2 │ 3 │ 4 │ 0 │
└─────────────────────┴────────────────────────┴────────────────────────┴────────────────────────┴────────────────────────┴────────────────────────┴────────────────────────┘
```
## positionCaseInsensitive
引入版本：v1.1.0
与 [`position`](#position) 类似，但不区分大小写。
**语法**
```sql theme={null}
positionCaseInsensitive(haystack, needle[, start_pos])
```
**别名**: `instr`
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string) 或 [`枚举`](/zh/reference/data-types/enum)
* `needle` — 要搜索的子串。[`String`](/zh/reference/data-types/string)
* `start_pos` — 可选。`haystack` 中开始搜索的位置 (从 1 开始计数) 。[`UInt*`](/zh/reference/data-types/int-uint)
**返回值**
如果找到子串，则返回其起始位置 (以字节为单位，从 1 开始计数) ；如果未找到子串，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**不区分大小写的搜索**
```sql title=Query theme={null}
SELECT positionCaseInsensitive('Hello, world!', 'hello')
```
```response title=Response theme={null}
┌─positionCaseInsensitive('Hello, world!', 'hello')─┐
│ 1 │
└───────────────────────────────────────────────────┘
```
## positionCaseInsensitiveUTF8
引入版本：v1.1.0
与 [`positionUTF8`](#positionUTF8) 类似，但按不区分大小写的方式搜索。
**语法**
```sql theme={null}
positionCaseInsensitiveUTF8(haystack, needle[, start_pos])
```
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string) 或 [`枚举`](/zh/reference/data-types/enum)
* `needle` — 要搜索的子串。[`String`](/zh/reference/data-types/string)
* `start_pos` — 可选。`haystack` 中开始搜索的位置 (从 1 开始) 。[`UInt*`](/zh/reference/data-types/int-uint)
**返回值**
如果找到子串，则返回其起始位置 (以字节为单位，从 1 开始计数) ；如果未找到，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**不区分大小写的 UTF-8 搜索**
```sql title=Query theme={null}
SELECT positionCaseInsensitiveUTF8('Привет мир', 'МИР')
```
```response title=Response theme={null}
┌─positionCaseInsensitiveUTF8('Привет мир', 'МИР')─┐
│ 8 │
└──────────────────────────────────────────────────┘
```
## positionUTF8
引入版本：v1.1.0
与 [`position`](#position) 类似，但假定 `haystack` 和 `needle` 为 UTF-8 编码的字符串。
**语法**
```sql theme={null}
positionUTF8(haystack, needle[, start_pos])
```
**参数**
* `haystack` — 执行搜索的字符串。[`String`](/zh/reference/data-types/string) 或 [`枚举`](/zh/reference/data-types/enum)
* `needle` — 要搜索的子串。[`String`](/zh/reference/data-types/string)
* `start_pos` — 可选。`haystack` 中开始搜索的位置 (从 1 开始计数) 。[`UInt*`](/zh/reference/data-types/int-uint)
**返回值**
如果找到子串，则返回其起始位置 (以字节为单位，从 1 开始计数) ；如果未找到，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**按 UTF-8 字符计数**
```sql title=Query theme={null}
SELECT positionUTF8('Motörhead', 'r')
```
```response title=Response theme={null}
┌─position('Motörhead', 'r')─┐
│ 5 │
└────────────────────────────┘
```