> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Layout de dicionário de árvore de expressões regulares
> Configure um dicionário de árvore de expressões regulares para buscas baseadas em padrões.
export const CloudNotSupportedBadge = () => {
return
Not supported in ClickHouse Cloud
;
};
## Visão geral
O dicionário `regexp_tree` permite mapear chaves para valores com base em padrões hierárquicos de expressões regulares.
Ele é otimizado para buscas por correspondência de padrões (por exemplo, classificar strings, como strings de user agent, por meio da correspondência com padrões regex) em vez de correspondência exata de chaves.
## Use o dicionário de árvore regexp com a fonte YAMLRegExpTree
Os dicionários de árvore regexp são definidos no ClickHouse open-source usando a fonte [`YAMLRegExpTree`](/pt-BR/reference/statements/create/dictionary/sources/yamlregexptree), à qual é fornecido o caminho para um arquivo YAML que contém a árvore regexp.
```sql title="Query" theme={null}
CREATE DICTIONARY regexp_dict
(
regexp String,
name String,
version String
)
PRIMARY KEY(regexp)
SOURCE(YAMLRegExpTree(PATH '/var/lib/clickhouse/user_files/regexp_tree.yaml'))
LAYOUT(regexp_tree)
...
```
A fonte do dicionário [`YAMLRegExpTree`](/pt-BR/reference/statements/create/dictionary/sources/yamlregexptree) representa a estrutura de uma árvore regexp. Por exemplo:
```yaml theme={null}
- regexp: 'Linux/(\d+[\.\d]*).+tlinux'
name: 'TencentOS'
version: '\1'
- regexp: '\d+/tclwebkit(?:\d+[\.\d]*)'
name: 'Android'
versions:
- regexp: '33/tclwebkit'
version: '13'
- regexp: '3[12]/tclwebkit'
version: '12'
- regexp: '30/tclwebkit'
version: '11'
- regexp: '29/tclwebkit'
version: '10'
```
Esta configuração consiste em uma lista de nós de árvore regexp. Cada nó tem a seguinte estrutura:
* **regexp**: a expressão regular do nó.
* **attributes**: uma lista de atributos de dicionário definidos pelo usuário. Neste exemplo, há dois atributos: `name` e `version`. O primeiro nó define os dois atributos. O segundo nó define apenas o atributo `name`. O atributo `version` é fornecido pelos nós filhos do segundo nó.
* O valor de um atributo pode conter **retroreferências**, que se referem a grupos de captura da expressão regular correspondente. No exemplo, o valor do atributo `version` no primeiro nó consiste em uma retroreferência `\1` ao grupo de captura `(\d+[\.\d]*)` na expressão regular. Os números de retroreferência variam de 1 a 9 e são escritos como `$1` ou `\1` (para o número 1). A retroreferência é substituída pelo grupo de captura correspondente durante a execução da consulta.
* **child nodes**: uma lista de filhos de um nó de árvore regexp, cada um com seus próprios atributos e (potencialmente) nós filhos. A correspondência de strings segue uma busca em profundidade. Se uma string corresponder a um nó regexp, o dicionário verifica se ela também corresponde aos nós filhos desse nó. Se isso acontecer, os atributos do nó correspondente mais profundo serão atribuídos. Os atributos de um nó filho substituem os atributos com o mesmo nome dos nós pai. O nome dos nós filhos em arquivos YAML pode ser arbitrário, por exemplo, `versions` no exemplo acima.
Dicionários de árvore regexp permitem acesso apenas por meio das funções `dictGet`, `dictGetOrDefault` e `dictGetAll`. Por exemplo:
```sql title="Query" theme={null}
SELECT dictGet('regexp_dict', ('name', 'version'), '31/tclwebkit1024');
```
```text title="Response" theme={null}
┌─dictGet('regexp_dict', ('name', 'version'), '31/tclwebkit1024')─┐
│ ('Android','12') │
└─────────────────────────────────────────────────────────────────┘
```
Neste caso, primeiro encontramos correspondência para a expressão regular `\d+/tclwebkit(?:\d+[\.\d]*)` no segundo nó da camada superior.
Em seguida, o dicionário continua a procurar nos nós filhos e descobre que a string também corresponde a `3[12]/tclwebkit`.
Como resultado, o valor do atributo `name` é `Android` (definido na primeira camada) e o valor do atributo `version` é `12` (definido no nó filho).
Com um arquivo de configuração YAML sofisticado, você pode usar dicionários de árvore regexp como analisador de strings de user agent.
O ClickHouse oferece suporte a [uap-core](https://github.com/ua-parser/uap-core) e você pode ver como usá-lo no teste funcional [02504\_regexp\_dictionary\_ua\_parser](https://github.com/ClickHouse/ClickHouse/blob/master/tests/queries/0_stateless/02504_regexp_dictionary_ua_parser.sh)
### Coletando valores de atributo
Às vezes, é útil retornar valores de várias expressões regulares correspondentes, em vez de apenas o valor de um nó folha. Nesses casos, a função especializada [`dictGetAll`](/pt-BR/reference/functions/regular-functions/ext-dict-functions#dictGetAll) pode ser usada. Se um nó tiver um valor de atributo do tipo `T`, `dictGetAll` retornará um `Array(T)` contendo zero ou mais valores.
Por padrão, o número de correspondências retornadas por chave é ilimitado. Um limite pode ser passado como quarto argumento opcional para `dictGetAll`. O array é preenchido em *ordem topológica*, o que significa que os nós filhos vêm antes dos nós pais, e os nós irmãos seguem a ordem da fonte.
Exemplo:
```sql theme={null}
CREATE DICTIONARY regexp_dict
(
regexp String,
tag String,
topological_index Int64,
captured Nullable(String),
parent String
)
PRIMARY KEY(regexp)
SOURCE(YAMLRegExpTree(PATH '/var/lib/clickhouse/user_files/regexp_tree.yaml'))
LAYOUT(regexp_tree)
LIFETIME(0)
```
```yaml theme={null}
# /var/lib/clickhouse/user_files/regexp_tree.yaml
- regexp: 'clickhouse\.com'
tag: 'ClickHouse'
topological_index: 1
paths:
- regexp: 'clickhouse\.com/docs(.*)'
tag: 'ClickHouse Documentation'
topological_index: 0
captured: '\1'
parent: 'ClickHouse'
- regexp: '/docs(/|$)'
tag: 'Documentation'
topological_index: 2
- regexp: 'github.com'
tag: 'GitHub'
topological_index: 3
captured: 'NULL'
```
```sql title="Query" theme={null}
CREATE TABLE urls (url String) ENGINE=MergeTree ORDER BY url;
INSERT INTO urls VALUES ('clickhouse.com'), ('clickhouse.com/docs/en'), ('github.com/clickhouse/tree/master/docs');
SELECT url, dictGetAll('regexp_dict', ('tag', 'topological_index', 'captured', 'parent'), url, 2) FROM urls;
```
```text title="Response" theme={null}
┌─url────────────────────────────────────┬─dictGetAll('regexp_dict', ('tag', 'topological_index', 'captured', 'parent'), url, 2)─┐
│ clickhouse.com │ (['ClickHouse'],[1],[],[]) │
│ clickhouse.com/docs/en │ (['ClickHouse Documentation','ClickHouse'],[0,1],['/en'],['ClickHouse']) │
│ github.com/clickhouse/tree/master/docs │ (['Documentation','GitHub'],[2,3],[NULL],[]) │
└────────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────┘
```
### Modos de correspondência
O comportamento da correspondência de padrões pode ser modificado com determinadas configurações do dicionário:
* `regexp_dict_flag_case_insensitive`: Usa correspondência sem diferenciar maiúsculas de minúsculas (o padrão é `false`). Pode ser sobrescrita em expressões individuais com `(?i)` e `(?-i)`.
* `regexp_dict_flag_dotall`: Permite que '.' corresponda a caracteres de nova linha (o padrão é `false`).
## Usar dicionário de árvore regexp no ClickHouse Cloud
A fonte [`YAMLRegExpTree`](/pt-BR/reference/statements/create/dictionary/sources/yamlregexptree) funciona no ClickHouse Open Source, mas não no ClickHouse Cloud.
Para usar dicionários de árvore regexp no ClickHouse Cloud, primeiro crie localmente, no ClickHouse Open Source, um dicionário de árvore regexp a partir de um arquivo YAML e, em seguida, exporte esse dicionário para um arquivo CSV usando a função de tabela `dictionary` e a cláusula [INTO OUTFILE](/pt-BR/reference/statements/select/into-outfile).
```sql theme={null}
SELECT * FROM dictionary(regexp_dict) INTO OUTFILE('regexp_dict.csv')
```
O conteúdo do arquivo CSV é:
```text theme={null}
1,0,"Linux/(\d+[\.\d]*).+tlinux","['version','name']","['\\1','TencentOS']"
2,0,"(\d+)/tclwebkit(\d+[\.\d]*)","['comment','version','name']","['test $1 and $2','$1','Android']"
3,2,"33/tclwebkit","['version']","['13']"
4,2,"3[12]/tclwebkit","['version']","['12']"
5,2,"3[12]/tclwebkit","['version']","['11']"
6,2,"3[12]/tclwebkit","['version']","['10']"
```
O esquema do arquivo exportado é:
* `id UInt64`: o ID do nó RegexpTree.
* `parent_id UInt64`: o ID do nó pai.
* `regexp String`: a expressão regular.
* `keys Array(String)`: os nomes dos atributos definidos pelo usuário.
* `values Array(String)`: os valores dos atributos definidos pelo usuário.
Para criar o dicionário no ClickHouse Cloud, primeiro crie uma tabela `regexp_dictionary_source_table` com a estrutura abaixo:
```sql theme={null}
CREATE TABLE regexp_dictionary_source_table
(
id UInt64,
parent_id UInt64,
regexp String,
keys Array(String),
values Array(String)
) ENGINE=Memory;
```
Em seguida, atualize o CSV local com
```bash theme={null}
clickhouse client \
--host MY_HOST \
--secure \
--password MY_PASSWORD \
--query "
INSERT INTO regexp_dictionary_source_table
SELECT * FROM input ('id UInt64, parent_id UInt64, regexp String, keys Array(String), values Array(String)')
FORMAT CSV" < regexp_dict.csv
```
Para mais detalhes, veja [Inserir arquivos locais](/pt-BR/integrations/connectors/data-ingestion/insert-local-files). Depois de inicializar a tabela de origem, podemos criar uma RegexpTree a partir da tabela de origem:
```sql theme={null}
CREATE DICTIONARY regexp_dict
(
regexp String,
name String,
version String
PRIMARY KEY(regexp)
SOURCE(CLICKHOUSE(TABLE 'regexp_dictionary_source_table'))
LIFETIME(0)
LAYOUT(regexp_tree);
```