SphinxSE — это механизм хранения MySQL, который можно встроить в серверы MySQL/MariaDB с помощью их подключаемой архитектуры.

Несмотря на название, SphinxSE сам по себе не хранит никаких данных. Вместо этого он служит встроенным клиентом, который позволяет серверу MySQL взаимодействовать с searchd, выполнять поисковые запросы и получать результаты поиска. Все операции индексирования и поиска происходят вне MySQL.

Некоторые типичные сценарии использования SphinxSE включают:

• Упрощение перевода приложений с использованием полнотекстового поиска (FTS) MySQL на Manticore;
• Возможность использования Manticore с языками программирования, для которых пока нет нативных API;
• Предоставление оптимизаций, когда требуется дополнительная обработка результирующего набора Manticore на стороне MySQL (например, JOIN с таблицами исходных документов или дополнительная фильтрация на стороне MySQL).

Вам потребуется получить копию исходного кода MySQL, подготовить её, а затем пересобрать бинарный файл MySQL. Исходный код MySQL (mysql-5.x.yy.tar.gz) можно получить с сайта http://dev.mysql.com.

1. Скопируйте файл патча sphinx.5.0.yy.diff в каталог исходного кода MySQL и выполните

   $ patch -p1 < sphinx.5.0.yy.diff

   Если нет .diff файла для вашей конкретной версии, попробуйте применить .diff с наиболее близкими номерами версий. Важно, чтобы патч применился без конфликтов.

2. В каталоге исходного кода MySQL выполните

   $ sh BUILD/autorun.sh

3. В каталоге исходного кода MySQL создайте каталог sql/sphinx и скопируйте туда все файлы из каталога mysqlse из исходного кода Manticore. Пример:

   $ cp -R /root/builds/sphinx-0.9.7/mysqlse /root/builds/mysql-5.0.24/sql/sphinx

4. Сконфигурируйте MySQL и включите новый механизм:

   $ ./configure --with-sphinx-storage-engine

5. Соберите и установите MySQL:

   $ make
   $ make install

1. В каталоге исходного кода MySQL создайте каталог storage/sphinx и скопируйте все файлы из каталога mysqlse в исходном коде Manticore в это новое место. Например:

   $ cp -R /root/builds/sphinx-0.9.7/mysqlse /root/builds/mysql-5.1.14/storage/sphinx

2. В каталоге исходного кода MySQL выполните:

   $ sh BUILD/autorun.sh

3. Сконфигурируйте MySQL и включите механизм Manticore:

   $ ./configure --with-plugins=sphinx

4. Соберите и установите MySQL:

   $ make
   $ make install

mysql> show engines;

+------------+----------+-------------------------------------------------------------+
| Engine     | Support  | Comment                                                     |
+------------+----------+-------------------------------------------------------------+
| MyISAM     | DEFAULT  | Default engine as of MySQL 3.23 with great performance      |
  ...
| SPHINX     | YES      | Manticore storage engine                                       |
  ...
+------------+----------+-------------------------------------------------------------+
13 rows in set (0.00 sec)

Для поиска с помощью SphinxSE вам необходимо создать специальную "поисковую таблицу" с ENGINE=SPHINX, а затем использовать оператор SELECT, поместив полнотекстовый запрос в условие WHERE для столбца запроса.

Вот пример создания таблицы и поискового запроса:

CREATE TABLE t1
(
    id          INTEGER UNSIGNED NOT NULL,
    weight      INTEGER NOT NULL,
    query       VARCHAR(3072) NOT NULL,
    group_id    INTEGER,
    INDEX(query)
) ENGINE=SPHINX CONNECTION="sphinx://localhost:9312/test";
SELECT * FROM t1 WHERE query='test it;mode=any';

В поисковой таблице первые три столбца должны иметь следующие типы: INTEGER UNSIGNED или BIGINT для 1-го столбца (ID документа), INTEGER или BIGINT для 2-го столбца (вес совпадения) и VARCHAR или TEXT для 3-го столбца (ваш запрос). Это соответствие фиксировано; вы не можете опустить какой-либо из этих трёх обязательных столбцов, поменять их местами или изменить их типы. Кроме того, столбец запроса должен быть проиндексирован, а все остальные — нет. Имена столбцов игнорируются, поэтому вы можете использовать произвольные имена.

