> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Extensão vsql_trgm para MySQL

> A extensão vsql_trgm traz ao MySQL a similaridade por trigramas do pg_trgm, pontuando o quanto duas strings se parecem para que um termo de busca com erro de grafia ainda encontre a sua linha.

O `vsql_trgm` é um port do `pg_trgm` do PostgreSQL. Ele divide uma string em
pedaços de três caracteres e pontua duas strings por quantos pedaços elas
compartilham, de modo que um termo de busca com erro de grafia ainda encontra a
sua linha. Use-o quando o `LIKE` é estrito demais e a busca de texto completo é
grosseira demais.

| | |
| - | - |
| **Mantenedor** | VillageSQL |
| **Código-fonte e documentação completa** | [villagesql/vsql-trgm](https://github.com/villagesql/vsql-trgm) |
| **Licença** | GPL-2.0 |

## Instalar

O `vsql_trgm.veb` já está no diretório `lib/veb/` do servidor se você instalou
o VillageSQL com o script de instalação, a imagem Docker ou um tarball de
release. Instale-o no servidor com uma única instrução:

```sql theme={null}
INSTALL EXTENSION vsql_trgm;
```

Confirme que ele está lá:

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_trgm';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_trgm      |
+----------------+
```

Para compilá-lo você mesmo, siga as instruções de compilação no
[repositório](https://github.com/villagesql/vsql-trgm).

## O que ela adiciona

Ela adiciona três famílias de função. A família simples compara duas strings
inteiras. A família de palavra encontra a substring da segunda string que
melhor corresponde. A família estrita de palavra faz o mesmo, mas se alinha
nos limites das palavras. Cada família tem o seu próprio limiar padrão.

| Função | Retorna | O que faz |
| - | - | - |
| `trgm_show(s)` | texto | Os trigramas de uma string, como um array JSON |
| `trgm_similarity(a, b)` | real | A fração de trigramas que as duas strings têm em comum, de 0 a 1 |
| `trgm_distance(a, b)` | real | 1 menos a similaridade |
| `trgm_similar(a, b)` | int | 1 quando a similaridade atinge 0,3 |
| `trgm_similar_threshold(a, b, t)` | int | 1 quando ela atinge um limiar que você escolhe, entre 0 e 1 |
| `trgm_word_similarity(a, b)` | real | A melhor similaridade entre `a` e qualquer substring de `b` |
| `trgm_word_distance(a, b)` | real | 1 menos isso |
| `trgm_word_similar(a, b)` | int | 1 quando a similaridade de palavra atinge 0,6 |
| `trgm_strict_word_similarity(a, b)` | real | O mesmo que a forma de palavra, alinhado nos limites das palavras |
| `trgm_strict_word_distance(a, b)` | real | 1 menos isso |
| `trgm_strict_word_similar(a, b)` | int | 1 quando a similaridade estrita de palavra atinge 0,5 |

## Exemplo

Monte uma pequena tabela de nomes:

```sql theme={null}
CREATE TABLE people (id INT PRIMARY KEY, name VARCHAR(32));

INSERT INTO people VALUES
    (1, 'Jonathan Smith'),
    (2, 'John Smyth'),
    (3, 'Joan Smithe'),
    (4, 'Peter Brown');
```

Busque nela por uma grafia que ninguém digitou e ordene o que volta:

```sql theme={null}
SELECT name, ROUND(trgm_similarity(name, 'Jon Smith'), 3) AS score
FROM people
WHERE trgm_similar(name, 'Jon Smith') = 1
ORDER BY score DESC;
```

```
+----------------+-------+
| name           | score |
+----------------+-------+
| Jonathan Smith | 0.562 |
| Joan Smithe    | 0.467 |
| John Smyth     | 0.312 |
+----------------+-------+
```

Peter Brown compartilha trigramas de menos para atingir 0,3, então nunca
aparece. Para ver o que está sendo comparado, peça os próprios trigramas:

```sql theme={null}
SELECT trgm_show('Smith') AS trigrams;
```

```
+---------------------------------------+
| trigrams                              |
+---------------------------------------+
| ["  s"," sm","ith","mit","smi","th "] |
+---------------------------------------+
```

Os espaços de preenchimento são intencionais. Eles permitem que o início e o
fim de uma string contem para a pontuação.

> [!NOTE]
>
> O `set_limit()` do PostgreSQL não tem equivalente aqui, porque o `vsql_trgm`
> não mantém estado de sessão. Em vez disso, passe o limiar que você quer para
> o `trgm_similar_threshold()`. Um filtro de similaridade também lê todas as
> linhas, então meça-o antes de executar um contra uma tabela grande.

## Veja também

* [Similaridade por trigramas no MySQL](https://villagesql.com/docs/en/guides/trigram-similarity.md) — limiares, ordenação e o que custa em uma tabela grande
* [Correspondência aproximada de strings](https://villagesql.com/docs/en/guides/fuzzy-string-matching.md) — códigos fonéticos e distância de edição como alternativas
* [Busca de texto completo](https://villagesql.com/docs/en/guides/full-text-search.md) — a ferramenta certa para documentos, e não para nomes
* [Instalar extensões](https://villagesql.com/docs/pt-BR/extensions/install.md) — como o `INSTALL EXTENSION` funciona e onde o servidor procura um bundle
* [Extensões disponíveis](https://villagesql.com/docs/pt-BR/extensions/catalog) — o catálogo completo
* [villagesql/vsql-trgm](https://github.com/villagesql/vsql-trgm) — código-fonte, instruções de compilação e as limitações conhecidas


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.