> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Documentação das funções de busca em strings
# Funções de busca em strings
Todas as funções nesta seção fazem buscas com diferenciação entre maiúsculas e minúsculas por padrão. A busca sem diferenciar maiúsculas de minúsculas geralmente é oferecida por variantes separadas da função.
A busca sem diferenciar maiúsculas de minúsculas segue as regras de conversão entre minúsculas e maiúsculas do idioma inglês. Por exemplo, o `i` maiúsculo em inglês é
`I`, enquanto em turco é `İ` — os resultados para idiomas diferentes do inglês podem ser inesperados.
As funções nesta seção também pressupõem que a string pesquisada (chamada nesta seção de `haystack`) e a string de busca (chamada nesta seção de `needle`) sejam textos codificados em byte único. Se essa suposição for
violada, nenhuma exceção é gerada e os resultados são indefinidos. A busca com strings codificadas em UTF-8 geralmente é oferecida por variantes separadas da função. Da mesma forma, se uma variante de função UTF-8 for usada e as strings de entrada não forem texto codificado em UTF-8, nenhuma exceção é gerada e os
resultados são indefinidos. Observe que nenhuma normalização Unicode automática é realizada; no entanto, você pode usar as funções
[normalizeUTF8\*()](/pt-BR/reference/functions/regular-functions/string-functions#normalizeUTF8NFC) para isso.
[Funções gerais de strings](/pt-BR/reference/functions/regular-functions/string-functions) e [funções de substituição em strings](/pt-BR/reference/functions/regular-functions/string-replace-functions) são descritas separadamente.
A documentação abaixo é gerada a partir da tabela de sistema `system.functions`.
{/*AUTOGENERATED_START*/}
## countMatches
Introduzido em: v21.1.0
Retorna o número de correspondências de uma expressão regular em uma string.
**Comportamento dependente da versão**
O comportamento desta função depende da versão do ClickHouse:
* em versões \< v25.6, a função para de contar na primeira correspondência vazia, mesmo que o padrão a aceite.
* em versões >= 25.6, a função continua a execução quando ocorre uma correspondência vazia. O comportamento legado pode ser restaurado usando a configuração `count_matches_stop_at_empty_match = true`;
**Sintaxe**
```sql theme={null}
countMatches(haystack, pattern)
```
**Argumentos**
* `haystack` — A string na qual pesquisar. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — Padrão de expressão regular. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o número de correspondências encontradas. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Contar sequências de dígitos**
```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
Introduzido em: v21.1.0
Semelhante a [`countMatches`](#countMatches), mas faz correspondência sem diferenciar maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
countMatchesCaseInsensitive(haystack, pattern)
```
**Argumentos**
* `haystack` — A string na qual pesquisar. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — Padrão de expressão regular. [`const String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o número de correspondências encontradas. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Contagem sem diferenciar maiúsculas de minúsculas**
```sql title=Query theme={null}
SELECT countMatchesCaseInsensitive('Hello HELLO world', 'hello')
```
```response title=Response theme={null}
┌─countMatchesCaseInsensitive('Hello HELLO world', 'hello')─┐
│ 2 │
└───────────────────────────────────────────────────────────┘
```
## countSubstrings
Introduzido em: v21.1.0
Retorna quantas vezes a substring `needle` ocorre na string `haystack`.
**Sintaxe**
```sql theme={null}
countSubstrings(haystack, needle[, start_pos])
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [String](/pt-BR/reference/data-types/string) ou [Enum](/pt-BR/reference/data-types/enum). - `needle` — Substring a ser pesquisada. [String](/pt-BR/reference/data-types/string). - `start_pos` — Posição (baseada em 1) em `haystack` na qual a busca se inicia. [UInt](/pt-BR/reference/data-types/int-uint). Opcional.
**Valor retornado**
O número de ocorrências. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT countSubstrings('aaaa', 'aa');
```
```response title=Response theme={null}
┌─countSubstrings('aaaa', 'aa')─┐
│ 2 │
└───────────────────────────────┘
```
**Com o argumento 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
Introduzido em: v21.1.0
Semelhante a [`countSubstrings`](#countSubstrings), mas conta sem diferenciar maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
countSubstringsCaseInsensitive(haystack, needle[, start_pos])
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string) ou [`Enum`](/pt-BR/reference/data-types/enum)
* `needle` — Substring a ser buscada. [`String`](/pt-BR/reference/data-types/string)
* `start_pos` — Opcional. Posição (baseada em 1) em `haystack` na qual a busca começa. [`UInt*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna o número de ocorrências da substring em `haystack`. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT countSubstringsCaseInsensitive('AAAA', 'aa');
```
```response title=Response theme={null}
┌─countSubstri⋯AAA', 'aa')─┐
│ 2 │
└──────────────────────────┘
```
**Com o argumento start\_pos**
```sql title=Query theme={null}
SELECT countSubstringsCaseInsensitive('abc___ABC___abc', 'abc', 4);
```
```response title=Response theme={null}
┌─countSubstri⋯, 'abc', 4)─┐
│ 2 │
└──────────────────────────┘
```
## countSubstringsCaseInsensitiveUTF8
Introduzido em: v21.1.0
Como [`countSubstrings`](#countSubstrings), mas conta sem diferenciar maiúsculas de minúsculas e pressupõe que o haystack seja uma string UTF-8.
**Sintaxe**
```sql theme={null}
countSubstringsCaseInsensitiveUTF8(haystack, needle[, start_pos])
```
**Argumentos**
* `haystack` — String UTF-8 na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string) ou [`Enum`](/pt-BR/reference/data-types/enum)
* `needle` — Substring a ser pesquisada. [`String`](/pt-BR/reference/data-types/string)
* `start_pos` — Opcional. Posição (começando em 1) em `haystack` na qual a busca se inicia. [`UInt*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna o número de ocorrências de `needle` em `haystack`. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT countSubstringsCaseInsensitiveUTF8('ложка, кошка, картошка', 'КА');
```
```response title=Response theme={null}
┌─countSubstri⋯шка', 'КА')─┐
│ 4 │
└──────────────────────────┘
```
**Com o argumento start\_pos**
```sql title=Query theme={null}
SELECT countSubstringsCaseInsensitiveUTF8('ложка, кошка, картошка', 'КА', 13);
```
```response title=Response theme={null}
┌─countSubstri⋯, 'КА', 13)─┐
│ 2 │
└──────────────────────────┘
```
Introduzido em: v1.1.0
Extrai a primeira correspondência de uma expressão regular em uma string.
Se 'haystack' não corresponder a 'pattern', uma string vazia será retornada.
Esta função usa a biblioteca de expressões regulares RE2. Consulte [re2](https://github.com/google/re2/wiki/Syntax) para conhecer a sintaxe compatível.
Se a expressão regular tiver grupos de captura (subpadrões), a função faz a correspondência da string de entrada com o primeiro grupo de captura.
**Sintaxe**
```sql theme={null}
extract(haystack, pattern)
```
**Argumentos**
* `haystack` — String de onde extrair. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — Expressão regular, normalmente contendo um grupo de captura. [`const String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o fragmento extraído como string. [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Extrair domínio de um e-mail**
```sql title=Query theme={null}
SELECT extract('test@clickhouse.com', '.*@(.*)$')
```
```response title=Response theme={null}
┌─extract('test@clickhouse.com', '.*@(.*)$')─┐
│ clickhouse.com │
└───────────────────────────────────────────┘
```
**Sem correspondência, retorna string vazia**
```sql title=Query theme={null}
SELECT extract('test@clickhouse.com', 'no_match')
```
```response title=Response theme={null}
┌─extract('test@clickhouse.com', 'no_match')─┐
│ │
└────────────────────────────────────────────┘
```
Introduzido em: v1.1.0
Semelhante a [`extract`](#extract), mas retorna um array com todas as correspondências de uma expressão regular em uma string.
Se 'haystack' não corresponder à regex 'pattern', será retornado um array vazio.
Se a expressão regular tiver grupos de captura (subpadrões), a função faz a correspondência da string de entrada com o primeiro grupo de captura.
**Sintaxe**
```sql theme={null}
extractAll(haystack, pattern)
```
**Argumentos**
* `haystack` — String da qual os fragmentos são extraídos. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — Expressão regular, opcionalmente contendo grupos de captura. [`const String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um array com os fragmentos extraídos. [`Array(String)`](/pt-BR/reference/data-types/array)
**Exemplos**
**Extrair todos os números**
```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'] │
└─────────────────────────────────────────────┘
```
**Extrair usando um grupo de captura**
```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'] │
└────────────────────────────────────────────────────────────────────┘
```
Introduzido em: v20.5.0
Encontra todos os grupos em uma string usando a expressão regular fornecida e retorna um array de arrays, em que cada array contém todas as capturas do mesmo grupo de captura, organizadas pelo número do grupo.
**Sintaxe**
```sql theme={null}
extractAllGroupsHorizontal(s, regexp)
```
**Argumentos**
* `s` — String de entrada da qual extrair os dados. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `regexp` — Expressão regular usada para fazer a correspondência. [`const String`](/pt-BR/reference/data-types/string) ou [`const FixedString`](/pt-BR/reference/data-types/fixedstring)
**Valor retornado**
Retorna um array de arrays, em que cada array interno contém todas as capturas de um grupo de captura em todas as correspondências. O primeiro array interno contém todas as capturas do grupo 1, o segundo do grupo 2, e assim por diante. Se nenhuma correspondência for encontrada, retorna um array vazio. [`Array(Array(String))`](/pt-BR/reference/data-types/array)
**Exemplos**
**Exemplo de uso**
```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']]
```
Introduzido em: v20.5.0
Extrai os grupos de captura da primeira substring correspondente a uma expressão regular. Para extrair grupos de todas as correspondências, use [`extractAllGroupsHorizontal`](#extractAllGroupsHorizontal) ou [`extractAllGroupsVertical`](/pt-BR/reference/functions/regular-functions/splitting-merging-functions#extractAllGroupsVertical).
**Sintaxe**
```sql theme={null}
extractGroups(s, regexp)
```
**Argumentos**
* `s` — String de entrada da qual extrair. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `regexp` — Expressão regular. Deve conter pelo menos um grupo de captura. Constante. [`const String`](/pt-BR/reference/data-types/string) ou [`const FixedString`](/pt-BR/reference/data-types/fixedstring)
**Valor retornado**
Se a expressão regular encontrar correspondência, retorna um array contendo os grupos capturados (`1` a `N`, em que `N` é o número de grupos de captura em `regexp`) da primeira correspondência. Se não houver correspondência, retorna um array vazio. [`Array(String)`](/pt-BR/reference/data-types/array)
**Exemplos**
**Exemplo de uso**
```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
Introduzido em: v25.10.0
Semelhante a [`hasAnyTokens`](#hasAnyTokens), mas retorna 1 se todos os tokens na string ou array `needle` corresponderem à string `input`, e 0 caso contrário. Se `input` for uma coluna, retorna todas as linhas que satisfazem essa condição.
A coluna `input` deve ter um [índice de texto](/pt-BR/reference/engines/table-engines/mergetree-family/textindexes) definido para desempenho ideal.
Se nenhum índice de texto estiver definido, a função fará uma varredura exaustiva da coluna, o que é várias ordens de magnitude mais lento do que uma consulta por índice.
Antes de realizar a busca, a função tokeniza
* o argumento `input` (sempre), e
* o argumento `needle` (se fornecido como [String](/pt-BR/reference/data-types/string))
usa o tokenizador especificado para o índice de texto.
Se a coluna não tiver nenhum índice de texto definido, o tokenizador `splitByNonAlpha` será usado.
Se o argumento `needle` for do tipo [Array(String)](/pt-BR/reference/data-types/array), cada elemento do array será tratado como um token — não haverá tokenização adicional.
Tokens duplicados são ignorados.
Por exemplo, needles = \['ClickHouse', 'ClickHouse'] é considerado igual a \['ClickHouse'].
Quando um índice de texto define um [pré-processador](/pt-BR/reference/engines/table-engines/mergetree-family/textindexes#creating-a-text-index) (por exemplo, `lowerUTF8`), `hasAllTokens` o aplica a `input` e, quando `needles` é uma [String](/pt-BR/reference/data-types/string), a `needles` antes da tokenização. Quando `needles` é um [Array(String)](/pt-BR/reference/data-types/array), seus elementos são passados como estão, e o pré-processador não é aplicado a eles.
O pré-processador é aplicado apenas no caminho do índice de texto, portanto os resultados podem diferir entre consultas que usam o índice de texto e consultas que não o usam (por exemplo, `SETTINGS use_skip_indexes = 0`).
Essa inconsistência é tolerada para melhorar a usabilidade da busca de texto completo.
**Sintaxe**
```sql theme={null}
hasAllTokens(input, needles)
```
**Aliases**: `hasAllToken`
**Argumentos**
* `input` — A coluna de entrada. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring) ou [`Array(String)`](/pt-BR/reference/data-types/array) ou [`Array(FixedString)`](/pt-BR/reference/data-types/array)
* `needles` — tokens a serem buscados. [`String`](/pt-BR/reference/data-types/string) ou [`Array(String)`](/pt-BR/reference/data-types/array)
* `tokenizer` — O tokenizador a ser usado. Os argumentos válidos são `splitByNonAlpha`, `splitByString`, `asciiCJK`, `ngrams`, `sparseGrams` e `array`. Opcional; se não for definido explicitamente, o valor padrão é `splitByNonAlpha`. [`const String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna 1 se todas as needles corresponderem; 0 caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Uso básico com uma needle do tipo String**
```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 │
└─────────┘
```
**Especifique os needles a serem pesquisados exatamente como estão (sem tokenização) em um array**
```sql title=Query theme={null}
SELECT count() FROM table WHERE hasAllTokens(msg, ['a', 'd']);
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**Gere agulhas usando a função `tokens`**
```sql title=Query theme={null}
SELECT count() FROM table WHERE hasAllTokens(msg, tokens('a()d', 'splitByString', ['()', '\\']));
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**Use um tokenizador personalizado via o 3º argumento**
```sql title=Query theme={null}
SELECT hasAllTokens('abcdef', 'abc', 'ngrams(3)');
```
```response title=Response theme={null}
┌─hasAllTokens('abcdef', 'abc', 'ngrams(3)')─┐
│ 1 │
└──────────────────────────────────────────────┘
```
**Exemplos de uso para colunas array e 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}
```
**Exemplo com uma coluna do tipo array**
```sql title=Query theme={null}
SELECT count() FROM log WHERE hasAllTokens(tags, 'clickhouse');
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**Exemplo com mapKeys**
```sql title=Query theme={null}
SELECT count() FROM log WHERE hasAllTokens(mapKeys(attributes), ['address', 'log_level']);
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**Exemplo com 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
Introduzido em: v25.10.0
Retorna 1 se pelo menos um token da string ou array `needle` corresponder à string `input`, e 0 caso contrário. Se `input` for uma coluna, retorna todas as linhas que satisfazem essa condição.
A coluna `input` deve ter um [índice de texto](/pt-BR/reference/engines/table-engines/mergetree-family/textindexes) definido para um desempenho ideal.
Se nenhum índice de texto estiver definido, a função realiza uma varredura exaustiva da coluna, que é várias ordens de magnitude mais lenta que uma busca no índice.
Antes de realizar a busca, a função tokeniza
* o argumento `input` (sempre), e
* o argumento `needle` (se fornecido como [String](/pt-BR/reference/data-types/string))
usando o tokenizador especificado para o índice de texto.
Se a coluna não tiver um índice de texto definido, o tokenizador `splitByNonAlpha` será usado.
Se o argumento `needle` for do tipo [Array(String)](/pt-BR/reference/data-types/array), cada elemento do array será tratado como um token — não haverá tokenização adicional.
Tokens duplicados são ignorados.
Por exemplo, \['ClickHouse', 'ClickHouse'] é tratado da mesma maneira que \['ClickHouse'].
Quando um índice de texto define um [pré-processador](/pt-BR/reference/engines/table-engines/mergetree-family/textindexes#creating-a-text-index) (por exemplo, `lowerUTF8`), `hasAnyTokens` o aplica a `input` e, quando `needles` é uma [String](/pt-BR/reference/data-types/string), a `needles` antes da tokenização. Quando `needles` é um [Array(String)](/pt-BR/reference/data-types/array), seus elementos são usados como estão, e o pré-processador não é aplicado a eles.
O pré-processador é aplicado apenas no caminho do índice de texto, portanto os resultados podem diferir entre consultas que usam o índice de texto e consultas que não o usam (por exemplo, `SETTINGS use_skip_indexes = 0`).
Essa inconsistência é tolerada para melhorar a usabilidade da busca de texto completo.
**Sintaxe**
```sql theme={null}
hasAnyTokens(input, needles)
```
**Aliases**: `hasAnyToken`
**Argumentos**
* `input` — A coluna de entrada. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring) ou [`Nullable(String)`](/pt-BR/reference/data-types/nullable) ou [`Nullable(FixedString)`](/pt-BR/reference/data-types/nullable) ou [`Array(String)`](/pt-BR/reference/data-types/array) ou [`Array(FixedString)`](/pt-BR/reference/data-types/array) ou [`Array(Nullable(String))`](/pt-BR/reference/data-types/array) ou [`Array(Nullable(FixedString))`](/pt-BR/reference/data-types/array)
* `needles` — tokens a serem procurados. [`String`](/pt-BR/reference/data-types/string) ou [`Array(String)`](/pt-BR/reference/data-types/array)
* `tokenizer` — O tokenizador a ser utilizado. Os argumentos válidos são `splitByNonAlpha`, `splitByString`, `asciiCJK`, `ngrams`, `sparseGrams` e `array`. Opcional; se não for definido explicitamente, o valor padrão é `splitByNonAlpha`. [`const String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se houver pelo menos uma correspondência. Caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Uso básico com uma substring**
```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 │
└─────────┘
```
**Especifique os needles a serem pesquisados exatamente como estão (sem tokenização) em um array**
```sql title=Query theme={null}
SELECT count() FROM table WHERE hasAnyTokens(msg, ['a', 'd']);
```
```response title=Response theme={null}
┌─count()─┐
│ 3 │
└─────────┘
```
**Gere agulhas usando a função `tokens`**
```sql title=Query theme={null}
SELECT count() FROM table WHERE hasAnyTokens(msg, tokens('a()d', 'splitByString', ['()', '\\']));
```
```response title=Response theme={null}
┌─count()─┐
│ 3 │
└─────────┘
```
**Exemplos de uso para colunas array e 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}
```
**Exemplo com uma coluna de array**
```sql title=Query theme={null}
SELECT count() FROM log WHERE hasAnyTokens(tags, 'clickhouse');
```
```response title=Response theme={null}
┌─count()─┐
│ 1 │
└─────────┘
```
**Exemplo com mapKeys**
```sql title=Query theme={null}
SELECT count() FROM log WHERE hasAnyTokens(mapKeys(attributes), ['address', 'log_level']);
```
```response title=Response theme={null}
┌─count()─┐
│ 2 │
└─────────┘
```
**Exemplo com 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
Introduzido em: v26.4.0
Verifica se o `input` contém todos os tokens da `phrase` em ordem consecutiva.
A coluna `input` deve ter um [índice de texto](/pt-BR/reference/engines/table-engines/mergetree-family/textindexes) definido para desempenho ideal.
Se nenhum índice de texto for definido, a função executa uma varredura exaustiva da coluna, que é várias ordens de magnitude mais lenta do que uma consulta ao índice.
Antes da pesquisa, a função tokeniza os argumentos `input` e `phrase` usando o tokenizador especificado para o índice de texto.
Se a coluna não tiver nenhum índice de texto definido, o tokenizador `splitByNonAlpha` será usado — a menos que um tokenizador seja fornecido como terceiro argumento opcional.
O argumento `tokenizer` deve ser um de `splitByNonAlpha`, `splitByString`, `ngrams` ou `asciiCJK`.
Quando um índice de texto define um [pré-processador](/pt-BR/reference/engines/table-engines/mergetree-family/textindexes#creating-a-text-index) (por exemplo, `lowerUTF8`), `hasPhrase` o aplica tanto a `input` quanto a `phrase` antes da tokenização.
O pré-processador é aplicado apenas no caminho do índice de texto, portanto os resultados podem diferir entre consultas que usam o índice de texto e consultas que não o usam (por exemplo, `SETTINGS use_skip_indexes = 0`).
Essa inconsistência é tolerada para melhorar a usabilidade da busca de texto completo.
Diferentemente de [`hasToken`](#hasToken), [`hasAnyTokens`](#hasAnyTokens) e [`hasAllTokens`](#hasAllTokens), `hasPhrase` exige que os tokens apareçam na mesma ordem
e sem nenhum token entre eles. Por exemplo, `hasPhrase('the quick brown fox', 'quick fox')` retorna 0
porque "brown" aparece entre "quick" e "fox".
**Sintaxe**
```sql theme={null}
hasPhrase(input, phrase[, tokenizer])
```
**Aliases**: `matchPhrase`
**Argumentos**
* `input` — A coluna de entrada. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `phrase` — Frase a ser buscada. [`const String`](/pt-BR/reference/data-types/string)
* `tokenizer` — O tokenizador a ser usado. Opcional; o padrão é `splitByNonAlpha`. [`const String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se a frase for encontrada como uma sequência contínua de tokens; caso contrário, retorna `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Correspondência por frase**
```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 │
└────────────────────────────────────────────────────────┘
```
**Tokens não consecutivos**
```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
Introduzido em: v23.7.0
Verifica se uma needle é uma subsequência de uma haystack.
Uma subsequência de uma string é uma sequência que pode ser derivada de outra string pela remoção de alguns caracteres, ou de nenhum, sem alterar a ordem dos caracteres restantes.
**Sintaxe**
```sql theme={null}
hasSubsequence(haystack, needle)
```
**Argumentos**
* `haystack` — String em que a subsequência será pesquisada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Subsequência a ser pesquisada. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se `needle` for uma subsequência de `haystack`; caso contrário, retorna `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Verificação básica de subsequência**
```sql title=Query theme={null}
SELECT hasSubsequence('Hello World', 'HlWrd')
```
```response title=Response theme={null}
┌─hasSubsequence('Hello World', 'HlWrd')─┐
│ 1 │
└────────────────────────────────────────┘
```
**Nenhuma subsequência encontrada**
```sql title=Query theme={null}
SELECT hasSubsequence('Hello World', 'xyz')
```
```response title=Response theme={null}
┌─hasSubsequence('Hello World', 'xyz')─┐
│ 0 │
└──────────────────────────────────────┘
```
## hasSubsequenceCaseInsensitive
Introduzido em: v23.7.0
Como [`hasSubsequence`](#hasSubsequence), mas faz a busca sem diferenciar maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
hasSubsequenceCaseInsensitive(haystack, needle)
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Subsequência a ser procurada. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna 1 se needle for uma subsequência de haystack e 0 caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT hasSubsequenceCaseInsensitive('garbage', 'ARG');
```
```response title=Response theme={null}
┌─hasSubsequenceCaseInsensitive('garbage', 'ARG')─┐
│ 1 │
└─────────────────────────────────────────────────┘
```
## hasSubsequenceCaseInsensitiveUTF8
Introduzido em: v23.7.0
Como [`hasSubsequenceUTF8`](#hasSubsequenceUTF8), mas faz a busca sem diferenciar maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
hasSubsequenceCaseInsensitiveUTF8(haystack, needle)
```
**Argumentos**
* `haystack` — String codificada em UTF-8 na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Subsequência codificada em UTF-8 a ser buscada. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna 1 se `needle` for uma subsequência de `haystack`, 0 caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT hasSubsequenceCaseInsensitiveUTF8('ClickHouse - столбцовая система управления базами данных', 'СИСТЕМА');
```
```response title=Response theme={null}
┌─hasSubsequen⋯ 'СИСТЕМА')─┐
│ 1 │
└──────────────────────────┘
```
## hasSubsequenceUTF8
Introduzido em: v23.7.0
Como [`hasSubsequence`](/pt-BR/reference/functions/regular-functions/string-search-functions#hasSubsequence), mas considera que haystack e needle são strings codificadas em UTF-8.
**Sintaxe**
```sql theme={null}
hasSubsequenceUTF8(haystack, needle)
```
**Argumentos**
* `haystack` — A string em que a busca é feita. [`String`](/pt-BR/reference/data-types/string)
* `needle` — A subsequência a ser procurada. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se `needle` for uma subsequência de `haystack`; caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT hasSubsequenceUTF8('картошка', 'кошка');
```
```response title=Response theme={null}
┌─hasSubsequen⋯', 'кошка')─┐
│ 1 │
└──────────────────────────┘
```
**Subsequência não correspondente**
```sql title=Query theme={null}
SELECT hasSubsequenceUTF8('картошка', 'апельсин');
```
```response title=Response theme={null}
┌─hasSubsequen⋯'апельсин')─┐
│ 0 │
└──────────────────────────┘
```
## hasToken
Introduzido em: v20.1.0
Verifica se o token informado está presente no haystack.
Usa [splitByNonAlpha](/pt-BR/reference/functions/regular-functions/splitting-merging-functions#splitByNonAlpha) como tokenizador, ou seja, um token é definido como a maior subsequência possível de caracteres consecutivos `[0-9A-Za-z_]` (números, caracteres ASCII e underscore).
**Sintaxe**
```sql theme={null}
hasToken(haystack, token)
```
**Argumentos**
* `haystack` — String na qual será feita a busca. [`String`](/pt-BR/reference/data-types/string)
* `token` — Token a ser procurado. [`const String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se o token for encontrado; caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Busca por token**
```sql title=Query theme={null}
SELECT hasToken('clickhouse test', 'test')
```
```response title=Response theme={null}
┌─hasToken('clickhouse test', 'test')─┐
│ 1 │
└─────────────────────────────────────┘
```
## hasTokenCaseInsensitive
Introduzido em: v20.1.0
Realiza uma busca sem diferenciar maiúsculas de minúsculas por needle em haystack usando o índice tokenbf\_v1.
**Sintaxe**
```sql theme={null}
hasTokenCaseInsensitive(haystack, needle)
```
**Argumentos**
* Nenhum.
**Valor retornado**
**Exemplos**
## hasTokenCaseInsensitiveOrNull
Introduzido em: v23.1.0
Realiza uma busca por needle em haystack sem diferenciar maiúsculas de minúsculas, usando o índice tokenbf\_v1. Retorna NULL se needle estiver malformado.
**Sintaxe**
```sql theme={null}
hasTokenCaseInsensitiveOrNull(haystack, needle)
```
**Argumentos**
* Nenhum.
**Valor retornado**
**Exemplos**
## hasTokenOrNull
Introduzido em: v20.1.0
Semelhante a [`hasToken`](#hasToken), mas retorna NULL se o token estiver malformado.
**Sintaxe**
```sql theme={null}
hasTokenOrNull(haystack, token)
```
**Argumentos**
* `haystack` — String na qual será feita a busca. Deve ser constante. [`String`](/pt-BR/reference/data-types/string)
* `token` — Token a ser buscado. [`const String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se o token for encontrado, `0` caso contrário, NULL se o token estiver malformado. [`Nullable(UInt8)`](/pt-BR/reference/data-types/nullable)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT hasTokenOrNull('apple banana cherry', 'ban ana');
```
```response title=Response theme={null}
┌─hasTokenOrNu⋯ 'ban ana')─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────┘
```
## highlight
Introduzido em: v26.4.0
Destaca ocorrências de termos de busca em uma string, envolvendo-as com tags HTML.
A função realiza correspondência ASCII sem diferenciar maiúsculas de minúsculas. Se vários termos de busca se sobrepuserem ou estiverem adjacentes no texto, as regiões correspondentes serão mescladas em um único trecho destacado.
**Sintaxe**
```sql theme={null}
highlight(haystack, needles[, open_tag, close_tag])
```
**Argumentos**
* `haystack` — O texto no qual pesquisar. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `needles` — Um array de termos de pesquisa a serem destacados. [`const Array(String)`](/pt-BR/reference/data-types/array)
* `open_tag` — A tag de abertura a ser inserida antes de cada ocorrência. Padrão: ``. [`const String`](/pt-BR/reference/data-types/string)
* `close_tag` — A tag de fechamento a ser inserida após cada ocorrência. Padrão: ``. [`const String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna o texto de entrada com os termos encontrados delimitados pelas tags especificadas. [`String`](/pt-BR/reference/data-types/string)
**Exemplos**
**Destaque básico**
```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 │
└────────────────────────────────────────────────────┘
```
**Tags personalizadas**
```sql title=Query theme={null}
SELECT highlight('Hello World', ['hello'], '', '')
```
```response title=Response theme={null}
┌─highlight('Hello World', ['hello'], '', '')─┐
│ Hello World │
└────────────────────────────────────────────────────┘
```
## ilike
Introduzido em: v20.6.0
Como [`like`](#like), mas faz a busca sem diferenciar maiúsculas de minúsculas. Suporta a cláusula opcional `ESCAPE` (consulte `like`).
**Sintaxe**
```sql theme={null}
ilike(haystack, pattern[, escape_character])
-- haystack ILIKE pattern [ESCAPE 'escape_character']
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `pattern` — padrão LIKE usado para correspondência. [`String`](/pt-BR/reference/data-types/string)
* `escape_character` — String opcional de um único caractere usada como caractere de escape em vez de `\`. Padrão: `\`. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se a string corresponder ao padrão LIKE (sem diferenciar maiúsculas de minúsculas); caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT ilike('ClickHouse', '%house%');
```
```response title=Response theme={null}
┌─ilike('ClickHouse', '%house%')─┐
│ 1 │
└────────────────────────────────┘
```
## like
Introduzido em: v1.1.0
Retorna se a string `haystack` corresponde à expressão `LIKE` `pattern`.
Uma expressão `LIKE` pode conter caracteres normais e os seguintes metassímbolos:
* `%` indica uma quantidade arbitrária de caracteres arbitrários (incluindo zero caracteres).
* `_` indica um único caractere arbitrário.
* `\` é usado para escapar os literais `%`, `_` e `\`.
A correspondência é baseada em UTF-8; por exemplo, `_` corresponde ao ponto de código Unicode `¥`, que em UTF-8 é representado por dois bytes.
Se o haystack ou a expressão `LIKE` não forem UTF-8 válidos, o comportamento será indefinido.
Nenhuma normalização Unicode automática é realizada; você pode usar as funções `normalizeUTF8*` para isso.
Para corresponder a `%`, `_` e `\` literais (que são metacaracteres de `LIKE`), prefixe-os com uma barra invertida: `\%`, `\_` e `\\`.
A barra invertida perde seu significado especial (ou seja, é interpretada literalmente) se preceder um caractere diferente de `%`, `_` ou `\`.
O ClickHouse exige que barras invertidas em strings [também sejam escapadas](/pt-BR/reference/syntax#string), então na prática você precisará escrever `\\%`, `\\_` e `\\\\`.
Para expressões `LIKE` no formato `%needle%`, a função é tão rápida quanto a função `position`.
Todas as outras expressões `LIKE` são convertidas internamente em uma expressão regular e executadas com desempenho semelhante ao da função `match`.
## cláusula ESCAPE
A cláusula `ESCAPE` opcional especifica um caractere de escape personalizado (deve ser um único caractere ASCII).
Quando especificado, o caractere de escape personalizado substitui a barra invertida padrão para escapar os metacaracteres `%` e `_`.
O caractere de escape pode escapar três coisas: `%` (porcentagem literal), `_` (sublinhado literal) e ele mesmo (caractere de escape literal).
Quando um caractere de escape personalizado é usado, a barra invertida não tem significado especial e é tratada como um caractere literal.
**Sintaxe**
```sql theme={null}
like(haystack, pattern[, escape_character])
-- haystack LIKE pattern [ESCAPE 'escape_character']
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `pattern` — Padrão `LIKE` usado na correspondência. Pode conter `%` (corresponde a qualquer número de caracteres), `_` (corresponde a um único caractere) e `\` para escape. [`String`](/pt-BR/reference/data-types/string)
* `escape_character` — String opcional de um único caractere a ser usada como caractere de escape em vez de `\`. Padrão: `\`. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se a string corresponder ao padrão `LIKE`; caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT like('ClickHouse', '%House');
```
```response title=Response theme={null}
┌─like('ClickHouse', '%House')─┐
│ 1 │
└──────────────────────────────┘
```
**Curinga de caractere único**
```sql title=Query theme={null}
SELECT like('ClickHouse', 'Click_ouse');
```
```response title=Response theme={null}
┌─like('ClickH⋯lick_ouse')─┐
│ 1 │
└──────────────────────────┘
```
**Padrão não correspondente**
```sql title=Query theme={null}
SELECT like('ClickHouse', '%SQL%');
```
```response title=Response theme={null}
┌─like('ClickHouse', '%SQL%')─┐
│ 0 │
└─────────────────────────────┘
```
**Cláusula ESCAPE**
```sql title=Query theme={null}
SELECT '50%off' LIKE '50#%off' ESCAPE '#';
```
```response title=Response theme={null}
┌─like('50%off', '50#%off', '#')─┐
│ 1 │
└────────────────────────────────┘
```
## locate
Introduzido em: v18.16.0
Como [`position`](#position), mas com os argumentos `haystack` e `locate` em ordem inversa.
**Comportamento dependente da versão**
O comportamento dessa função depende da versão do ClickHouse:
* nas versões \< v24.3, `locate` era um alias da função `position` e aceitava os argumentos `(haystack, needle[, start_pos])`.
* nas versões >= 24.3, `locate` é uma função própria (para melhor compatibilidade com o MySQL) e aceita os argumentos `(needle, haystack[, start_pos])`.
O comportamento anterior pode ser restaurado usando a configuração `function_locate_has_mysql_compatible_argument_order = false`.
**Sintaxe**
```sql theme={null}
locate(needle, haystack[, start_pos])
```
**Argumentos**
* `needle` — Substring a ser procurada. [`String`](/pt-BR/reference/data-types/string)
* `haystack` — String na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string) ou [`Enum`](/pt-BR/reference/data-types/enum)
* `start_pos` — Opcional. Posição (baseada em 1) em `haystack` a partir da qual a busca começa. [`UInt`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a posição inicial em bytes, contando a partir de 1, se a substring for encontrada; `0` se a substring não for encontrada. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Uso básico**
```sql title=Query theme={null}
SELECT locate('ca', 'abcabc')
```
```response title=Response theme={null}
┌─locate('ca', 'abcabc')─┐
│ 3 │
└────────────────────────┘
```
## match
Introduzido em: v1.1.0
Verifica se uma string fornecida corresponde ao padrão de expressão regular informado.
Esta função usa a biblioteca de expressões regulares RE2. Consulte [re2](https://github.com/google/re2/wiki/Syntax) para ver a sintaxe compatível.
A correspondência funciona assumindo UTF-8; por exemplo, `¥` usa dois bytes internamente, mas a correspondência o trata como um único ponto de código.
A expressão regular não deve conter bytes NULL.
Se o haystack ou o pattern não forem UTF-8 válidos, o comportamento será indefinido.
Ao contrário do comportamento padrão do re2, `.` corresponde a quebras de linha. Para desativar isso, prefixe o padrão com `(?-s)`.
O padrão não é ancorado. Para corresponder à string inteira, ancore o padrão usando `^` e `$`.
Se você só quiser procurar substrings, use as funções [`like`](#like) ou [`position`](#position), que são muito mais rápidas do que esta função.
Sintaxe alternativa do operador: `haystack REGEXP pattern`.
**Sintaxe**
```sql theme={null}
match(haystack, pattern)
```
**Aliases**: `REGEXP_MATCHES`
**Argumentos**
* `haystack` — String na qual o padrão é buscado. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — Padrão de expressão regular. Pode ser uma constante ou vir de uma coluna. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se o padrão corresponder, `0` caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Correspondência de padrões simples**
```sql title=Query theme={null}
SELECT match('Hello World', 'Hello.*')
```
```response title=Response theme={null}
┌─match('Hello World', 'Hello.*')─┐
│ 1 │
└─────────────────────────────────┘
```
**Padrão não corresponde**
```sql title=Query theme={null}
SELECT match('Hello World', 'goodbye.*')
```
```response title=Response theme={null}
┌─match('Hello World', 'goodbye.*')─┐
│ 0 │
└───────────────────────────────────┘
```
**Correspondência com substring**
```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
Introduzido em: v20.1.0
Semelhante a [`multiFuzzyMatchAny`](#multiFuzzyMatchAny), mas retorna o array com todos os índices, em qualquer ordem, que correspondem ao haystack dentro de uma [distância de edição](https://en.wikipedia.org/wiki/Edit_distance) constante.
**Sintaxe**
```sql theme={null}
multiFuzzyMatchAllIndices(haystack, distance, [pattern1, pattern2, ..., patternN])
```
**Argumentos**
* `haystack` — String na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `distance` — A distância máxima de edição para correspondência aproximada. [`UInt8`](/pt-BR/reference/data-types/int-uint)
* `pattern` — Array de padrões a serem correspondidos. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna um array com todos os índices (a partir de 1) que correspondem ao `haystack` dentro da distância de edição especificada, em qualquer ordem. Retorna um array vazio se nenhuma correspondência for encontrada. [`Array(UInt64)`](/pt-BR/reference/data-types/array)
**Exemplos**
**Exemplo de uso**
```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
Introduzido em: v20.1.0
Como [`multiMatchAny`](#multiMatchAny), mas retorna 1 se algum padrão corresponder à haystack dentro de uma [distância de edição](https://en.wikipedia.org/wiki/Edit_distance) constante.
Esta função depende de uma funcionalidade experimental da biblioteca [hyperscan](https://intel.github.io/hyperscan/dev-reference/compilation.html#approximate-matching) e pode ser lenta em alguns casos extremos.
O desempenho depende do valor da distância de edição e dos padrões usados, mas o custo é sempre maior em comparação com as variantes sem correspondência difusa.
A família de funções `multiFuzzyMatch*()` não oferece suporte a expressões regulares UTF-8 (ela as trata como uma sequência de bytes) devido a restrições do hyperscan.
**Sintaxe**
```sql theme={null}
multiFuzzyMatchAny(haystack, distance, [pattern1, pattern2, ..., patternN])
```
**Argumentos**
* `haystack` — String na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `distance` — A distância máxima de edição para correspondência aproximada. [`UInt8`](/pt-BR/reference/data-types/int-uint)
* `pattern` — Opcional. Um array de padrões para comparar. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna `1` se algum padrão corresponder ao `haystack` dentro da distância de edição especificada; caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT multiFuzzyMatchAny('ClickHouse', 2, ['ClickHouse', 'ClckHouse', 'ClickHose']);
```
```response title=Response theme={null}
┌─multiFuzzyMa⋯lickHose'])─┐
│ 1 │
└──────────────────────────┘
```
## multiFuzzyMatchAnyIndex
Introduzido em: v20.1.0
Como [`multiFuzzyMatchAny`](#multiFuzzyMatchAny), mas retorna qualquer índice que corresponda ao haystack com uma [distância de edição](https://en.wikipedia.org/wiki/Edit_distance) constante.
**Sintaxe**
```sql theme={null}
multiFuzzyMatchAnyIndex(haystack, distance, [pattern1, pattern2, ..., patternn])
```
**Argumentos**
* `haystack` — String na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `distance` — A distância máxima de edição para correspondência aproximada. [`UInt8`](/pt-BR/reference/data-types/int-uint)
* `pattern` — Array de padrões para correspondência. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna o índice (a partir de 1) de qualquer padrão que corresponda ao `haystack` dentro da distância de edição especificada; caso contrário, `0`. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT multiFuzzyMatchAnyIndex('ClickHouse', 2, ['ClckHouse', 'ClickHose', 'ClickHouse']);
```
```response title=Response theme={null}
┌─multiFuzzyMa⋯ickHouse'])─┐
│ 2 │
└──────────────────────────┘
```
## multiMatchAllIndices
Introduzido em: v20.1.0
Como [`multiMatchAny`](#multiMatchAny), mas retorna o array com todos os índices que correspondem ao haystack, em qualquer ordem.
**Sintaxe**
```sql theme={null}
multiMatchAllIndices(haystack, [pattern1, pattern2, ..., patternn])
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — Expressões regulares usadas na correspondência. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Array com todos os índices (a partir de 1) que encontram correspondência no `haystack`, em qualquer ordem. Retorna um array vazio se nenhuma correspondência for encontrada. [`Array(UInt64)`](/pt-BR/reference/data-types/array)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT multiMatchAllIndices('ClickHouse', ['[0-9]', 'House', 'Click', 'ouse']);
```
```response title=Response theme={null}
┌─multiMatchAl⋯', 'ouse'])─┐
│ [3, 2, 4] │
└──────────────────────────┘
```
## multiMatchAny
Introduzido em: v20.1.0
Verifica se pelo menos um entre vários padrões de expressão regular corresponde à string de entrada.
Se você quiser apenas pesquisar várias substrings em uma string, pode usar a função [`multiSearchAny`](#multiSearchAny) — ela funciona muito mais rápido do que esta função.
**Sintaxe**
```sql theme={null}
multiMatchAny(haystack, pattern1[, pattern2, ...])
```
**Argumentos**
* `haystack` — String em que os padrões são buscados. [`String`](/pt-BR/reference/data-types/string)
* `pattern1[, pattern2, ...]` — Um array de um ou mais padrões de expressão regular. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna `1` se algum padrão corresponder, `0` caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Correspondência com múltiplos padrões**
```sql title=Query theme={null}
SELECT multiMatchAny('Hello World', ['Hello.*', 'foo.*'])
```
```response title=Response theme={null}
┌─multiMatchAny('Hello World', ['Hello.*', 'foo.*'])─┐
│ 1 │
└────────────────────────────────────────────────────┘
```
**Nenhum padrão corresponde**
```sql title=Query theme={null}
SELECT multiMatchAny('Hello World', ['goodbye.*', 'foo.*'])
```
```response title=Response theme={null}
┌─multiMatchAny('Hello World', ['goodbye.*', 'foo.*'])─┐
│ 0 │
└──────────────────────────────────────────────────────┘
```
## multiMatchAnyIndex
Introduzido em: v20.1.0
Como [`multiMatchAny`](#multiMatchAny), mas retorna qualquer índice que corresponda à string de entrada.
**Sintaxe**
```sql theme={null}
multiMatchAnyIndex(haystack, [pattern1, pattern2, ..., patternn])
```
**Argumentos**
* `haystack` — String na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `pattern` — Expressões regulares a serem correspondidas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna o índice (a partir de 1) do primeiro padrão que corresponde, ou 0 se nenhuma correspondência for encontrada. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT multiMatchAnyIndex('ClickHouse', ['[0-9]', 'House', 'Click']);
```
```response title=Response theme={null}
┌─multiMatchAn⋯, 'Click'])─┐
│ 3 │
└──────────────────────────┘
```
## multiSearchAllPositions
Introduzido em: v20.1.0
Como [`position`](#position), mas retorna um array com as posições (em bytes, começando em 1) de várias substrings `needle` em uma string `haystack`.
Todas as funções `multiSearch*()` suportam no máximo 2^8 needles.
**Sintaxe**
```sql theme={null}
multiSearchAllPositions(haystack, needle1[, needle2, ...])
```
**Argumentos**
* `haystack` — String na qual a busca é feita. [`String`](/pt-BR/reference/data-types/string)
* `needle1[, needle2, ...]` — Um array com uma ou mais substrings a serem buscadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna um array com a posição inicial em bytes, contada a partir de 1, se a substring for encontrada, ou `0` se a substring não for encontrada. [`Array(UInt64)`](/pt-BR/reference/data-types/array)
**Exemplos**
**Busca por múltiplas substrings**
```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
Introduzido em: v20.1.0
Como [`multiSearchAllPositions`](#multiSearchAllPositions), mas não diferencia maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
multiSearchAllPositionsCaseInsensitive(haystack, needle1[, needle2, ...])
```
**Argumentos**
* `haystack` — String na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle1[, needle2, ...]` — Um array de uma ou mais substrings a serem pesquisadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna um array com a posição inicial em bytes, contando a partir de 1 (se a substring for encontrada), ou `0` se a substring não for encontrada. [`Array(UInt64)`](/pt-BR/reference/data-types/array)
**Exemplos**
**Multibusca sem distinção entre maiúsculas e minúsculas**
```sql title=Query theme={null}
SELECT multiSearchAllPositionsCaseInsensitive('ClickHouse',['c','h'])
```
```response title=Response theme={null}
┌─multiSearchA⋯['c', 'h'])─┐
│ [1,6] │
└──────────────────────────┘
```
## multiSearchAllPositionsCaseInsensitiveUTF8
Introduzido em: v20.1.0
Como [`multiSearchAllPositionsUTF8`](#multiSearchAllPositionsUTF8), mas não diferencia maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
multiSearchAllPositionsCaseInsensitiveUTF8(haystack, [needle1, needle2, ..., needleN])
```
**Argumentos**
* `haystack` — string codificada em UTF-8 na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — substrings codificadas em UTF-8 que serão buscadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Array com as posições iniciais em bytes, contadas a partir de 1 (se a substring for encontrada). Retorna 0 se a substring não for encontrada. [`Array`](/pt-BR/reference/data-types/array)
**Exemplos**
**Busca UTF-8 sem diferenciar maiúsculas de minúsculas**
```sql title=Query theme={null}
SELECT multiSearchAllPositionsCaseInsensitiveUTF8('Здравствуй, мир!', ['здравствуй', 'МИР']);
```
```response title=Response theme={null}
┌─multiSearchA⋯й', 'МИР'])─┐
│ [1, 13] │
└──────────────────────────┘
```
## multiSearchAllPositionsUTF8
Introduzido em: v20.1.0
Como [`multiSearchAllPositions`](#multiSearchAllPositions), mas pressupõe que `haystack` e as substrings `needle` sejam strings codificadas em UTF-8.
**Sintaxe**
```sql theme={null}
multiSearchAllPositionsUTF8(haystack, needle1[, needle2, ...])
```
**Argumentos**
* `haystack` — String codificada em UTF-8 na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle1[, needle2, ...]` — Um array de substrings codificadas em UTF-8 a serem procuradas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna um array com as posições iniciais, em bytes e contadas a partir de 1 (se a substring for encontrada), ou `0`, se a substring não for encontrada. [`Array`](/pt-BR/reference/data-types/array)
**Exemplos**
**Busca múltipla em UTF-8**
```sql title=Query theme={null}
SELECT multiSearchAllPositionsUTF8('ClickHouse',['C','H'])
```
```response title=Response theme={null}
┌─multiSearchAllPositionsUTF8('ClickHouse', ['C', 'H'])─┐
│ [1,6] │
└───────────────────────────────────────────────────────┘
```
## multiSearchAny
Introduzido em: v20.1.0
Verifica se pelo menos uma das várias strings needle corresponde à string haystack.
As funções [`multiSearchAnyCaseInsensitive`](#multiSearchAnyCaseInsensitive), [`multiSearchAnyUTF8`](#multiSearchAnyUTF8) e [`multiSearchAnyCaseInsensitiveUTF8`](#multiSearchAnyCaseInsensitiveUTF8) fornecem variantes sem distinção entre maiúsculas e minúsculas e/ou em UTF-8 desta função.
**Sintaxe**
```sql theme={null}
multiSearchAny(haystack, needle1[, needle2, ...])
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle1[, needle2, ...]` — Um array de substrings a serem pesquisadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna `1` se houver pelo menos uma correspondência; caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Busca por qualquer correspondência**
```sql title=Query theme={null}
SELECT multiSearchAny('ClickHouse',['C','H'])
```
```response title=Response theme={null}
┌─multiSearchAny('ClickHouse', ['C', 'H'])─┐
│ 1 │
└──────────────────────────────────────────┘
```
## multiSearchAnyCaseInsensitive
Introduzido em: v20.1.0
Como [multiSearchAny](#multiSearchAny), mas sem diferenciar maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
multiSearchAnyCaseInsensitive(haystack, [needle1, needle2, ..., needleN])
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Substrings a serem pesquisadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna `1` se houver pelo menos uma correspondência sem distinção entre maiúsculas e minúsculas; caso contrário, retorna `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Busca sem distinção entre maiúsculas e minúsculas**
```sql title=Query theme={null}
SELECT multiSearchAnyCaseInsensitive('ClickHouse',['c','h'])
```
```response title=Response theme={null}
┌─multiSearchAnyCaseInsensitive('ClickHouse', ['c', 'h'])─┐
│ 1 │
└─────────────────────────────────────────────────────────┘
```
## multiSearchAnyCaseInsensitiveUTF8
Introduzido em: v20.1.0
Como [multiSearchAnyUTF8](#multiSearchAnyUTF8), mas sem diferenciar maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
multiSearchAnyCaseInsensitiveUTF8(haystack, [needle1, needle2, ..., needleN])
```
**Argumentos**
* `haystack` — string UTF-8 na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — substrings UTF-8 a serem procuradas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna `1` se houver pelo menos uma correspondência sem diferenciar maiúsculas de minúsculas; caso contrário, retorna `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Dada a string UTF-8 'Здравствуйте', verifique se o caractere 'з' (minúsculo) está presente**
```sql title=Query theme={null}
SELECT multiSearchAnyCaseInsensitiveUTF8('Здравствуйте',['з'])
```
```response title=Response theme={null}
┌─multiSearchA⋯те', ['з'])─┐
│ 1 │
└──────────────────────────┘
```
## multiSearchAnyUTF8
Introduzido em: v20.1.0
Semelhante a [multiSearchAny](#multiSearchAny), mas assume que `haystack` e as substrings `needle` são strings codificadas em UTF-8.
**Sintaxe**
```sql theme={null}
multiSearchAnyUTF8(haystack, [needle1, needle2, ..., needleN])
```
**Argumentos**
* `haystack` — string em UTF-8 na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — substrings em UTF-8 a serem buscadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna `1` se houver pelo menos uma correspondência; caso contrário, retorna `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Dada '你好，世界' ('Olá, mundo') como uma string em UTF-8, verifique se a string contém algum caractere 你 ou 界**
```sql title=Query theme={null}
SELECT multiSearchAnyUTF8('你好，世界', ['你', '界'])
```
```response title=Response theme={null}
┌─multiSearchA⋯你', '界'])─┐
│ 1 │
└──────────────────────────┘
```
## multiSearchFirstIndex
Introduzido em: v20.1.0
Procura várias strings needle em uma string haystack (diferencia maiúsculas de minúsculas) e retorna o índice, com base em 1, da primeira needle encontrada.
**Sintaxe**
```sql theme={null}
multiSearchFirstIndex(haystack, [needle1, needle2, ..., needleN])
```
**Argumentos**
* `haystack` — A string em que a busca será feita. [`String`](/pt-BR/reference/data-types/string)
* `needles` — Array de strings a serem pesquisadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna o índice com base em 1 (posição no array `needles`) da primeira `needle` encontrada em `haystack`. Retorna 0 se nenhuma `needle` for encontrada. A busca diferencia maiúsculas de minúsculas. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT multiSearchFirstIndex('ClickHouse Database', ['Click', 'Database', 'Server']);
```
```response title=Response theme={null}
┌─multiSearchF⋯ 'Server'])─┐
│ 1 │
└──────────────────────────┘
```
**Comportamento com diferenciação entre maiúsculas e minúsculas**
```sql title=Query theme={null}
SELECT multiSearchFirstIndex('ClickHouse Database', ['CLICK', 'Database', 'Server']);
```
```response title=Response theme={null}
┌─multiSearchF⋯ 'Server'])─┐
│ 2 │
└──────────────────────────┘
```
**Nenhuma correspondência encontrada**
```sql title=Query theme={null}
SELECT multiSearchFirstIndex('Hello World', ['goodbye', 'test']);
```
```response title=Response theme={null}
┌─multiSearchF⋯', 'test'])─┐
│ 0 │
└──────────────────────────┘
```
## multiSearchFirstIndexCaseInsensitive
Introduzido em: v20.1.0
Retorna o índice `i` (a partir de 1) da `needle_i` localizada mais à esquerda na string `haystack` e 0 caso contrário.
Não diferencia maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
multiSearchFirstIndexCaseInsensitive(haystack, [needle1, needle2, ..., needleN]
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Substrings a serem buscadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna o índice (a partir de 1) da substring encontrada mais à esquerda. Caso contrário, retorna `0` se não houver correspondência. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT multiSearchFirstIndexCaseInsensitive('hElLo WoRlD', ['World', 'Hello']);
```
```response title=Response theme={null}
┌─multiSearchF⋯, 'Hello'])─┐
│ 1 │
└──────────────────────────┘
```
## multiSearchFirstIndexCaseInsensitiveUTF8
Introduzido em: v20.1.0
Procura várias strings needle em uma string haystack, sem diferenciar maiúsculas de minúsculas e com suporte à codificação UTF-8, e retorna o índice, começando em 1, da primeira needle encontrada.
**Sintaxe**
```sql theme={null}
multiSearchFirstIndexCaseInsensitiveUTF8(haystack, [needle1, needle2, ..., needleN])
```
**Argumentos**
* `haystack` — A string em que a busca é feita. [`String`](/pt-BR/reference/data-types/string)
* `needles` — Array de strings a serem buscadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna o índice com base em 1 (posição no array `needles`) da primeira string encontrada em `haystack`. Retorna 0 se nenhuma string for encontrada. A busca não diferencia maiúsculas de minúsculas e respeita a codificação de caracteres UTF-8. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT multiSearchFirstIndexCaseInsensitiveUTF8('ClickHouse Database', ['CLICK', 'data', 'server']);
```
```response title=Response theme={null}
┌─multiSearchF⋯ 'server'])─┐
│ 1 │
└──────────────────────────┘
```
**Tratamento de maiúsculas/minúsculas em UTF-8**
```sql title=Query theme={null}
SELECT multiSearchFirstIndexCaseInsensitiveUTF8('Привет Мир', ['мир', 'ПРИВЕТ']);
```
```response title=Response theme={null}
┌─multiSearchF⋯ 'ПРИВЕТ'])─┐
│ 1 │
└──────────────────────────┘
```
**Nenhuma correspondência encontrada**
```sql title=Query theme={null}
SELECT multiSearchFirstIndexCaseInsensitiveUTF8('Hello World', ['goodbye', 'test']);
```
```response title=Response theme={null}
┌─multiSearchF⋯', 'test'])─┐
│ 0 │
└──────────────────────────┘
```
## multiSearchFirstIndexUTF8
Introduzido em: v20.1.0
Retorna o índice `i` (a partir de 1) da `needle`\_i encontrada na posição mais à esquerda na string `haystack`, e 0 caso contrário.
Pressupõe que `haystack` e `needle` sejam strings codificadas em UTF-8.
**Sintaxe**
```sql theme={null}
multiSearchFirstIndexUTF8(haystack, [needle1, needle2, ..., needleN])
```
**Argumentos**
* `haystack` — string em UTF-8 na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Array de substrings em UTF-8 a serem procuradas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna o índice (a partir de 1) da `needle` encontrada mais à esquerda. Caso contrário, retorna 0 se não houver correspondência. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT multiSearchFirstIndexUTF8('Здравствуйте мир', ['мир', 'здравствуйте']);
```
```response title=Response theme={null}
┌─multiSearchF⋯вствуйте'])─┐
│ 1 │
└──────────────────────────┘
```
## multiSearchFirstPosition
Introduzido em: v20.1.0
Como [`position`](#position), mas retorna a posição mais à esquerda em uma string `haystack` que corresponde a qualquer uma de várias strings `needle`.
As funções [`multiSearchFirstPositionCaseInsensitive`](#multiSearchFirstPositionCaseInsensitive), [`multiSearchFirstPositionUTF8`](#multiSearchFirstPositionUTF8) e [`multiSearchFirstPositionCaseInsensitiveUTF8`](#multiSearchFirstPositionCaseInsensitiveUTF8) fornecem variantes sem distinção entre maiúsculas e minúsculas e/ou em UTF-8 desta função.
**Sintaxe**
```sql theme={null}
multiSearchFirstPosition(haystack, needle1[, needle2, ...])
```
**Argumentos**
* `haystack` — String na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle1[, needle2, ...]` — Um array de uma ou mais substrings a serem buscadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna o deslocamento da ocorrência mais à esquerda em uma string `haystack` que corresponda a qualquer uma de várias strings `needle`; caso contrário, `0`, se não houver correspondência. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Busca da primeira posição**
```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
Introduzido em: v20.1.0
Como [multiSearchFirstPosition](#multiSearchFirstPosition), mas não diferencia maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
multiSearchFirstPositionCaseInsensitive(haystack, [needle1, needle2, ..., needleN])
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Array de substrings a serem buscadas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna o deslocamento na string `haystack` que corresponde a qualquer uma das strings `needle`. Retorna `0` se não houver correspondência. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Primeira posição sem diferenciar maiúsculas de minúsculas**
```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
Introduzido em: v20.1.0
Como [multiSearchFirstPosition](#multiSearchFirstPosition), mas considera `haystack` e `needle` como strings UTF-8 e não diferencia maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
multiSearchFirstPositionCaseInsensitiveUTF8(haystack, [needle1, needle2, ..., needleN])
```
**Argumentos**
* `haystack` — string UTF-8 na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Array de substrings UTF-8 a serem procuradas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Retorna o deslocamento mais à esquerda em uma string `haystack` que corresponde a qualquer uma das várias strings `needle`, sem diferenciar maiúsculas de minúsculas. Retorna `0` se não houver correspondência. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Encontre o deslocamento mais à esquerda na string UTF-8 'Здравствуй, мир' ('Hello, world') que corresponde a qualquer uma das substrings fornecidas**
```sql title=Query theme={null}
SELECT multiSearchFirstPositionCaseInsensitiveUTF8('Здравствуй, мир', ['МИР', 'вст', 'Здра'])
```
```response title=Response theme={null}
┌─multiSearchFirstPositionCaseInsensitiveUTF8('Здравствуй, мир', ['МИР', 'вст', 'Здра'])─┐
│ 1 │
└────────────────────────────────────────────────────────────────────────────────────────┘
```
## multiSearchFirstPositionUTF8
Introduzido em: v20.1.0
Assim como [multiSearchFirstPosition](#multiSearchFirstPosition), mas pressupõe que `haystack` e `needle` sejam strings UTF-8.
**Sintaxe**
```sql theme={null}
multiSearchFirstPositionUTF8(haystack, [needle1, needle2, ..., needleN])
```
**Argumentos**
* `haystack` — string UTF-8 na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Array de substrings UTF-8 a serem procuradas. [`Array(String)`](/pt-BR/reference/data-types/array)
**Valor retornado**
Deslocamento da ocorrência mais à esquerda em uma string `haystack` que corresponde a qualquer uma das várias strings `needle`. Retorna `0` se não houver correspondência. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Encontre o deslocamento da ocorrência mais à esquerda na string UTF-8 'Здравствуй, мир' ('Hello, world') que corresponde a qualquer uma das strings `needle` fornecidas**
```sql title=Query theme={null}
SELECT multiSearchFirstPositionUTF8('Здравствуй, мир',['мир', 'вст', 'авст'])
```
```response title=Response theme={null}
┌─multiSearchFirstPositionUTF8('Здравствуй, мир', ['мир', 'вст', 'авст'])─┐
│ 4 │
└─────────────────────────────────────────────────────────────────────────┘
```
## ngramDistance
Introduzido em: v20.1.0
Calcula a distância de 4-gramas entre duas strings.
Para isso, conta a diferença simétrica entre dois multiconjuntos de 4-gramas e a normaliza pela soma de suas cardinalidades.
Quanto menor o valor retornado, mais semelhantes são as strings.
Para busca sem distinção entre maiúsculas e minúsculas e/ou no formato UTF-8, use as funções [`ngramDistanceCaseInsensitive`](#ngramDistanceCaseInsensitive), [`ngramDistanceUTF8`](#ngramDistanceUTF8), [`ngramDistanceCaseInsensitiveUTF8`](#ngramDistanceCaseInsensitiveUTF8).
**Sintaxe**
```sql theme={null}
ngramDistance(haystack, needle)
```
**Argumentos**
* `haystack` — String para comparação. [`String`](/pt-BR/reference/data-types/string)
* `needle` — String para comparação. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um valor Float32 entre `0` e `1`. Quanto menor o valor retornado, mais semelhantes são as strings. [`Float32`](/pt-BR/reference/data-types/float)
**Exemplos**
**Calcular a distância por 4-gramas**
```sql title=Query theme={null}
SELECT ngramDistance('ClickHouse', 'ClickHouses')
```
```response title=Response theme={null}
┌─ngramDistance('ClickHouse', 'ClickHouses')─┐
│ 0.1 │
└────────────────────────────────────────────┘
```
## ngramDistanceCaseInsensitive
Introduzido em: v20.1.0
Fornece uma variante de [`ngramDistance`](#ngramDistance) sem diferenciar maiúsculas de minúsculas.
Calcula a distância de 4-gram entre duas strings, ignorando maiúsculas e minúsculas.
Quanto menor o valor retornado, mais semelhantes são as strings.
**Sintaxe**
```sql theme={null}
ngramDistanceCaseInsensitive(haystack, needle)
```
**Argumentos**
* `haystack` — Primeira string de comparação. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Segunda string de comparação. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um número `Float32` entre `0` e `1`. [`Float32`](/pt-BR/reference/data-types/float)
**Exemplos**
**Distância de 4 gramas sem diferenciar maiúsculas de minúsculas**
```sql title=Query theme={null}
SELECT ngramDistanceCaseInsensitive('ClickHouse','clickhouse')
```
```response title=Response theme={null}
┌─ngramDistanceCaseInsensitive('ClickHouse','clickhouse')─┐
│ 0 │
└─────────────────────────────────────────────────────────┘
```
## ngramDistanceCaseInsensitiveUTF8
Introduzido em: v20.1.0
Fornece uma variante UTF-8 de [`ngramDistance`](#ngramDistance) que não diferencia maiúsculas de minúsculas.
Pressupõe que as strings `needle` e `haystack` sejam codificadas em UTF-8 e ignora maiúsculas e minúsculas.
Calcula a distância de 3-gramas entre duas strings UTF-8, ignorando maiúsculas e minúsculas.
Quanto menor o valor retornado, mais semelhantes são as strings.
**Sintaxe**
```sql theme={null}
ngramDistanceCaseInsensitiveUTF8(haystack, needle)
```
**Argumentos**
* `haystack` — Primeira string de comparação codificada em UTF-8. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Segunda string de comparação codificada em UTF-8. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um número `Float32` entre `0` e `1`. [`Float32`](/pt-BR/reference/data-types/float)
**Exemplos**
**Distância UTF-8 de 3 gramas sem diferenciar maiúsculas de minúsculas**
```sql title=Query theme={null}
SELECT ngramDistanceCaseInsensitiveUTF8('abcde','CDE')
```
```response title=Response theme={null}
┌─ngramDistanceCaseInsensitiveUTF8('abcde','CDE')─┐
│ 0.5 │
└─────────────────────────────────────────────────┘
```
## ngramDistanceUTF8
Introduzido em: v20.1.0
Fornece uma variante em UTF-8 de [`ngramDistance`](#ngramDistance).
Pressupõe que as strings `needle` e `haystack` sejam codificadas em UTF-8.
Calcula a distância de 3-gramas entre duas strings UTF-8.
Quanto menor o valor retornado, mais semelhantes são as strings.
**Sintaxe**
```sql theme={null}
ngramDistanceUTF8(haystack, needle)
```
**Argumentos**
* `haystack` — Primeira string de comparação codificada em UTF-8. [`String`](/pt-BR/reference/data-types/string)
* `needle` — Segunda string de comparação codificada em UTF-8. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna um número `Float32` entre `0` e `1`. [`Float32`](/pt-BR/reference/data-types/float)
**Exemplos**
**Distância de 3-gramas UTF-8**
```sql title=Query theme={null}
SELECT ngramDistanceUTF8('abcde','cde')
```
```response title=Response theme={null}
┌─ngramDistanceUTF8('abcde','cde')─┐
│ 0.5 │
└───────────────────────────────────┘
```
## ngramSearch
Introduzido em: v20.1.0
Verifica se a distância de 4-gramas entre duas strings é menor ou igual a um determinado limiar.
Para busca sem distinção entre maiúsculas e minúsculas e/ou no formato UTF-8, use as funções `ngramSearchCaseInsensitive`, `ngramSearchUTF8`, `ngramSearchCaseInsensitiveUTF8`.
**Sintaxe**
```sql theme={null}
ngramSearch(haystack, needle)
```
**Argumentos**
* `haystack` — String a ser comparada. [`String`](/pt-BR/reference/data-types/string)
* `needle` — String a ser comparada. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se a distância de 4-gramas entre as strings for menor ou igual a um limiar (`1.0` por padrão); caso contrário, retorna `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Busca com 4-gramas**
```sql title=Query theme={null}
SELECT ngramSearch('ClickHouse', 'Click')
```
```response title=Response theme={null}
┌─ngramSearch('ClickHouse', 'Click')─┐
│ 1 │
└────────────────────────────────────┘
```
## ngramSearchCaseInsensitive
Introduzido em: v20.1.0
Fornece uma variante de [`ngramSearch`](#ngramSearch) que não diferencia maiúsculas de minúsculas.
Calcula a diferença não simétrica entre as strings needle e haystack, ou seja, o número de n-gramas da needle menos o número de n-gramas em comum, normalizado pelo número de n-gramas da needle.
Verifica se a distância de 4-gramas entre duas strings é menor ou igual a um determinado limiar, ignorando maiúsculas e minúsculas.
**Sintaxe**
```sql theme={null}
ngramSearchCaseInsensitive(haystack, needle)
```
**Argumentos**
* `haystack` — String de comparação. [`String`](/pt-BR/reference/data-types/string)
* `needle` — String de comparação. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se a distância de 4-gramas entre as strings for menor ou igual ao limiar (`1.0` por padrão); caso contrário, retorna `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Busca sem distinção entre maiúsculas e minúsculas usando 4-gramas**
```sql title=Query theme={null}
SELECT ngramSearchCaseInsensitive('Hello World','hello')
```
```response title=Response theme={null}
┌─ngramSearchCaseInsensitive('Hello World','hello')─┐
│ 1 │
└────────────────────────────────────────────────────┘
```
## ngramSearchCaseInsensitiveUTF8
Introduzido em: v20.1.0
Fornece uma variante UTF-8 de [`ngramSearch`](#ngramSearch) sem diferenciar maiúsculas de minúsculas.
Pressupõe que `haystack` e `needle` sejam strings UTF-8 e ignora diferenças entre maiúsculas e minúsculas.
Verifica se a distância de 3-gramas entre duas strings UTF-8 é menor ou igual a um determinado limite, sem diferenciar maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
ngramSearchCaseInsensitiveUTF8(haystack, needle)
```
**Argumentos**
* `haystack` — string em UTF-8 para comparação. [`String`](/pt-BR/reference/data-types/string)
* `needle` — string em UTF-8 para comparação. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se a distância de 3-gramas entre as strings for menor ou igual a um limiar (`1.0` por padrão), `0` caso contrário. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Busca UTF-8 sem diferenciar maiúsculas de minúsculas usando 3-gramas**
```sql title=Query theme={null}
SELECT ngramSearchCaseInsensitiveUTF8('абвГДЕёжз', 'АбвгдЕЁжз')
```
```response title=Response theme={null}
┌─ngramSearchCaseInsensitiveUTF8('абвГДЕёжз', 'АбвгдЕЁжз')─┐
│ 1 │
└──────────────────────────────────────────────────────────┘
```
## ngramSearchUTF8
Introduzido em: v20.1.0
Fornece uma variante UTF-8 de `ngramSearch`.
Pressupõe que `haystack` e `needle` sejam strings em UTF-8.
Verifica se a distância de 3-gramas entre duas strings em UTF-8 é menor ou igual a um determinado limite.
**Sintaxe**
```sql theme={null}
ngramSearchUTF8(haystack, needle)
```
**Argumentos**
* `haystack` — string em UTF-8 para comparação. [`String`](/pt-BR/reference/data-types/string)
* `needle` — string em UTF-8 para comparação. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se a distância de 3-gramas entre as strings for menor ou igual a um limiar (`1.0` por padrão); caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Busca em UTF-8 usando 3-gramas**
```sql title=Query theme={null}
SELECT ngramSearchUTF8('абвгдеёжз', 'гдеёзд')
```
```response title=Response theme={null}
┌─ngramSearchUTF8('абвгдеёжз', 'гдеёзд')─┐
│ 1 │
└────────────────────────────────────────┘
```
## notILike
Introduzido na versão: v20.6.0
Verifica se uma string não corresponde a um padrão, sem diferenciar maiúsculas de minúsculas. O padrão pode conter os caracteres especiais `%` e `_` para correspondência com SQL LIKE. Suporta a cláusula opcional `ESCAPE` (consulte `like`).
**Sintaxe**
```sql theme={null}
notILike(haystack, pattern[, escape_character])
-- haystack NOT ILIKE pattern [ESCAPE 'escape_character']
```
**Argumentos**
* `haystack` — A string de entrada na qual a busca é feita. [`String`](/pt-BR/reference/data-types/string) ou [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `pattern` — O padrão SQL LIKE usado para correspondência. `%` corresponde a qualquer número de caracteres (incluindo zero), `_` corresponde a exatamente um caractere. [`String`](/pt-BR/reference/data-types/string)
* `escape_character` — String opcional de um único caractere a ser usada como caractere de escape em vez de `\`. Padrão: `\`. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se a string não corresponder ao padrão (sem diferenciar maiúsculas de minúsculas); caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT notILike('ClickHouse', '%house%');
```
```response title=Response theme={null}
┌─notILike('Cl⋯ '%house%')─┐
│ 0 │
└──────────────────────────┘
```
## notLike
Introduzido em: v1.1.0
Semelhante a [`like`](#like), mas com o resultado negado. Oferece suporte à cláusula opcional `ESCAPE` (consulte `like`).
**Sintaxe**
```sql theme={null}
notLike(haystack, pattern[, escape_character])
-- haystack NOT LIKE pattern [ESCAPE 'escape_character']
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string) e [`FixedString`](/pt-BR/reference/data-types/fixedstring)
* `pattern` — Padrão `LIKE` para correspondência. [`String`](/pt-BR/reference/data-types/string)
* `escape_character` — String opcional de um único caractere para usar como caractere de escape em vez de `\`. Padrão: `\`. [`String`](/pt-BR/reference/data-types/string)
**Valor retornado**
Retorna `1` se a string não corresponder ao padrão `LIKE`; caso contrário, `0`. [`UInt8`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Exemplo de uso**
```sql title=Query theme={null}
SELECT notLike('ClickHouse', '%House%');
```
```response title=Response theme={null}
┌─notLike('Cli⋯ '%House%')─┐
│ 0 │
└──────────────────────────┘
```
**Padrão não correspondente**
```sql title=Query theme={null}
SELECT notLike('ClickHouse', '%SQL%');
```
```response title=Response theme={null}
┌─notLike('Cli⋯', '%SQL%')─┐
│ 1 │
└──────────────────────────┘
```
## position
Introduzido na versão: v1.1.0
Retorna a posição (em bytes, começando em 1) de uma substring `needle` em uma string `haystack`.
Se a substring `needle` estiver vazia, aplicam-se as seguintes regras:
* se nenhum `start_pos` for especificado: retorna `1`
* se `start_pos = 0`: retorna `1`
* se `start_pos >= 1` e `start_pos <= length(haystack) + 1`: retorna `start_pos`
* caso contrário: retorna `0`
As mesmas regras também se aplicam às funções [`locate`](#locate), [`positionCaseInsensitive`](#positionCaseInsensitive), [`positionUTF8`](#positionUTF8) e [`positionCaseInsensitiveUTF8`](#positionCaseInsensitiveUTF8).
**Sintaxe**
```sql theme={null}
position(haystack, needle[, start_pos])
```
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string) ou [`Enum`](/pt-BR/reference/data-types/enum)
* `needle` — Substring a ser procurada. [`String`](/pt-BR/reference/data-types/string)
* `start_pos` — Posição em `haystack` (começando em 1) na qual a busca se inicia. Opcional. [`UInt`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a posição inicial em bytes, contando a partir de 1, se a substring for encontrada; caso contrário, retorna `0` se a substring não for encontrada. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Uso básico**
```sql title=Query theme={null}
SELECT position('Hello, world!', '!')
```
```response title=Response theme={null}
┌─position('Hello, world!', '!')─┐
│ 13 │
└────────────────────────────────┘
```
**Com o argumento 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 │
└───────────────────────────────────┴───────────────────────────────────┘
```
**Sintaxe de 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 │
└─────────────────────────────┘
```
**Subcadeia com `needle` vazio**
```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
Introduzido em: v1.1.0
Como [`position`](#position), mas sem diferenciar maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
positionCaseInsensitive(haystack, needle[, start_pos])
```
**Aliases**: `instr`
**Argumentos**
* `haystack` — String em que a busca é realizada. [`String`](/pt-BR/reference/data-types/string) ou [`Enum`](/pt-BR/reference/data-types/enum)
* `needle` — Substring a ser procurada. [`String`](/pt-BR/reference/data-types/string)
* `start_pos` — Opcional. Posição (indexada a partir de 1) em `haystack` na qual a busca começa. [`UInt*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a posição inicial em bytes, contando a partir de 1, se a substring for encontrada; caso contrário, retorna `0`. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Busca sem diferenciar maiúsculas de minúsculas**
```sql title=Query theme={null}
SELECT positionCaseInsensitive('Hello, world!', 'hello')
```
```response title=Response theme={null}
┌─positionCaseInsensitive('Hello, world!', 'hello')─┐
│ 1 │
└───────────────────────────────────────────────────┘
```
## positionCaseInsensitiveUTF8
Introduzido em: v1.1.0
Como [`positionUTF8`](#positionUTF8), mas faz a busca sem diferenciar letras maiúsculas de minúsculas.
**Sintaxe**
```sql theme={null}
positionCaseInsensitiveUTF8(haystack, needle[, start_pos])
```
**Argumentos**
* `haystack` — String na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string) ou [`Enum`](/pt-BR/reference/data-types/enum)
* `needle` — Substring a ser procurada. [`String`](/pt-BR/reference/data-types/string)
* `start_pos` — Opcional. Posição (base 1) em `haystack` na qual a busca começa. [`UInt*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a posição inicial, em bytes e contando a partir de 1, se a substring for encontrada; caso contrário, retorna `0`. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Busca UTF-8 sem diferenciar maiúsculas de minúsculas**
```sql title=Query theme={null}
SELECT positionCaseInsensitiveUTF8('Привет мир', 'МИР')
```
```response title=Response theme={null}
┌─positionCaseInsensitiveUTF8('Привет мир', 'МИР')─┐
│ 8 │
└──────────────────────────────────────────────────┘
```
## positionUTF8
Introduzido em: v1.1.0
Como [`position`](#position), mas presume que `haystack` e `needle` sejam strings codificadas em UTF-8.
**Sintaxe**
```sql theme={null}
positionUTF8(haystack, needle[, start_pos])
```
**Argumentos**
* `haystack` — String na qual a busca é realizada. [`String`](/pt-BR/reference/data-types/string) ou [`Enum`](/pt-BR/reference/data-types/enum)
* `needle` — Substring a ser pesquisada. [`String`](/pt-BR/reference/data-types/string)
* `start_pos` — Opcional. Posição (começando em 1) em `haystack` na qual a busca se inicia. [`UInt*`](/pt-BR/reference/data-types/int-uint)
**Valor retornado**
Retorna a posição inicial em bytes, contando a partir de 1, se a substring for encontrada; caso contrário, retorna `0`. [`UInt64`](/pt-BR/reference/data-types/int-uint)
**Exemplos**
**Contagem de caracteres UTF-8**
```sql title=Query theme={null}
SELECT positionUTF8('Motörhead', 'r')
```
```response title=Response theme={null}
┌─position('Motörhead', 'r')─┐
│ 5 │
└────────────────────────────┘
```