Дополнительные столбцы должны быть типа INTEGER, TIMESTAMP, BIGINT, VARCHAR или FLOAT. Они будут привязаны к атрибутам, предоставляемым в результирующем наборе Manticore, по имени, поэтому их имена должны совпадать с именами атрибутов, указанными в sphinx.conf. Если в результатах поиска Manticore нет соответствующего имени атрибута, столбец будет содержать значения NULL.

Специальные "виртуальные" имена атрибутов также могут быть привязаны к столбцам SphinxSE. Используйте для этого _sph_ вместо @. Например, чтобы получить значения виртуальных атрибутов @groupby, @count или @distinct, используйте имена столбцов _sph_groupby, _sph_count или _sph_distinct соответственно.

Параметр строки CONNECTION используется для указания хоста, порта и таблицы Manticore. Если строка подключения не указана в CREATE TABLE, предполагается имя таблицы * (т.е. поиск по всем таблицам) и localhost:9312. Синтаксис строки подключения следующий:

CONNECTION="sphinx://HOST:PORT/TABLENAME"

Вы можете изменить строку подключения по умолчанию позже:

mysql> ALTER TABLE t1 CONNECTION="sphinx://NEWHOST:NEWPORT/NEWTABLENAME";

Вы также можете переопределить эти параметры для каждого запроса.

Как показано в примере, текст запроса и параметры поиска должны быть помещены в условие WHERE для столбца поискового запроса (т.е. 3-го столбца). Параметры разделяются точкой с запятой, а их имена от значений — знаком равенства. Можно указать любое количество параметров. Доступные параметры:

• query - текст запроса;
• mode - режим соответствия. Должен быть одним из "all", "any", "phrase", "boolean" или "extended". По умолчанию "all";
• sort - режим сортировки совпадений. Должен быть одним из "relevance", "attr_desc", "attr_asc", "time_segments" или "extended". Во всех режимах, кроме "relevance", после двоеточия также требуется указать имя атрибута (или условие сортировки для "extended"):

  ... WHERE query='test;sort=attr_asc:group_id';
  ... WHERE query='test;sort=extended:@weight desc, group_id asc';

• offset - смещение в наборе результатов; по умолчанию 0;
• limit - количество совпадений для извлечения из набора результатов; по умолчанию 20;
• index - имена таблиц для поиска:

  ... WHERE query='test;index=test1;';
  ... WHERE query='test;index=test1,test2,test3;';

• minid, maxid - минимальный и максимальный идентификатор документа для соответствия;
• weights - список весов, разделенных запятыми, для назначения полнотекстовым полям Manticore:

  ... WHERE query='test;weights=1,2,3;';

• filter, !filter - имя атрибута и набор значений для соответствия, разделенные запятыми:

  # only include groups 1, 5 and 19
  ... WHERE query='test;filter=group_id,1,5,19;';
  # exclude groups 3 and 11
  ... WHERE query='test;!filter=group_id,3,11;';

• range, !range - имя атрибута Manticore (целочисленного или bigint), минимальное и максимальное значения для соответствия, разделенные запятыми:

  # include groups from 3 to 7, inclusive
  ... WHERE query='test;range=group_id,3,7;';
  # exclude groups from 5 to 25
  ... WHERE query='test;!range=group_id,5,25;';

• floatrange, !floatrange - имя атрибута Manticore (с плавающей точкой), минимальное и максимальное значения для соответствия, разделенные запятыми:

  # filter by a float size
  ... WHERE query='test;floatrange=size,2,3;';
  # pick all results within 1000 meter from geoanchor
  ... WHERE query='test;floatrange=@geodist,0,1000;';

• maxmatches - значение maxmatches для запроса, как в опции поиска max_matches:

  ... WHERE query='test;maxmatches=2000;';

