С помощью движка MySQL FEDERATED вы можете подключаться к локальному или удалённому экземпляру Manticore из MySQL/MariaDB и выполнять поисковые запросы.

Непосредственно запрос Manticore нельзя использовать с движком FEDERATED из-за ограничений FEDERATED и того факта, что Manticore реализует собственный синтаксис, например, оператор MATCH.

Для поиска через FEDERATED сначала нужно создать таблицу с движком FEDERATED. Запрос Manticore будет включён в столбец query в операторе SELECT, выполняемом по таблице FEDERATED.

CREATE TABLE t1
(
    id          INTEGER UNSIGNED NOT NULL,
    year        INTEGER NOT NULL,
    rating      FLOAT,
    query       VARCHAR(1024) NOT NULL,
    INDEX(query)
) ENGINE=FEDERATED
DEFAULT CHARSET=utf8
CONNECTION='mysql://FEDERATED@127.0.0.1:9306/DB/movies';

Query OK, 0 rows affected (0.00 sec)

SELECT * FROM t1 WHERE query='SELECT * FROM movies WHERE MATCH (\'pie\')';

+----+------+--------+------------------------------------------+
| id | year | rating | query                                    |
+----+------+--------+------------------------------------------+
|  1 | 2019 |      5 | SELECT * FROM movies WHERE MATCH ('pie') |
+----+------+--------+------------------------------------------+
1 row in set (0.04 sec)

Единственное фиксированное сопоставление — это столбец query. Он обязателен и должен быть единственным столбцом, связанным с таблицей.

Таблица Manticore, связанная через FEDERATED, должна быть физической таблицей (обычной или реального времени).

Таблица FEDERATED должна иметь столбцы с такими же именами, как атрибуты удалённой таблицы Manticore, поскольку они будут связаны с атрибутами, предоставленными в наборе результатов Manticore по имени. Однако может быть сопоставлена только часть атрибутов, а не все.

Сервер Manticore идентифицирует запрос от клиента FEDERATED по имени пользователя "FEDERATED". Параметр строки CONNECTION используется для указания хоста Manticore, SQL-порта и таблиц для запросов, поступающих через соединение. Синтаксис строки соединения следующий:

CONNECTION="mysql://FEDERATED@HOST:PORT/DB/TABLENAME"

Поскольку в Manticore нет понятия базы данных, строка DB может быть произвольной, так как она будет игнорироваться Manticore, но MySQL требует значение в определении строки CONNECTION. Как видно из примера, полный SQL-запрос SELECT должен быть помещён в условие WHERE по столбцу query.

Поддерживается только оператор SELECT, не поддерживаются INSERT, REPLACE, UPDATE или DELETE.

Очень важно отметить, что гораздо эффективнее позволить Manticore выполнять сортировку, фильтрацию и нарезку набора результатов, чем увеличивать максимальное количество совпадений и использовать условия WHERE, ORDER BY и LIMIT на стороне MySQL. Это по двум причинам. Во-первых, Manticore реализует ряд оптимизаций и работает лучше MySQL для этих задач. Во-вторых, меньше данных нужно упаковывать searchd, передавать и распаковывать между Manticore и MySQL.

SELECT t1.id, t1.year, comments.comment FROM t1 JOIN comments ON t1.id=comments.post_id WHERE query='SELECT * FROM movies WHERE MATCH (\'pie\')';

+----+------+--------------+
| id | year | comment      |
+----+------+--------------+
|  1 | 2019 | was not good |
+----+------+--------------+
1 row in set (0.00 sec)

Manticore можно расширять пользовательскими функциями, или UDF (User-Defined Functions), вот так:

SELECT id, attr1, myudf (attr2, attr3+attr4) ...

Вы можете динамически загружать и выгружать UDF в searchd без необходимости перезапуска сервера и использовать их в выражениях при поиске, ранжировании и т.д. Краткое резюме возможностей UDF:

• UDF могут принимать аргументы типа integer (как 32-битные, так и 64-битные), float, string, MVA или PACKEDFACTORS().
• UDF могут возвращать значения типа integer, float или string.
• UDF могут проверять количество, типы и имена аргументов на этапе настройки запроса и выдавать ошибки.

Агрегационные функции пока не поддерживаются. Другими словами, ваши UDF вызываются для одного документа за раз и должны возвращать некоторое значение для этого документа. Написать функцию, которая может вычислять агрегатное значение, например AVG() по всей группе документов с одинаковым ключом GROUP BY, пока невозможно. Однако вы можете использовать UDF внутри встроенных агрегатных функций: то есть, хотя MYCUSTOMAVG() пока не поддерживается, AVG(MYCUSTOMFUNC()) будет работать отлично!

UDF имеют широкий спектр применения, например:

