---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ydb.tech/docs/en/yql/reference/syntax/select/fulltext_index.md?version=main
  - https://ydb.tech/docs/ru/yql/reference/syntax/select/fulltext_index.md?version=main
sourcePath: ru/core/yql/reference/syntax/select/fulltext_index.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt

# VIEW (Полнотекстовый индекс)

Для выполнения запроса `SELECT` с использованием [полнотекстового индекса](https://ydb.tech/docs/ru/dev/fulltext-indexes.md?version=main) в строковой таблице используйте выражение `VIEW`:

```yql
SELECT ...
FROM TableName VIEW IndexName
WHERE FulltextMatch(TextColumn, "query")
ORDER BY ...
```

{% note info %}

Полнотекстовый индекс не будет автоматически выбран [оптимизатором](https://ydb.tech/docs/ru/concepts/glossary.md?version=main#optimizer), поэтому его нужно указывать явно с помощью `VIEW IndexName`.

Функции полнотекстового поиска (`FulltextMatch`, `FulltextScore`) требуют `VIEW`. Если `VIEW` не используется, запрос завершится с ошибкой.

В одном чтении через `VIEW` поддерживается только один полнотекстовый предикат. `FulltextMatch` / `FulltextScore` нельзя использовать под `OR` или `NOT`.
Для доступа к индексу по релевантности требуется ограничение `FulltextScore(...) > 0` в `WHERE`.

Описание функций см. в разделе [Полнотекстовый поиск](https://ydb.tech/docs/ru/yql/reference/builtins/fulltext.md?version=main), включая
[FulltextMatch](https://ydb.tech/docs/ru/yql/reference/builtins/fulltext.md?version=main#fulltext-match) и
[FulltextScore](https://ydb.tech/docs/ru/yql/reference/builtins/fulltext.md?version=main#fulltext-score).

{% endnote %}

## FulltextMatch

[FulltextMatch(text, query)](https://ydb.tech/docs/ru/yql/reference/builtins/fulltext.md?version=main#fulltext-match) фильтрует строки по совпадению текста с полнотекстовым запросом:

```yql
SELECT id, title
FROM articles VIEW ft_idx
WHERE FulltextMatch(body, "машинное обучение")
LIMIT 20;
```

Только первые два аргумента могут быть позиционными. Дополнительные параметры нужно передавать как **именованные аргументы**:

* `Mode` (String): вид запроса:
  * `Keywords` (по умолчанию) — текст запроса разбивается на отдельные термы; логика их объединения определяется `DefaultOperator`
  * `Query` — расширенный синтаксис с логическими операторами: обязательные термы через `+`, исключённые через `-`, точные фразы в двойных кавычках
  * `Wildcard` — поиск с подстановочными символами: `%` заменяет любую подстроку, `_` — один символ (аналогично `LIKE`); требует N-граммного индекса
* `DefaultOperator` (String): оператор объединения термов в режиме `Keywords`:
  * `And` (по умолчанию) — все термы запроса должны присутствовать в тексте
  * `Or` — термы делятся на **обязательные** (с префиксом `+`, должны присутствовать в каждом результате) и **необязательные** (без префикса, учитываются в `MinimumShouldMatch`). Без префикса `+` все термы считаются необязательными, и достаточно совпадения хотя бы одного (см. [пример](https://ydb.tech/docs/ru/yql/reference/builtins/fulltext.md?version=main#required-term-example))
* `MinimumShouldMatch` (String): минимальное число **необязательных** термов, которые должны совпасть при `DefaultOperator = "Or"` — задаётся как абсолютное число (например, `"3"`) или процент от числа необязательных термов (например, `"50%"`). Обязательные (`+`) термы в счёт не входят

### Режим `Wildcard` и шаблоны `%` / `_` (требуются N-граммы)

Если индекс создан с фильтрацией N-грамм, можно использовать шаблоны с `%` и `_` (по аналогии с `LIKE`).
Чтобы явно указать такой режим, передайте именованный аргумент `"Wildcard" AS Mode`:

```yql
SELECT id, title
FROM articles VIEW ft_idx
WHERE FulltextMatch(body, "маш% обу%ние", "Wildcard" AS Mode)
LIMIT 20;
```

### LIKE / ILIKE (используют полнотекстовый индекс)

Для полнотекстовых индексов с N-граммами поддерживается `LIKE`/`ILIKE` по текстовой колонке. Такие предикаты используют ту же логику, что и `FulltextMatch(..., "Wildcard" AS Mode)`:

```yql
SELECT id, title
FROM articles VIEW ft_idx
WHERE body ILIKE "%обуч%ние%"
LIMIT 20;
```

## FulltextScore

[FulltextScore(text, query)](https://ydb.tech/docs/ru/yql/reference/builtins/fulltext.md?version=main#fulltext-score) возвращает оценку релевантности ([BM25](https://en.wikipedia.org/wiki/Okapi_BM25)) и может использоваться для ранжирования.
Ранжирование требует индекса типа [fulltext_relevance](https://ydb.tech/docs/ru/dev/fulltext-indexes.md?version=main#relevance).

```yql
SELECT id, title, FulltextScore(body, "машинное обучение") AS relevance
FROM articles VIEW ft_idx
WHERE FulltextScore(body, "машинное обучение") > 0
ORDER BY relevance DESC
LIMIT 10;
```

### Дополнительные параметры

Дополнительные параметры нужно передавать как **именованные аргументы**:

* `DefaultOperator` (String): оператор объединения термов — `And` (по умолчанию, все термы должны присутствовать) или `Or` (термы делятся на **обязательные** с префиксом `+` и **необязательные** без префикса; каждый обязательный должен присутствовать, а из необязательных должны совпасть не менее `MinimumShouldMatch`)
* `MinimumShouldMatch` (String): при `DefaultOperator = "Or"` — минимальное число **необязательных** термов, которые должны совпасть; задаётся как абсолютное число (например, `"2"`) или процент от числа необязательных термов (например, `"50%"`). Обязательные (`+`) термы в счёт не входят
* `K1` (Double): параметр насыщения частоты терма в [BM25](https://en.wikipedia.org/wiki/Okapi_BM25) — определяет, насколько сильно влияет повторное появление терма на итоговую оценку; типичный диапазон: 1.2–2.0
* `B` (Double): параметр нормализации длины документа в [BM25](https://en.wikipedia.org/wiki/Okapi_BM25) — `0.0` отключает нормализацию, `1.0` полностью нормализует по длине документа; типичное значение: 0.75

Пример:

```yql
SELECT id, FulltextScore(body, "машинное обучение", "Or" AS DefaultOperator, "50%" AS MinimumShouldMatch) AS relevance
FROM articles VIEW ft_idx
WHERE FulltextScore(body, "машинное обучение", "Or" AS DefaultOperator, "50%" AS MinimumShouldMatch) > 0
ORDER BY relevance DESC;
```

{% note info %}

Только первые два аргумента `FulltextMatch` / `FulltextScore` могут быть позиционными. Для дополнительных параметров используйте именованные аргументы.

Выражение `FulltextScore(...)` повторяется в `SELECT` и `WHERE` целиком — YQL, как и стандартный SQL, вычисляет `WHERE` раньше `SELECT`, поэтому псевдонимы из `SELECT` недоступны в `WHERE`. Оба вхождения должны быть идентичны.

{% endnote %}