• cutoff - максимально допустимое количество совпадений, как в опции поиска cutoff:

  ... WHERE query='test;cutoff=10000;';

• maxquerytime - максимально допустимое время выполнения запроса (в миллисекундах), как в опции поиска max_query_time:

  ... WHERE query='test;maxquerytime=1000;';

• groupby - функция группировки и атрибут. Прочтите это о группировке результатов поиска:

  ... WHERE query='test;groupby=day:published_ts;';
  ... WHERE query='test;groupby=attr:group_id;';

• groupsort - условие сортировки для группировки:

  ... WHERE query='test;groupsort=@count desc;';

• distinct - атрибут для вычисления COUNT(DISTINCT) при выполнении группировки:

  ... WHERE query='test;groupby=attr:country_id;distinct=site_id';

• indexweights - список имен таблиц и весов, разделенных запятыми, для использования при поиске по нескольким таблицам:

  ... WHERE query='test;indexweights=tbl_exact,2,tbl_stemmed,1;';

• fieldweights - список весов для каждого поля, разделенных запятыми, которые могут использоваться ранкером:

  ... WHERE query='test;fieldweights=title,10,abstract,3,content,1;';

• comment - строка для пометки этого запроса в журнале запросов, как в опции поиска comment:

  ... WHERE query='test;comment=marker001;';

• select - строка с выражениями для вычисления:

  ... WHERE query='test;select=2*a+3*** as myexpr;';

• host, port - имя удаленного хоста searchd и TCP-порт соответственно:

  ... WHERE query='test;host=sphinx-test.loc;port=7312;';

• ranker - функция ранжирования для использования с режимом соответствия "extended", как в ranker. Известные значения: "proximity_bm25", "bm25", "none", "wordcount", "proximity", "matchany", "fieldmask", "sph04", синтаксис "expr:EXPRESSION" для поддержки ранкера на основе выражений (где EXPRESSION следует заменить на вашу конкретную формулу ранжирования) и "export:EXPRESSION":

  ... WHERE query='test;mode=extended;ranker=bm25;';
  ... WHERE query='test;mode=extended;ranker=expr:sum(lcs);';

  Ранкер "export" функционирует аналогично ranker=expr, но сохраняет значения факторов для каждого документа, в то время как ranker=expr отбрасывает их после вычисления итогового значения WEIGHT(). Имейте в виду, что ranker=export предназначен для эпизодического использования, например, для обучения функции машинного обучения (ML) или ручного определения собственной функции ранжирования, и не должен использоваться в реальной производственной среде. При использовании этого ранкера вам, вероятно, захочется изучить вывод функции RANKFACTORS(), которая генерирует строку, содержащую все факторы на уровне полей для каждого документа.

SELECT *, WEIGHT(), RANKFACTORS()
    FROM myindex
    WHERE MATCH('dog')
    OPTION ranker=export('100*bm25');

*************************** 1\. row ***************************
           id: 555617
    published: 1110067331
   channel_id: 1059819
        title: 7
      content: 428
     weight(): 69900
rankfactors(): bm25=699, bm25a=0.666478, field_mask=2,
doc_word_count=1, field1=(lcs=1, hit_count=4, word_count=1,
tf_idf=1.038127, min_idf=0.259532, max_idf=0.259532, sum_idf=0.259532,
min_hit_pos=120, min_best_span_pos=120, exact_hit=0,
max_window_hits=1), word1=(tf=4, idf=0.259532)
*************************** 2\. row ***************************
           id: 555313
    published: 1108438365
   channel_id: 1058561
        title: 8
      content: 249
     weight(): 68500
rankfactors(): bm25=685, bm25a=0.675213, field_mask=3,
doc_word_count=1, field0=(lcs=1, hit_count=1, word_count=1,
tf_idf=0.259532, min_idf=0.259532, max_idf=0.259532, sum_idf=0.259532,
min_hit_pos=8, min_best_span_pos=8, exact_hit=0, max_window_hits=1),
field1=(lcs=1, hit_count=2, word_count=1, tf_idf=0.519063,
min_idf=0.259532, max_idf=0.259532, sum_idf=0.259532, min_hit_pos=36,
min_best_span_pos=36, exact_hit=0, max_window_hits=1), word1=(tf=3,
idf=0.259532)