• внедрение пользовательских математических или строковых функций;
• доступ к базам данных или файлам изнутри Manticore;
• создание сложных функций ранжирования.

Плагины предоставляют дополнительные возможности для расширения функционала поиска. В настоящее время их можно использовать для вычисления пользовательских ранжировок и токенизации документов и запросов.

Вот полный список типов плагинов:

• UDF плагины (фактически UDF, но поскольку они подключаются как плагины, их также называют «UDF плагинами»)
• плагины ранжирования
• плагины фильтрации токенов во время индексации
• плагины фильтрации токенов во время выполнения запроса

В этом разделе описан общий процесс написания и управления плагинами; особенности создания разных типов плагинов рассматриваются в соответствующих подразделах.

Итак, как написать и использовать плагин? Вот краткое руководство из четырёх шагов:

• создать динамическую библиотеку (либо .so, либо .dll), скорее всего на C или C++;
• загрузить плагин в searchd с помощью CREATE PLUGIN;
• использовать плагин с помощью вызовов, специфичных для плагина (обычно через OPTIONS);
• выгрузить или перезагрузить плагин с помощью DROP PLUGIN и RELOAD PLUGINS соответственно.

Обратите внимание, что хотя UDF являются полноценными плагинами, они устанавливаются с помощью отдельного оператора CREATE FUNCTION. Это позволяет аккуратно указать тип возвращаемого значения, не жертвуя обратной совместимостью и не меняя синтаксис.

Динамические плагины поддерживаются в потоках и в thread_pool воркерах. Несколько плагинов (и/или UDF) могут содержаться в одном файле библиотеки. Вы можете либо сгруппировать все плагины проекта в одну большую библиотеку, либо создать отдельную библиотеку для каждого UDF и плагина — выбор за вами.

Как и для UDF, следует включить заголовочный файл src/sphinxudf.h. Минимум, что вам понадобится — это константа SPH_UDF_VERSION для реализации соответствующей функции версии. В зависимости от типа плагина, может потребоваться или не потребоваться линковка с src/sphinxudf.c. Однако все функции, реализованные в sphinxudf.c, связаны с распаковкой blob PACKEDFACTORS(), и ни один тип плагинов не имеет доступа к этим данным. Поэтому на данный момент достаточно линковки только с заголовочным файлом. (Фактически, если вы скопируете номер версии UDF, то для некоторых типов плагинов даже заголовочный файл не понадобится.)

Формально, плагины — это просто наборы функций на C, которые следуют определённому шаблону именования. Обычно требуется определить одну ключевую функцию для основной задачи, но можно определить и дополнительные функции. Например, чтобы реализовать ранжировщик с именем "myrank", нужно определить функцию myrank_finalize(), которая возвращает значение ранга. Но можно также определить функции myrank_init(), myrank_update() и myrank_deinit(). Конкретные наборы известных суффиксов и аргументов вызова зависят от типа плагина, но _init() и _deinit() универсальны и есть у каждого плагина. Подсказка: для быстрого ознакомления с известными суффиксами и типами аргументов смотрите sphinxplugin.h, где прототипы вызовов определены в начале файла.

Хотя публичный интерфейс определён на чистом C, наши плагины фактически следуют объектно-ориентированной модели. Действительно, каждая функция _init() получает параметр void ** userdata для вывода, и указатель, сохранённый в (*userdata), затем передаётся как первый аргумент всем остальным функциям плагина. Так что можно считать плагин классом, который создаётся каждый раз, когда нужен объект этого класса для обработки запроса: указатель userdata служит указателем this; функции выступают как методы, а функции _init() и _deinit() работают как конструктор и деструктор соответственно.

Это небольшое усложнение ООП в C возникает потому, что плагины работают в многопоточном окружении, и некоторым нужно хранить состояние. Нельзя хранить это состояние в глобальной переменной плагина, поэтому мы передаём параметр userdata, что естественно ведёт к модели ООП. Если ваш плагин простой и без состояния, интерфейс позволяет опустить _init(), _deinit() и любые другие функции.

В итоге, вот самый простой полный плагин ранжировщика всего из трёх строк кода на C:

// gcc -fPIC -shared -o myrank.so myrank.c
#include "sphinxudf.h"
int myrank_ver() { return SPH_UDF_VERSION; }
int myrank_finalize(void *u, int w) { return 123; }

Вот как использовать простой плагин ранжировщика:

mysql> CREATE PLUGIN myrank TYPE 'ranker' SONAME 'myrank.dll';
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT id, weight() FROM test1 WHERE MATCH('test') OPTION ranker=myrank('');
+------+----------+
| id   | weight() |
+------+----------+
|    1 |      123 |
|    2 |      123 |
+------+----------+
2 rows in set (0.01 sec)