# Плагины фильтров токенов

Плагины фильтров токенов позволяют реализовать пользовательский токенизатор, который создает токены согласно пользовательским правилам. Существует два типа:

* Токенизатор времени индексирования, объявленный с помощью [index_token_filter](../../../Creating_a_table/NLP_and_tokenization/Low-level_tokenization.md#index_token_filter) в настройках таблицы
* Токенизатор времени запроса, объявленный директивой OPTION [token_filter](../../../Searching/Options.md#token_filter)

В конвейере обработки текста фильтры токенов выполняются после обработки базового токенизатора (который обрабатывает текст из полей или запросов и создает токены из них).

## Токенизатор времени индексирования

Токенизатор времени индексирования создается `indexer` при индексировании исходных данных в таблицу или RT таблицей при обработке операторов `INSERT` или `REPLACE`.

Плагин объявляется как `имя библиотеки:имя плагина:необязательная строка настроек`. Функции инициализации плагина могут принимать произвольные настройки, которые можно передать в виде строки в формате `option1=value1;option2=value2;..`.

Пример:

```ini
index_token_filter = my_lib.so:email_process:field=email;split=.io
```

Последовательность вызовов для фильтра токенов времени индексирования следующая:

1.  Вызывается `XXX_init()` сразу после того, как `indexer` создает фильтр токенов с пустым списком полей, а затем после того, как indexer получает схему таблицы с фактическим списком полей. Он должен возвращать ноль при успешной инициализации или описание ошибки в противном случае.
2.  Вызывается `XXX_begin_document` только для RT таблиц при операциях `INSERT`/`REPLACE` для каждого документа. Он должен возвращать ноль при успешном вызове или описание ошибки в противном случае. С помощью OPTION `token_filter_options` можно передавать дополнительные параметры/настройки в функцию.
    ```sql
    INSERT INTO rt (id, title) VALUES (1, 'some text corp@space.io') OPTION token_filter_options='.io'
    ```
3.  Вызывается `XXX_begin_field` один раз для каждого поля перед обработкой поля базовым токенизатором, с номером поля в качестве параметра.
4.  Вызывается `XXX_push_token` один раз для каждого нового токена, созданного базовым токенизатором, с исходным токеном в качестве параметра. Он должен возвращать токен, количество дополнительных токенов, созданных фильтром токенов, и дельту позиции для токена.
5.  Вызывается `XXX_get_extra_token` несколько раз в случае, если `XXX_push_token` сообщает о дополнительных токенах. Он должен возвращать токен и дельту позиции для данного дополнительного токена.
6.  Вызывается `XXX_end_field` один раз сразу после обработки исходных токенов из текущего поля.
7.  Вызывается `XXX_deinit` в самом конце индексации.

Следующие функции обязательны для определения: `XXX_begin_document`, `XXX_push_token` и `XXX_get_extra_token`.

## Фильтр токенов времени запроса

Токенизатор времени запроса создается при каждом поиске полнотекстового запроса для каждой задействованной таблицы.

Последовательность вызовов для фильтра токенов времени запроса следующая:

1.  Вызывается `XXX_init()` один раз для каждой таблицы до разбора запроса с параметрами — максимальная длина токена и строка, установленная опцией `token_filter`
    ```sql
    SELECT * FROM index WHERE MATCH ('test') OPTION token_filter='my_lib.so:query_email_process:io'
    ```
    Он должен возвращать ноль при успешной инициализации или описание ошибки в противном случае.
2.  Вызывается `XXX_push_token()` один раз для каждого нового токена, созданного базовым токенизатором, с параметрами: токен, созданный базовым токенизатором, указатель на необработанный токен в исходной строке запроса и длина необработанного токена. Он должен возвращать токен и дельту позиции для токена.
3.  Вызывается `XXX_pre_morph()` один раз для токена непосредственно перед передачей в морфологический процессор с передачей ссылки на токен и флага стоп-слова. Может устанавливать флаг стоп-слова, чтобы пометить токен как стоп-слово.
4.  Вызывается `XXX_post_morph()` один раз для токена после обработки морфологическим процессором с передачей ссылки на токен и флага стоп-слова. Может устанавливать флаг стоп-слова, чтобы пометить токен как стоп-слово. Должен возвращать флаг, ненулевое значение которого означает использование токена до морфологической обработки.
5.  Вызывается `XXX_deinit()` в самом конце обработки запроса.

Отсутствие функций допускается.

<!-- proofread -->