• geoanchor - якорь геодистанции. Узнайте больше о геопоиске в этом разделе. Принимает 4 параметра, которые являются именами атрибутов широты и долготы и координатами точки якоря соответственно:

  ... WHERE query='test;geoanchor=latattr,lonattr,0.123,0.456';

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

Начиная с версии 5.0.0, Manticore по умолчанию хранит все поля. Когда Manticore используется вместе с MySQL или MariaDB через SphinxSE, хранение всех полей обычно не имеет смысла, потому что оригиналы уже хранятся в MySQL/MariaDB. В таких конфигурациях рекомендуется явно отключить хранимые поля для задействованной таблицы Manticore, установив:

stored_fields =

См. справочник по настройке: stored_fields.

Если вы сохраните значение по умолчанию (все поля хранятся) и затем выберете много документов сразу через SphinxSE, может быть превышен внутренний лимит в движке, и вы можете получить ошибку типа:

"bad searchd response length"

Установка stored_fields = позволяет избежать отправки больших хранимых полезных нагрузок обратно в MySQL/MariaDB и предотвращает эту ошибку в типичных интеграциях SphinxSE.

mysql> SHOW ENGINE SPHINX STATUS;

+--------+-------+-------------------------------------------------+
| Type   | Name  | Status                                          |
+--------+-------+-------------------------------------------------+
| SPHINX | stats | total: 25, total found: 25, time: 126, words: 2 |
| SPHINX | words | sphinx:591:1256 soft:11076:15945                |
+--------+-------+-------------------------------------------------+
2 rows in set (0.00 sec)

mysql> SHOW STATUS LIKE 'sphinx_%';

+--------------------+----------------------------------+
| Variable_name      | Value                            |
+--------------------+----------------------------------+
| sphinx_total       | 25                               |
| sphinx_total_found | 25                               |
| sphinx_time        | 126                              |
| sphinx_word_count  | 2                                |
| sphinx_words       | sphinx:591:1256 soft:11076:15945 |
+--------------------+----------------------------------+
5 rows in set (0.00 sec)

mysql> SELECT content, date_added FROM test.documents docs
-> JOIN t1 ON (docs.id=t1.id)
-> WHERE query="one document;mode=any";
mysql> SHOW ENGINE SPHINX STATUS;

+-------------------------------------+---------------------+
| content                             | docdate             |
+-------------------------------------+---------------------+
| this is my test document number two | 2006-06-17 14:04:28 |
| this is my test document number one | 2006-06-17 14:04:28 |
+-------------------------------------+---------------------+
2 rows in set (0.00 sec)
+--------+-------+---------------------------------------------+
| Type   | Name  | Status                                      |
+--------+-------+---------------------------------------------+
| SPHINX | stats | total: 2, total found: 2, time: 0, words: 2 |
| SPHINX | words | one:1:2 document:2:2                        |
+--------+-------+---------------------------------------------+
2 rows in set (0.00 sec)

SphinxSE также включает UDF-функцию, которая позволяет создавать сниппеты с помощью MySQL. Эта функциональность аналогична HIGHLIGHT(), но доступна через MySQL+SphinxSE.

Двоичный файл, предоставляющий UDF, называется sphinx.so и должен автоматически собираться и устанавливаться в соответствующее место вместе с SphinxSE. Если по какой-то причине он не устанавливается автоматически, найдите sphinx.so в директории сборки и скопируйте его в каталог плагинов вашего экземпляра MySQL. После этого зарегистрируйте UDF следующей командой:

CREATE FUNCTION sphinx_snippets RETURNS STRING SONAME 'sphinx.so';

Имя функции обязательно должно быть sphinx_snippets; использовать произвольное имя нельзя. Аргументы функции следующие:

Прототип: function sphinx_snippets ( document, table, words [, options] );

