SphinxSE 是一个 MySQL 存储引擎，可以通过 MySQL/MariaDB 服务器的可插拔架构进行编译。

尽管名字叫 SphinxSE，但它实际上并不存储任何数据。相反，它作为一个内置客户端，使 MySQL 服务器能够与 searchd 通信，执行搜索查询并检索搜索结果。所有的索引和搜索都在 MySQL 之外进行。

一些常见的 SphinxSE 应用包括：

• 简化将 MySQL 全文搜索（FTS）应用移植到 Manticore 的过程；
• 使 Manticore 能够与尚无原生 API 的编程语言一起使用；
• 当需要在 MySQL 端进行额外的 Manticore 结果集处理时提供优化（例如，与原始文档表的 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 目录，并将 Manticore 源代码中的 mysqlse 目录下的所有文件复制到该目录。例如：

   $ 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 目录，并将 Manticore 源代码中的 mysqlse 目录下的所有文件复制到该新位置。例如：

   $ 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';

在搜索表中，前三列 必须 具有以下类型：第 1 列（文档 ID）为 INTEGER UNSIGNED 或 BIGINT，第 2 列（匹配权重）为 INTEGER 或 BIGINT，第 3 列（您的查询）为 VARCHAR 或 TEXT。此映射是固定的；您不能省略这三列中的任何一列，不能更改它们的位置或类型。此外，查询列必须被索引，而其他列应保持未索引。列名被忽略，因此您可以使用任意名称。

附加列必须是 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";

您也可以在每个查询中覆盖这些参数。

如示例所示，查询文本和搜索选项都应放在搜索查询列（即第 3 列）的 WHERE 子句中。选项用分号分隔，名称和值用等号分隔。可以指定任意数量的选项。可用选项包括：

• 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 - 匹配的最小和最大文档 ID；
• 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 - 逗号分隔的（整数或 bigint）Manticore 属性名，以及要匹配的最小和最大值：

  # 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 - 每查询最大匹配数值，如 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 - 用于“扩展”匹配模式的排名函数，如同 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 处理排序、过滤和结果集切片要高效得多，而不是增加最大匹配数并在 MySQL 端使用 WHERE、ORDER BY 和 LIMIT 子句。这有两个原因。首先，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 引擎，您可以从 MySQL/MariaDB 连接到本地或远程的 Manticore 实例并执行搜索查询。

由于 FEDERATED 引擎的限制以及 Manticore 实现了自定义语法（如 MATCH 子句），实际的 Manticore 查询不能直接用于 FEDERATED 引擎，必须通过“代理”（作为列中的字符串发送）。

要通过 FEDERATED 进行搜索，首先需要创建一个 FEDERATED 引擎表。Manticore 查询将包含在对 FEDERATED 表执行的 SELECT 中的 query 列中。

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 列。它是必需的，并且必须是唯一附加表的列。

通过 FEDERATED 连接的 Manticore 表必须是物理表（普通表或实时表）。

FEDERATED 表应具有与远程 Manticore 表属性同名的列，因为它们将按名称绑定到 Manticore 结果集中提供的属性。然而，它可能只映射部分属性，而非全部。

Manticore 服务器通过用户名 "FEDERATED" 识别来自 FEDERATED 客户端的查询。CONNECTION 字符串参数用于指定 Manticore 主机、SQL 端口和通过连接进行查询的表。连接字符串语法如下：

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

由于 Manticore 没有数据库的概念，DB 字符串可以是任意的，因为 Manticore 会忽略它，但 MySQL 要求在 CONNECTION 字符串定义中必须有值。如示例所示，完整的 SELECT SQL 查询应放在针对 query 列的 WHERE 子句中。

仅支持 SELECT 语句，不支持 INSERT、REPLACE、UPDATE 或 DELETE。

一个非常重要的注意事项是，让 Manticore 执行排序、过滤和结果集切片要远远比增加最大匹配数并在 MySQL 端使用 WHERE、ORDER BY 和 LIMIT 子句更高效。原因有两个。首先，Manticore 实现了多种优化，执行这些任务的性能优于 MySQL。其次，搜索守护进程（searchd）需要打包、传输和解包的数据量更少。

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 可以通过用户自定义函数（简称 UDFs）进行扩展，方法如下：

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

您可以动态加载和卸载 UDFs 到 searchd，无需重启服务器，并在搜索、排序等表达式中使用它们。UDF 功能的简要总结如下：

• UDF 可以接受整数（32 位和 64 位）、浮点数、字符串、MVA 或 PACKEDFACTORS() 参数。
• UDF 可以返回整数、浮点数或字符串值。
• UDF 可以在查询设置阶段检查参数数量、类型和名称，并抛出错误。

我们尚不支持聚合函数。换句话说，您的 UDF 将一次仅针对单个文档调用，并期望返回该文档的某个值。编写能够计算整个共享相同 GROUP BY 键的文档组的聚合值（如 AVG()）的函数目前还不可行。不过，您可以在内置聚合函数中使用 UDF：即使 MYCUSTOMAVG() 目前不支持，AVG(MYCUSTOMFUNC()) 应该可以正常工作！

UDF 提供了广泛的应用场景，例如：

• 集成自定义数学或字符串函数；
• 从 Manticore 内部访问数据库或文件；
• 创建复杂的排序函数。

插件提供了扩展搜索功能的额外机会。目前它们可用于计算自定义排序和对文档及查询进行分词。

以下是插件类型的完整列表：

• UDF 插件（本质上是 UDF，但由于它们是插件，也称为“UDF 插件”）
• 排序器插件
• 索引时的分词过滤器插件
• 查询时的分词过滤器插件

本节涵盖编写和管理插件的一般流程；有关创建不同类型插件的具体内容，请参见各自的小节。

那么，如何编写和使用插件？以下是快速的四步指南：

• 创建动态库（.so 或 .dll），通常使用 C 或 C++；
• 使用 CREATE PLUGIN 将插件加载到 searchd；
• 通过插件特定调用（通常通过特定 OPTIONS）使用插件；
• 分别使用 DROP PLUGIN 和 RELOAD PLUGINS 卸载或重新加载插件。

请注意，虽然 UDF 是一等插件，但它们是通过单独的 CREATE FUNCTION 语句安装的。这允许对返回类型进行整洁的指定，同时不牺牲向后兼容性或更改语法。

动态插件支持线程和线程池工作者。多个插件（和/或 UDF）可以包含在单个库文件中。您可以选择将所有项目特定插件放入一个大型库，或为每个 UDF 和插件创建单独的库；这取决于您。

与 UDF 一样，您应包含 src/sphinxudf.h 头文件。至少，您需要 SPH_UDF_VERSION 常量来实现适当的版本函数。根据具体插件类型，您可能需要或不需要将插件与 src/sphinxudf.c 链接。然而，sphinxudf.c 中实现的所有函数都与解包 PACKEDFACTORS() blob 相关，而没有插件类型可以访问该数据。因此，目前仅链接头文件就足够了。（实际上，如果您复制 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)