ClickHouse/docs/en/sql-reference/functions/string-search-functions.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

684 lines
25 KiB
Markdown
Raw Normal View History

2020-04-03 13:23:32 +00:00
---
2022-08-28 14:53:34 +00:00
slug: /en/sql-reference/functions/string-search-functions
2023-04-19 17:05:55 +00:00
sidebar_position: 160
sidebar_label: Searching in Strings
2020-04-03 13:23:32 +00:00
---
2022-06-02 10:55:18 +00:00
# Functions for Searching in Strings
2023-04-20 09:30:11 +00:00
All functions in this section search by default case-sensitively. Case-insensitive search is usually provided by separate function variants.
Note that case-insensitive search follows the lowercase-uppercase rules of the English language. E.g. Uppercased `i` in English language is
`I` whereas in Turkish language it is `İ` - results for languages other than English may be unexpected.
2023-04-20 09:30:11 +00:00
Functions in this section also assume that the searched string and the search string are single-byte encoded text. If this assumption is
violated, no exception is thrown and results are undefined. Search with UTF-8 encoded strings is usually provided by separate function
variants. Likewise, if a UTF-8 function variant is used and the input strings are not UTF-8 encoded text, no exception is thrown and the
results are undefined. Note that no automatic Unicode normalization is performed, you can use the
[normalizeUTF8*()](https://clickhouse.com/docs/en/sql-reference/functions/string-functions/) functions for that.
2020-06-19 10:08:10 +00:00
2023-04-20 10:08:49 +00:00
[General strings functions](string-functions.md) and [functions for replacing in strings](string-replace-functions.md) are described separately.
2021-03-22 16:30:28 +00:00
2023-04-20 09:30:11 +00:00
## position
2021-02-22 09:49:49 +00:00
2023-04-20 09:30:11 +00:00
Returns the position (in bytes, starting at 1) of a substring `needle` in a string `haystack`.
**Syntax**
2020-03-20 10:10:48 +00:00
``` sql
2021-03-30 06:15:52 +00:00
position(haystack, needle[, start_pos])
2021-07-29 15:20:55 +00:00
```
2021-03-30 06:15:52 +00:00
2023-04-20 09:30:11 +00:00
Alias:
- `position(needle IN haystack)`
- `locate(haystack, needle[, start_pos])`.
2021-03-13 18:25:06 +00:00
**Arguments**
2023-04-20 09:30:11 +00:00
- `haystack` — String in which the search is performed. [String](../../sql-reference/syntax.md#syntax-string-literal).
- `needle` — Substring to be searched. [String](../../sql-reference/syntax.md#syntax-string-literal).
2023-04-20 09:30:11 +00:00
- `start_pos` Position (1-based) in `haystack` at which the search starts. [UInt](../../sql-reference/data-types/int-uint.md). Optional.
**Returned values**
2023-04-20 09:30:11 +00:00
- Starting position in bytes and counting from 1, if the substring was found.
- 0, if the substring was not found.
2023-04-20 09:30:11 +00:00
If substring `needle` is empty, these rules apply:
- if no `start_pos` was specified: return `1`
- if `start_pos = 0`: return `1`
- if `start_pos >= 1` and `start_pos <= length(haystack) + 1`: return `start_pos`
- otherwise: return `0`
2023-04-20 09:30:11 +00:00
The same rules also apply to functions `positionCaseInsensitive`, `positionUTF8` and `positionCaseInsensitiveUTF8`
2023-04-20 09:30:11 +00:00
Type: `Integer`.
2023-04-20 09:30:11 +00:00
**Examples**
2020-03-20 10:10:48 +00:00
``` sql
SELECT position('Hello, world!', '!');
```
Result:
2020-03-20 10:10:48 +00:00
``` text
┌─position('Hello, world!', '!')─┐
│ 13 │
└────────────────────────────────┘
```
2023-04-20 09:30:11 +00:00
Example with `start_pos` argument:
``` sql
SELECT
position('Hello, world!', 'o', 1),
position('Hello, world!', 'o', 7)
```
``` text
┌─position('Hello, world!', 'o', 1)─┬─position('Hello, world!', 'o', 7)─┐
│ 5 │ 9 │
└───────────────────────────────────┴───────────────────────────────────┘
```
2023-04-20 09:30:11 +00:00
Example for `needle IN haystack` syntax:
2023-04-20 09:30:11 +00:00
```sql
SELECT 6 = position('/' IN s) FROM (SELECT 'Hello/World' AS s);
```
Result:
2023-04-20 09:30:11 +00:00
```text
┌─equals(6, position(s, '/'))─┐
│ 1 │
└─────────────────────────────┘
```
2023-04-20 09:30:11 +00:00
Examples with empty `needle` substring:
2023-01-30 08:13:12 +00:00
``` sql
SELECT
position('abc', ''),
position('abc', '', 0),
position('abc', '', 1),
position('abc', '', 2),
position('abc', '', 3),
position('abc', '', 4),
position('abc', '', 5)
```
``` text
┌─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 │
└─────────────────────┴────────────────────────┴────────────────────────┴────────────────────────┴────────────────────────┴────────────────────────┴────────────────────────┘
```
2022-06-02 10:55:18 +00:00
## positionCaseInsensitive
2023-04-20 09:30:11 +00:00
Like [position](#position) but searches case-insensitively.
2023-04-20 09:30:11 +00:00
## positionUTF8
2023-04-20 09:30:11 +00:00
Like [position](#position) but assumes `haystack` and `needle` are UTF-8 encoded strings.
2023-04-20 09:30:11 +00:00
**Examples**
2023-04-20 09:30:11 +00:00
Function `positionUTF8` correctly counts character `ö` (represented by two points) as a single Unicode codepoint:
2020-03-20 10:10:48 +00:00
``` sql
2023-04-20 09:30:11 +00:00
SELECT positionUTF8('Motörhead', 'r');
```
Result:
2020-03-20 10:10:48 +00:00
``` text
2023-04-20 09:30:11 +00:00
┌─position('Motörhead', 'r')─┐
│ 5 │
└────────────────────────────┘
```
2023-04-20 09:30:11 +00:00
## positionCaseInsensitiveUTF8
2023-04-20 09:30:11 +00:00
Like [positionUTF8](#positionutf8) but searches case-insensitively.
2023-04-20 09:30:11 +00:00
## multiSearchAllPositions
2023-04-20 09:30:11 +00:00
Like [position](#position) but returns an array of positions (in bytes, starting at 1) for multiple `needle` substrings in a `haystack` string.
:::note
All `multiSearch*()` functions only support up to 2<sup>8</sup> needles.
:::
**Syntax**
2020-03-20 10:10:48 +00:00
``` sql
2023-04-20 09:30:11 +00:00
multiSearchAllPositions(haystack, [needle1, needle2, ..., needleN])
```
**Arguments**
2023-04-20 09:30:11 +00:00
- `haystack` — String in which the search is performed. [String](../../sql-reference/syntax.md#syntax-string-literal).
- `needle` — Substrings to be searched. Array
**Returned values**
2023-04-20 09:30:11 +00:00
- Array of the starting position in bytes and counting from 1 (if the substring was found) or 0 (if the substring was not found)
2023-04-20 09:30:11 +00:00
**Example**
2020-03-20 10:10:48 +00:00
``` sql
2023-04-20 09:30:11 +00:00
SELECT multiSearchAllPositions('Hello, World!', ['hello', '!', 'world']);
```
Result:
2020-03-20 10:10:48 +00:00
``` text
2023-04-20 09:30:11 +00:00
┌─multiSearchAllPositions('Hello, World!', ['hello', '!', 'world'])─┐
│ [0,13,0] │
└───────────────────────────────────────────────────────────────────┘
```
2023-04-20 09:30:11 +00:00
## multiSearchAllPositionsUTF8
2023-04-20 09:30:11 +00:00
Like [multiSearchAllPositions](#multiSearchAllPositions) but assumes `haystack` and the `needle`-s are UTF-8 encoded strings.
2023-04-20 09:30:11 +00:00
## multiSearchFirstPosition
2023-04-20 09:30:11 +00:00
Like `position` but returns the leftmost offset in a `haystack` string which matches any of multiple `needle` strings.
2023-04-20 09:30:11 +00:00
Functions `multiSearchFirstPositionCaseInsensitive`, `multiSearchFirstPositionUTF8` and `multiSearchFirstPositionCaseInsensitiveUTF8` provide case-insensitive and/or UTF-8 variants of this function.
2023-04-20 09:30:11 +00:00
**Syntax**
2023-04-20 09:30:11 +00:00
```sql
multiSearchFirstPosition(haystack, \[needle<sub>1</sub>, needle<sub>2</sub>, …, needle<sub>n</sub>\])
```
2023-04-20 09:30:11 +00:00
## multiSearchFirstIndex
2023-04-20 09:30:11 +00:00
Returns the index `i` (starting from 1) of the leftmost found needle<sub>i</sub> in the string `haystack` and 0 otherwise.
2023-04-20 09:30:11 +00:00
Functions `multiSearchFirstIndexCaseInsensitive`, `multiSearchFirstIndexUTF8` and `multiSearchFirstIndexCaseInsensitiveUTF8` provide case-insensitive and/or UTF-8 variants of this function.
**Syntax**
2023-04-20 09:30:11 +00:00
```sql
multiSearchFirstIndex(haystack, \[needle<sub>1</sub>, needle<sub>2</sub>, …, needle<sub>n</sub>\])
```
2023-04-20 09:30:11 +00:00
## multiSearchAny
2023-04-20 09:30:11 +00:00
Returns 1, if at least one string needle<sub>i</sub> matches the string `haystack` and 0 otherwise.
2023-04-20 09:30:11 +00:00
Functions `multiSearchAnyCaseInsensitive`, `multiSearchAnyUTF8` and `multiSearchAnyCaseInsensitiveUTF8` provide case-insensitive and/or UTF-8 variants of this function.
2023-04-20 09:30:11 +00:00
**Syntax**
2023-04-20 09:30:11 +00:00
```sql
multiSearchAny(haystack, \[needle<sub>1</sub>, needle<sub>2</sub>, …, needle<sub>n</sub>\])
```
2023-04-20 09:30:11 +00:00
## match
2023-04-20 09:30:11 +00:00
Returns whether string `haystack` matches the regular expression `pattern` in [re2 regular syntax](https://github.com/google/re2/wiki/Syntax).
2019-01-23 08:38:32 +00:00
2023-04-20 09:30:11 +00:00
Matching is based on UTF-8, e.g. `.` matches the Unicode code point `¥` which is represented in UTF-8 using two bytes. The regular
expression must not contain null bytes. If the haystack or the pattern are not valid UTF-8, then the behavior is undefined.
2019-01-23 08:38:32 +00:00
2023-04-20 09:30:11 +00:00
Unlike re2's default behavior, `.` matches line breaks. To disable this, prepend the pattern with `(?-s)`.
2019-01-23 08:38:32 +00:00
2023-04-20 09:30:11 +00:00
If you only want to search substrings in a string, you can use functions [like](#like) or [position](#position) instead - they work much faster than this function.
2020-03-20 10:10:48 +00:00
**Syntax**
2023-04-20 09:30:11 +00:00
```sql
match(haystack, pattern)
```
2023-04-20 09:30:11 +00:00
Alias: `haystack REGEXP pattern operator`
2023-04-20 09:30:11 +00:00
## multiMatchAny
2023-04-20 09:30:11 +00:00
Like `match` but returns 1 if at least one of the patterns match and 0 otherwise.
2023-04-20 09:30:11 +00:00
:::note
Functions in the `multi[Fuzzy]Match*()` family use the the (Vectorscan)[https://github.com/VectorCamp/vectorscan] library. As such, they are only enabled if ClickHouse is compiled with support for vectorscan.
2023-04-20 09:30:11 +00:00
To turn off all functions that use hyperscan, use setting `SET allow_hyperscan = 0;`.
2023-04-20 09:30:11 +00:00
Due to restrictions of vectorscan, the length of the `haystack` string must be less than 2<sup>32</sup> bytes.
2023-04-20 09:30:11 +00:00
Hyperscan is generally vulnerable to regular expression denial of service (ReDoS) attacks (e.g. see
(here)[https://www.usenix.org/conference/usenixsecurity22/presentation/turonova], (here)[https://doi.org/10.1007/s10664-021-10033-1] and
(here)[https://doi.org/10.1145/3236024.3236027]. Users are adviced to check the provided patterns carefully.
:::
2023-04-20 09:30:11 +00:00
If you only want to search multiple substrings in a string, you can use function [multiSearchAny](#multisearchany) instead - it works much faster than this function.
2023-04-20 09:30:11 +00:00
**Syntax**
```sql
multiMatchAny(haystack, \[pattern<sub>1</sub>, pattern<sub>2</sub>, …, pattern<sub>n</sub>\])
```
2023-04-20 09:30:11 +00:00
## multiMatchAnyIndex
2023-04-20 09:30:11 +00:00
Like `multiMatchAny` but returns any index that matches the haystack.
2019-01-23 08:38:32 +00:00
2023-04-20 09:30:11 +00:00
**Syntax**
2019-01-23 08:38:32 +00:00
2023-04-20 09:30:11 +00:00
```sql
multiMatchAnyIndex(haystack, \[pattern<sub>1</sub>, pattern<sub>2</sub>, …, pattern<sub>n</sub>\])
```
2019-01-23 08:38:32 +00:00
2023-04-20 09:30:11 +00:00
## multiMatchAllIndices
2019-01-23 08:38:32 +00:00
2023-04-20 09:30:11 +00:00
Like `multiMatchAny` but returns the array of all indices that match the haystack in any order.
2023-04-20 09:30:11 +00:00
**Syntax**
2023-04-20 09:30:11 +00:00
```sql
multiMatchAllIndices(haystack, \[pattern<sub>1</sub>, pattern<sub>2</sub>, …, pattern<sub>n</sub>\])
```
2019-01-23 08:38:32 +00:00
2023-04-20 09:30:11 +00:00
## multiFuzzyMatchAny
2019-01-23 08:38:32 +00:00
2023-04-20 09:30:11 +00:00
Like `multiMatchAny` but returns 1 if any pattern matches the haystack within a constant [edit distance](https://en.wikipedia.org/wiki/Edit_distance). This function relies on the experimental feature of [hyperscan](https://intel.github.io/hyperscan/dev-reference/compilation.html#approximate-matching) library, and can be slow for some corner cases. The performance depends on the edit distance value and patterns used, but it's always more expensive compared to a non-fuzzy variants.
2019-01-23 08:38:32 +00:00
2022-06-17 13:26:59 +00:00
:::note
2023-04-20 09:30:11 +00:00
`multiFuzzyMatch*()` function family do not support UTF-8 regular expressions (it threats them as a sequence of bytes) due to restrictions of hyperscan.
:::
2019-03-28 15:12:37 +00:00
2023-04-20 09:30:11 +00:00
**Syntax**
2023-04-20 09:30:11 +00:00
```sql
multiFuzzyMatchAny(haystack, distance, \[pattern<sub>1</sub>, pattern<sub>2</sub>, …, pattern<sub>n</sub>\])
```
2023-04-20 09:30:11 +00:00
## multiFuzzyMatchAnyIndex
2023-04-20 09:30:11 +00:00
Like `multiFuzzyMatchAny` but returns any index that matches the haystack within a constant edit distance.
2023-04-20 09:30:11 +00:00
**Syntax**
2023-02-08 13:07:27 +00:00
2023-04-20 09:30:11 +00:00
```sql
multiFuzzyMatchAnyIndex(haystack, distance, \[pattern<sub>1</sub>, pattern<sub>2</sub>, …, pattern<sub>n</sub>\])
```
2023-02-08 13:07:27 +00:00
2023-04-20 09:30:11 +00:00
## multiFuzzyMatchAllIndices
2023-04-20 09:30:11 +00:00
Like `multiFuzzyMatchAny` but returns the array of all indices in any order that match the haystack within a constant edit distance.
2023-04-20 09:30:11 +00:00
**Syntax**
2023-04-20 09:30:11 +00:00
```sql
multiFuzzyMatchAllIndices(haystack, distance, \[pattern<sub>1</sub>, pattern<sub>2</sub>, …, pattern<sub>n</sub>\])
```
2023-04-20 09:30:11 +00:00
## extract
2023-04-20 09:30:11 +00:00
Extracts a fragment of a string using a regular expression. If `haystack` does not match the `pattern` regex, an empty string is returned.
2019-03-29 01:02:05 +00:00
2023-04-20 09:30:11 +00:00
For regex without subpatterns, the function uses the fragment that matches the entire regex. Otherwise, it uses the fragment that matches the first subpattern.
2019-03-29 01:02:05 +00:00
2023-04-20 09:30:11 +00:00
**Syntax**
2019-03-29 01:02:05 +00:00
2023-04-20 09:30:11 +00:00
```sql
extract(haystack, pattern)
```
2019-03-29 01:02:05 +00:00
2023-04-20 09:30:11 +00:00
## extractAll
2023-04-20 09:30:11 +00:00
Extracts all fragments of a string using a regular expression. If `haystack` does not match the `pattern` regex, an empty string is returned.
2023-04-20 09:30:11 +00:00
Returns an array of strings consisting of all matches of the regex.
2023-04-20 09:30:11 +00:00
The behavior with respect to subpatterns is the same as in function `extract`.
2023-04-20 09:30:11 +00:00
**Syntax**
2023-04-20 09:30:11 +00:00
```sql
extractAll(haystack, pattern)
```
2022-06-02 10:55:18 +00:00
## extractAllGroupsHorizontal
2021-07-29 15:27:50 +00:00
Matches all groups of the `haystack` string using the `pattern` regular expression. Returns an array of arrays, where the first array includes all fragments matching the first group, the second array - matching the second group, etc.
2023-04-20 09:30:11 +00:00
This function is slower than [extractAllGroupsVertical](#extractallgroups-vertical).
2021-07-29 15:20:55 +00:00
**Syntax**
``` sql
extractAllGroupsHorizontal(haystack, pattern)
```
2021-07-29 15:20:55 +00:00
**Arguments**
- `haystack` — Input string. Type: [String](../../sql-reference/data-types/string.md).
- `pattern` — Regular expression with [re2 syntax](https://github.com/google/re2/wiki/Syntax). Must contain groups, each group enclosed in parentheses. If `pattern` contains no groups, an exception is thrown. Type: [String](../../sql-reference/data-types/string.md).
**Returned value**
- Type: [Array](../../sql-reference/data-types/array.md).
2021-07-29 15:20:55 +00:00
If `haystack` does not match the `pattern` regex, an array of empty arrays is returned.
**Example**
``` sql
SELECT extractAllGroupsHorizontal('abc=111, def=222, ghi=333', '("[^"]+"|\\w+)=("[^"]+"|\\w+)');
```
Result:
``` text
┌─extractAllGroupsHorizontal('abc=111, def=222, ghi=333', '("[^"]+"|\\w+)=("[^"]+"|\\w+)')─┐
│ [['abc','def','ghi'],['111','222','333']] │
└──────────────────────────────────────────────────────────────────────────────────────────┘
```
2022-06-02 10:55:18 +00:00
## extractAllGroupsVertical
Matches all groups of the `haystack` string using the `pattern` regular expression. Returns an array of arrays, where each array includes matching fragments from every group. Fragments are grouped in order of appearance in the `haystack`.
2021-07-29 15:20:55 +00:00
**Syntax**
``` sql
extractAllGroupsVertical(haystack, pattern)
```
2021-07-29 15:20:55 +00:00
**Arguments**
- `haystack` — Input string. Type: [String](../../sql-reference/data-types/string.md).
- `pattern` — Regular expression with [re2 syntax](https://github.com/google/re2/wiki/Syntax). Must contain groups, each group enclosed in parentheses. If `pattern` contains no groups, an exception is thrown. Type: [String](../../sql-reference/data-types/string.md).
**Returned value**
- Type: [Array](../../sql-reference/data-types/array.md).
2021-07-29 15:20:55 +00:00
If `haystack` does not match the `pattern` regex, an empty array is returned.
**Example**
``` sql
SELECT extractAllGroupsVertical('abc=111, def=222, ghi=333', '("[^"]+"|\\w+)=("[^"]+"|\\w+)');
```
Result:
``` text
┌─extractAllGroupsVertical('abc=111, def=222, ghi=333', '("[^"]+"|\\w+)=("[^"]+"|\\w+)')─┐
│ [['abc','111'],['def','222'],['ghi','333']] │
└────────────────────────────────────────────────────────────────────────────────────────┘
```
2023-04-20 09:30:11 +00:00
## like
2023-04-20 09:30:11 +00:00
Returns whether string `haystack` matches the LIKE expression `pattern`.
2023-04-20 09:30:11 +00:00
A LIKE expression can contain normal characters and the following metasymbols:
- `%` indicates an arbitrary number of arbitrary characters (including zero characters).
- `_` indicates a single arbitrary character.
- `\` is for escaping literals `%`, `_` and `\`.
2022-06-17 13:26:59 +00:00
Matching is based on UTF-8, e.g. `_` matches the Unicode code point `¥` which is represented in UTF-8 using two bytes.
2023-04-20 09:30:11 +00:00
If the haystack or the LIKE expression are not valid UTF-8, the behavior is undefined.
2023-04-20 09:30:11 +00:00
No automatic Unicode normalization is performed, you can use the [normalizeUTF8*()](https://clickhouse.com/docs/en/sql-reference/functions/string-functions/) functions for that.
2023-04-20 09:30:11 +00:00
To match against literal `%`, `_` and `/` (which are LIKE metacharacters), prepend them with a backslash: `\%`, `\_` and `\\`.
The backslash loses its special meaning (i.e. is interpreted literally) if it prepends a character different than `%`, `_` or `\`.
Note that ClickHouse requires backslashes in strings [to be quoted as well](../syntax.md#string), so you would actually need to write `\\%`, `\\_` and `\\\\`.
2023-04-20 09:30:11 +00:00
For LIKE expressions of the form `%needle%`, the function is as fast as the `position` function.
All other LIKE expressions are internally converted to a regular expression and executed with a performance similar to function `match`.
2022-06-17 13:26:59 +00:00
**Syntax**
2023-04-20 09:30:11 +00:00
```sql
like(haystack, pattern)
```
2023-04-20 09:30:11 +00:00
Alias: `haystack LIKE pattern` (operator)
2023-04-20 09:30:11 +00:00
## notLike
2023-04-20 09:30:11 +00:00
Like `like` but negates the result.
2023-04-20 09:30:11 +00:00
Alias: `haystack NOT LIKE pattern` (operator)
2023-04-20 09:30:11 +00:00
## ilike
2023-04-20 09:30:11 +00:00
Like `like` but searches case-insensitively.
2023-04-20 09:30:11 +00:00
Alias: `haystack ILIKE pattern` (operator)
2023-04-20 09:30:11 +00:00
## notILike
2023-04-20 09:30:11 +00:00
Like `ilike` but negates the result.
2023-04-20 09:30:11 +00:00
Alias: `haystack NOT ILIKE pattern` (operator)
2023-04-20 09:30:11 +00:00
## ngramDistance
2023-01-09 14:13:36 +00:00
2023-04-20 09:30:11 +00:00
Calculates the 4-gram distance between a `haystack` string and a `needle` string. For that, it counts the symmetric difference between two multisets of 4-grams and normalizes it by the sum of their cardinalities. Returns a Float32 between 0 and 1. The smaller the result is, the more strings are similar to each other. Throws an exception if constant `needle` or `haystack` arguments are more than 32Kb in size. If any of non-constant `haystack` or `needle` arguments is more than 32Kb in size, the distance is always 1.
2023-04-20 09:30:11 +00:00
Functions `ngramDistanceCaseInsensitive, ngramDistanceUTF8, ngramDistanceCaseInsensitiveUTF8` provide case-insensitive and/or UTF-8 variants of this function.
2023-04-20 09:30:11 +00:00
**Syntax**
2023-04-20 09:30:11 +00:00
```sql
ngramDistance(haystack, needle)
```
2023-04-20 09:30:11 +00:00
## ngramSearch
2023-04-20 09:30:11 +00:00
Like `ngramDistance` but calculates the non-symmetric difference between a `needle` string and a `haystack` string, i.e. the number of n-grams from needle minus the common number of n-grams normalized by the number of `needle` n-grams. Returns a Float32 between 0 and 1. The bigger the result is, the more likely `needle` is in the `haystack`. This function is useful for fuzzy string search. Also see function `soundex`.
2019-05-25 18:47:26 +00:00
2023-04-20 09:30:11 +00:00
Functions `ngramSearchCaseInsensitive, ngramSearchUTF8, ngramSearchCaseInsensitiveUTF8` provide case-insensitive and/or UTF-8 variants of this function.
2019-05-25 18:47:26 +00:00
2022-06-17 13:26:59 +00:00
:::note
2023-04-20 09:30:11 +00:00
The UTF-8 variants use the 3-gram distance. These are not perfectly fair n-gram distances. We use 2-byte hashes to hash n-grams and then calculate the (non-)symmetric difference between these hash tables collisions may occur. With UTF-8 case-insensitive format we do not use fair `tolower` function we zero the 5-th bit (starting from zero) of each codepoint byte and first bit of zeroth byte if bytes more than one this works for Latin and mostly for all Cyrillic letters.
:::
2023-04-20 09:30:11 +00:00
**Syntax**
```sql
ngramSearch(haystack, needle)
```
2022-06-02 10:55:18 +00:00
## countSubstrings
2023-04-20 09:30:11 +00:00
Returns how often substring `needle` occurs in string `haystack`.
2023-04-20 09:30:11 +00:00
Functions `countSubstringsCaseInsensitive` and `countSubstringsCaseInsensitiveUTF8` provide a case-insensitive and case-insensitive + UTF-8 variants of this function.
**Syntax**
``` sql
countSubstrings(haystack, needle[, start_pos])
```
**Arguments**
2023-04-20 09:30:11 +00:00
- `haystack` — String in which the search is performed. [String](../../sql-reference/syntax.md#syntax-string-literal).
- `needle` — Substring to be searched. [String](../../sql-reference/syntax.md#syntax-string-literal).
- `start_pos` Position (1-based) in `haystack` at which the search starts. [UInt](../../sql-reference/data-types/int-uint.md). Optional.
**Returned values**
2023-04-20 09:30:11 +00:00
- The number of occurrences.
2021-01-13 21:13:36 +00:00
Type: [UInt64](../../sql-reference/data-types/int-uint.md).
**Examples**
``` sql
2020-12-29 10:54:17 +00:00
SELECT countSubstrings('aaaa', 'aa');
```
Result:
``` text
┌─countSubstrings('aaaa', 'aa')─┐
│ 2 │
└───────────────────────────────┘
```
2023-04-20 09:30:11 +00:00
Example with `start_pos` argument:
2020-12-29 10:54:17 +00:00
```sql
SELECT countSubstrings('abc___abc', 'abc', 4);
```
Result:
``` text
┌─countSubstrings('abc___abc', 'abc', 4)─┐
│ 1 │
└────────────────────────────────────────┘
```
2023-04-20 09:30:11 +00:00
## countMatches
Returns the number of regular expression matches for a `pattern` in a `haystack`.
2020-12-29 10:54:17 +00:00
**Syntax**
``` sql
countMatches(haystack, pattern)
```
**Arguments**
- `haystack` — The string to search in. [String](../../sql-reference/syntax.md#syntax-string-literal).
- `pattern` — The regular expression with [re2 syntax](https://github.com/google/re2/wiki/Syntax). [String](../../sql-reference/data-types/string.md).
**Returned value**
- The number of matches.
Type: [UInt64](../../sql-reference/data-types/int-uint.md).
**Examples**
``` sql
SELECT countMatches('foobar.com', 'o+');
```
Result:
``` text
┌─countMatches('foobar.com', 'o+')─┐
│ 2 │
└──────────────────────────────────┘
```
``` sql
SELECT countMatches('aaaa', 'aa');
```
Result:
``` text
┌─countMatches('aaaa', 'aa')────┐
│ 2 │
└───────────────────────────────┘
```
2023-02-16 09:33:51 +00:00
2023-04-20 09:30:11 +00:00
## regexpExtract
2023-02-16 09:33:51 +00:00
Extracts the first string in haystack that matches the regexp pattern and corresponds to the regex group index.
**Syntax**
``` sql
regexpExtract(haystack, pattern[, index])
```
Alias: `REGEXP_EXTRACT(haystack, pattern[, index])`.
**Arguments**
- `haystack` — String, in which regexp pattern will to be matched. [String](../../sql-reference/syntax.md#syntax-string-literal).
- `pattern` — String, regexp expression, must be constant. [String](../../sql-reference/syntax.md#syntax-string-literal).
- `index` An integer number greater or equal 0 with default 1. It represents which regex group to extract. [UInt or Int](../../sql-reference/data-types/int-uint.md). Optional.
2023-02-16 09:33:51 +00:00
**Returned values**
`pattern` may contain multiple regexp groups, `index` indicates which regex group to extract. An index of 0 means matching the entire regular expression.
Type: `String`.
**Examples**
``` sql
SELECT
regexpExtract('100-200', '(\\d+)-(\\d+)', 1),
regexpExtract('100-200', '(\\d+)-(\\d+)', 2),
regexpExtract('100-200', '(\\d+)-(\\d+)', 0),
2023-04-20 09:30:11 +00:00
regexpExtract('100-200', '(\\d+)-(\\d+)');
```
2023-02-16 09:33:51 +00:00
2023-04-20 09:30:11 +00:00
Result:
``` text
2023-02-16 09:33:51 +00:00
┌─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 │
└──────────────────────────────────────────────┴──────────────────────────────────────────────┴──────────────────────────────────────────────┴───────────────────────────────────────────┘
```
2023-07-06 19:43:37 +00:00
## hasSubsequence
Returns 1 if needle is a subsequence of haystack, or 0 otherwise.
A subsequence of a string is a sequence that can be derived from the given string by deleting zero or more elements without changing the order of the remaining elements.
**Syntax**
``` sql
hasSubsequence(haystack, needle)
```
**Arguments**
- `haystack` — String in which the search is performed. [String](../../sql-reference/syntax.md#syntax-string-literal).
2023-07-10 09:18:09 +00:00
- `needle` — Subsequence to be searched. [String](../../sql-reference/syntax.md#syntax-string-literal).
2023-07-06 19:43:37 +00:00
**Returned values**
- 1, if needle is a subsequence of haystack.
- 0, otherwise.
Type: `UInt8`.
**Examples**
``` sql
SELECT hasSubsequence('garbage', 'arg') ;
```
Result:
``` text
┌─hasSubsequence('garbage', 'arg')─┐
│ 1 │
└──────────────────────────────────┘
```
## hasSubsequenceCaseInsensitive
Like [hasSubsequence](#hasSubsequence) but searches case-insensitively.
## hasSubsequenceUTF8
Like [hasSubsequence](#hasSubsequence) but assumes `haystack` and `needle` are UTF-8 encoded strings.
## hasSubsequenceCaseInsensitiveUTF8
2023-09-22 17:48:17 +00:00
Like [hasSubsequenceUTF8](#hasSubsequenceUTF8) but searches case-insensitively.