Аргументы document и words могут быть строками или столбцами таблицы. Опции должны быть указаны следующим образом: 'value' AS option_name. Для списка поддерживаемых опций обратитесь к разделу Выделение текста. Единственная дополнительная опция, специфичная для UDF, называется sphinx и позволяет указать расположение searchd (хост и порт).

Примеры использования:

SELECT sphinx_snippets('hello world doc', 'main', 'world',
    'sphinx://192.168.1.1/' AS sphinx, true AS exact_phrase,
    '[**]' AS before_match, '[/**]' AS after_match)
FROM documents;
SELECT title, sphinx_snippets(text, 'table', 'mysql php') AS text
    FROM sphinx, documents
    WHERE query='mysql php' AND sphinx.id=documents.id;

С помощью движка 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, обязательно должна быть физической таблицей (plain или real-time).

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

Сервер Manticore идентифицирует запрос от клиента FEDERATED по имени пользователя "FEDERATED". Параметр CONNECTION string используется для указания хоста 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, например так:

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

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

• UDF могут принимать целочисленные (как 32-битные, так и 64-битные), вещественные, строковые аргументы, аргументы типа MVA или PACKEDFACTORS().
• UDF могут возвращать целочисленные, вещественные или строковые значения.
• 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, связаны с распаковкой бинарных данных 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)

UDF хранятся во внешних динамических библиотеках (.so файлы в UNIX и .dll в системах Windows). Файлы библиотек должны быть размещены в доверенной папке, указанной в директиве plugin_dir по соображениям безопасности: легче защитить одну папку, чем позволить кому угодно устанавливать произвольный код в searchd. Вы можете динамически загружать и выгружать UDF в searchd с помощью SQL-запросов CREATE FUNCTION и DROP FUNCTION соответственно. Дополнительно можно бесшовно перезагружать UDF (и другие плагины) с помощью команды RELOAD PLUGINS. Manticore отслеживает текущие загруженные функции; каждый раз, когда вы создаёте или удаляете UDF, searchd обновляет своё состояние в файле sphinxql_state в виде простого SQL-скрипта.

UDF являются локальными. Чтобы использовать их в кластере, вы должны разместить одинаковую библиотеку на всех узлах и выполнить CREATE-запросы на каждом узле. В будущих версиях этот процесс может измениться.

После успешной загрузки UDF, вы можете использовать её в своих запросах SELECT или других запросах так же, как и любую встроенную функцию:

SELECT id, MYCUSTOMFUNC (groupid, authorname), ... FROM myindex

Несколько UDF (и других плагинов) могут находиться в одной библиотеке. Библиотека загрузится только один раз и автоматически выгрузится, когда все UDF и плагины в ней будут удалены.

В теории, вы можете написать UDF на любом языке, если его компилятор может импортировать стандартные заголовки C и создавать стандартные динамические библиотеки с правильно экспортированными функциями. Однако писать на C++ или простом C — самый простой путь. Мы предоставляем пример библиотеки UDF, написанной на простом C, которая реализует несколько функций (демонстрируя различные техники) вместе с нашим исходным кодом, находящимся по адресу src/udfexample.c. В своём примере включён также заголовочный файл src/sphinxudf.h, который содержит определения нескольких структур и типов, связанных с UDF. Для большинства UDF и плагинов достаточно просто использовать #include "sphinxudf.h", как показано в примере. Однако если вы пишете функцию ранжирования и хотите получать данные сигналов ранжирования (факторов) внутри UDF, вам также нужно будет скомпилировать и связать с src/sphinxudf.c (доступным в нашем исходном коде), поскольку реализации функций, позволяющих получить доступ к данным сигналов из UDF, находятся в этом файле.

Заголовочный файл sphinxudf.h и sphinxudf.c являются автономными, так что вы можете скопировать эти файлы отдельно; они не зависят от других частей исходного кода Manticore.

Внутри вашей UDF вы должны реализовать и экспортировать только пару функций. Во-первых, для контроля версии интерфейса UDF вы должны определить функцию int LIBRARYNAME_ver(), где LIBRARYNAME — это имя вашего файла библиотеки, и она должна возвращать SPH_UDF_VERSION (значение, определённое в sphinxudf.h). Вот пример.

#include <sphinxudf.h>
// our library will be called udfexample.so, thus, so it must define
// a version function named udfexample_ver()
int udfexample_ver()
{
    return SPH_UDF_VERSION;
}

Эта предосторожность защищает вас от случайной загрузки библиотеки с несовпадающей версией интерфейса UDF в более новый или более старый searchd. Во-вторых, вы должны также реализовать саму функцию.

sphinx_int64_t testfunc ( SPH_UDF_INIT * init, SPH_UDF_ARGS * args, char * error_flag )
{
    return 123;
}

Имена функций UDF в SQL нечувствительны к регистру. Однако соответствующие C-функции должны быть в нижнем регистре, иначе UDF не загрузится. Более того, крайне важно, чтобы:

1. соглашение о вызове было C (aka __cdecl),
2. список аргументов точно соответствовал ожиданиям системы плагинов, и
3. возвращаемый тип совпадал с указанным в CREATE FUNCTION.

К сожалению, (легко) проверить эти ошибки при загрузке функции нельзя, и они могут привести к падению сервера и/или непредсказуемым результатам. И последнее, все реализованные вами функции на C должны быть потокобезопасными.

Первый аргумент — указатель на структуру SPH_UDF_INIT — фактически указатель на состояние нашей функции. Он опционален. В приведённом выше примере функция не хранит состояние, так как просто всегда возвращает 123. Поэтому мы не должны определять функцию инициализации, и можем просто игнорировать этот аргумент. Этот аргумент служит и ещё одной цели. Поскольку один и тот же запрос может выполняться в нескольких потоках (см. pseudo-sharding), демон пытается определить, является ли UDF сохраняющей состояние или нет, проверяя этот аргумент. Если этот аргумент инициализирован, параллельное выполнение будет отключено. Так что если ваша UDF сохраняет состояние, но не использует этот аргумент, она будет вызвана из нескольких потоков, и ваш код должен это учитывать.

Второй аргумент — указатель на SPH_UDF_ARGS — самый важный. Все фактические аргументы вызова передаются в вашу UDF через эту структуру; она содержит количество аргументов, имена, типы и так далее. Значит, будь вызов типа SELECT id, testfunc(1) или SELECT id, testfunc('abc', 1000*id+gid, WEIGHT()) или любой другой, UDF получит одинаковую структуру SPH_UDF_ARGS. Однако данные, переданные в args, будут различаться. В первом примере args->arg_count будет равно 1, во втором — 3, массив args->arg_types будет содержать типы разных аргументов и т. д.

Наконец, третий аргумент — это флаг ошибки. UDF может установить его, чтобы указать, что произошла внутренняя ошибка, UDF не может продолжать работу, и запрос должен завершиться преждевременно. Вы не должны использовать этот флаг для проверки типов аргументов или других ошибок, которые могут возникать при нормальном использовании. Этот флаг предназначен для сообщения о внезапных критических ошибках выполнения, например, исчерпании памяти.

Если бы мы хотели, например, выделить временное хранилище для использования функцией, или заранее проверить, поддерживаются ли типы аргументов, нам пришлось бы добавить ещё две функции — инициализации и деинициализации UDF соответственно.

int testfunc_init ( SPH_UDF_INIT * init, SPH_UDF_ARGS * args,
    char * error_message )
{
    // allocate and initialize a little bit of temporary storage
    init->func_data = malloc ( sizeof(int) );
    *(int*)init->func_data = 123;
    // return a success code
    return 0;
}
void testfunc_deinit ( SPH_UDF_INIT * init )
{
    // free up our temporary storage
    free ( init->func_data );
}

Обратите внимание, что testfunc_init() также получает структуру аргументов вызова. К моменту её вызова фактические значения ещё не переданы, поэтому args->arg_values будет равен NULL. Однако имена и типы аргументов уже известны и будут переданы. Вы можете проверить их в функции инициализации и вернуть ошибку, если они имеют неподдерживаемый тип.

UDF могут получать аргументы практически любого допустимого внутреннего типа Manticore. Полный список смотрите в перечислении sphinx_udf_argtype в файле sphinxudf.h. Большинство типов напрямую соответствуют соответствующим типам C.

Наиболее примечательным типом является тип аргумента SPH_UDF_TYPE_FACTORS. Вы получаете этот тип, вызывая вашу UDF с аргументом [PACKEDFACTOR()](../../Functions/Searching_and_ranking_functions#PACKEDFACTORS()). Его данные представляют собой бинарный блок в определённом внутреннем формате, и для извлечения отдельных сигналов ранжирования из этого блока вам необходимо использовать одну из двух семейств функций: sphinx_factors_XXX() или sphinx_get_YYY_factor().

Это семейство состоит из 3 функций.

• sphinx_factors_init() инициализирует распакованную структуру SPH_UDF_FACTORS
• sphinx_factors_unpack() распаковывает бинарный блок в структуру SPH_UDF_FACTORS
• sphinx_factors_deinit() очищает и освобождает память структуры SPH_UDF_FACTORS.

Сначала вам нужно вызвать init() и unpack(), затем вы можете использовать поля SPH_UDF_FACTORS, и, наконец, необходимо выполнить очистку с помощью deinit().

Этот подход прост, но может приводить к множеству выделений памяти для каждого обрабатываемого документа, что может быть медленным.

Другой интерфейс, состоящий из набора функций sphinx_get_YYY_factor(), использовать немного более многословно, но он обращается к данным блока напрямую и гарантирует отсутствие выделений памяти. Для максимальной производительности UDF ранжирования вам следует использовать этот подход.

Что касается возвращаемых типов, UDF в настоящее время могут возвращать единственное значение типа INTEGER, BIGINT, FLOAT или STRING. Соответствующий тип возвращаемого значения C-функции должен быть sphinx_int64_t, sphinx_int64_t, double или char*. В последнем случае вы обязаны использовать функцию args->fn_malloc для выделения памяти под возвращаемые строковые значения. Внутри вашей UDF вы можете использовать что угодно, поэтому пример testfunc_init() выше является корректным кодом, даже несмотря на прямое использование malloc(): вы управляете этим указателем самостоятельно, он освобождается с помощью соответствующего вызова free(), и всё в порядке. Однако возвращаемые строковые значения управляются Manticore, и у нас есть собственный аллокатор, поэтому именно для возвращаемых значений вам также необходимо использовать его.

В зависимости от того, как ваши UDF используются в запросе, основной вызов функции (testfunc() в нашем примере) может вызываться в разном объёме и порядке. А именно:

• UDF, упомянутые в предложениях WHERE, ORDER BY или GROUP BY, должны и будут вычисляться для каждого подходящего документа. Они будут вызываться в естественном порядке соответствия.
• без подзапросов, UDF, которые могут быть вычислены на самом последнем этапе над окончательным набором результатов, будут вычислены именно так, но до применения предложения LIMIT. Они будут вызываться в порядке набора результатов.
• с подзапросами, такие UDF также будут вычислены после применения внутреннего предложения LIMIT.

Однако последовательность вызова других функций фиксирована. А именно:

• testfunc_init() вызывается один раз при инициализации запроса. Она может вернуть ненулевой код для указания на ошибку; в этом случае запрос будет прерван, и будет возвращено сообщение об ошибке из буфера error_message.
• testfunc() вызывается для каждой подходящей строки (см. выше), когда Manticore нуждается в вычислении значения UDF. Она также может указать на (внутреннюю) ошибку, записав ненулевое байтовое значение в error_flag. В этом случае гарантируется, что функция не будет вызываться для последующих строк, и будет подставлено возвращаемое значение по умолчанию, равное 0. Manticore может как прервать такие запросы досрочно, так и не делать этого; ни одно из этих поведений в настоящее время не гарантируется.
• testfunc_deinit() вызывается один раз при завершении обработки запроса (в данном шарде таблицы).