大漠_FaiHo

Sphinx--强大的开源全文检索引擎，Coreseek--免费开源的中文全文检索引擎

1. 简介

1.1. 什么是Sphinx/Coreseek

Sphinx是一个在GPLv2下分发的全文检索引擎；Coreseek 是一个可供企业使用的、基于Sphinx（可独立于Sphinx原始版本运行）的中文全文检索引擎，按照GPLv2协议发行，商业使用（例如, 嵌入到其他程序中）需要联系我们以获得商业授权。

一般而言，Sphinx是一个独立的全文搜索引擎；而Coreseek是一个支持中文的全文搜索引擎，意图为其他应用提供高速、低空间占用、高结果相关度的中文全文搜索能力。Sphinx/Coreseek可以非常容易的与SQL数据库和脚本语言集成。

当前系统内置MySQL和PostgreSQL 数据库数据源的支持，也支持从管道标准输入读取入特定格式的XML数据。通过修改源代码，用户可以自行增加新的数据源（例如：其他类型的DBMS的原生支持）。在最新的版本中，用户还可以使用Python脚本作为数据源来获取任何已知世界和未知世界的数据，这极大的扩展了数据源的来源。

搜索API支持PHP、Python、Perl、Rudy和Java，并且也可以用作MySQL存储引擎。搜索API非常简单，可以在若干个小时之内移植到新的语言上。

Sphinx 是SQL Phrase Index的缩写，但不幸的和CMU的Sphinx项目重名。

Coreseek (http://www.coreseek.cn/) 为Sphinx在中国地区的用户提供支持服务，如果您不希望纠缠与琐碎的技术细节，请直接联系我们。

本参考手册基于Sphinx 0.9.9最新文档，可能存在潜在的翻译错误，如果您发现本文的翻译错误，请联系我们。

我们的联系方式： [email protected] 李沫南(nzinfo) [email protected] 乔楚(HonestQiao 13581882013)

1.2. Sphinx/Coreseek 的特性

高速的建立索引(在当代CPU上，峰值性能可达到10 MB/秒);
高性能的搜索(在2 – 4GB 的文本数据上，平均每次检索响应时间小于0.1秒);
可处理海量数据(目前已知可以处理超过100 GB的文本数据, 在单一CPU的系统上可处理100 M 文档);
提供了优秀的相关度算法，基于短语相似度和统计（BM25）的复合Ranking方法;
支持分布式搜索;
提供文档片段（摘要以及高亮）生成功能;
可作为MySQL的存储引擎提供搜索服务;
支持布尔、短语、词语相似度等多种检索模式;
文档支持多个全文检索字段(缺省配置下，最大不超过32个);
文档支持多个额外的属性信息(例如：分组信息，时间戳等);
停止词查询;
支持单一字节编码和UTF-8编码，以及对GBK和BIG5的完善支持;
支持英语、俄语词词干化和Soundex，以便进行词形学处理;
原生的MySQL支持(同时支持MyISAM 和InnoDB );
原生的PostgreSQL 支持;
支持直接模拟为MySQL服务端运行;
支持MMSeg分词引擎，用户可自定义词典;
Python数据源支持，得以获取任何已知世界和未知世界的数据.

1.3. 如何得到Sphinx/Coreseek

Sphinx原始版本可以从Sphinx官方网站 http://www.sphinxsearch.com/，Coreseek可以从Coreseek官方网站 http://www.coreseek.cn/下载.

目前，Sphinx/Coreseek的发布包包括如下软件:

indexer: 用于创建全文索引;
search: 一个简单的命令行(CLI) 的测试程序，用于测试全文索引;
searchd: 一个守护进程，其他软件可以通过这个守护进程进行全文检索;
sphinxapi: 一系列searchd 的客户端API 库，用于流行的Web脚本开发语言(PHP, Python, Perl, Ruby, Java).
spelldump: 一个简单的命令行工具，用于从 ispell 或 MySpell (OpenOffice内置绑定) 格式的字典中提取词条。当使用 wordforms 时可用这些词条对索引进行定制.
indextool: 工具程序，用来转储关于索引的多项调试信息。此工具是从版本Coreseek 3.1(Sphinx 0.9.9-rc2)开始加入的。
mmseg: 工具程序和库，Coreseek用于提供中文分词和词典处理。

1.4. 许可协议

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. See COPYING file for details.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

If you don't want to be bound by GNU GPL terms (for instance, if you would like to embed Sphinx in your software, but would not like to disclose its source code), please contactthe author to obtain a commercial license.

1.5. 作者和贡献者

作者

Coreseek 主要开发人员:

nzinfo, <li.monan(at)gmail.com>, HonestQiao, <honestqiao(at)gmail.com>

Sphinx 的最初作者和目前的主要开发人员:

Andrew Aksyonoff, <shodan(at)shodan.ru>

贡献者

为Sphinx的开发出过力的人员和他们的贡献如下（以下排名不分先后）:

Robert "coredev" Bengtsson (Sweden), initial version of PostgreSQL data source;
Len Kranendonk, Perl API
Dmytro Shteflyuk, Ruby API

此外，还有许多人提出了宝贵的想法、错误报告以及修正。在此一并致谢！对Sphinx/Coreseek所采用依赖和工具软件的作者，在此也表示由衷的感谢与敬意。

1.6. 历史

Coreseek 的开发工作类似Sphinx（起始于2001年），可以上溯到2006年，当时我们试图为一个数据库驱动的网站寻找一个可接受的中文搜索的解决方案，但是当时没有任何方案能够完全而又直接的满足要求。事实上，主要是如下问题：

搜索质量(例如：类似Google的有效的相关度算法)

单纯的统计学方法的效果非常糟糕，特别是在大量的短篇文档的集合上，例如：论坛、博客等等

搜索速度

特别是当搜索的短语包括“停止词”时，表现的尤其明显，例如："to be or not to be"

建立索引时，可控的磁盘和CPU消耗

在现有硬件的环境下，这一点的重要性要超过对索引构造速度的要求.

中文搜索的准确性和效率

因为众所周知的原因，只有准确的中文分词才能提高中文搜索的准确性，并大大降低计算量.

通过网络，我们了解到有无数的人存在类似的需求，尔后我们进行了不同途径的探索，尝试了不同的走法，经过了反复的实践，最终选择基于Sphinx、结合MMSeg，开发出Coreseek中文全文检索引擎，并按照GPLv2协议发行，以供企业和个人解决中文搜索问题。

年复一年，其他的解决方案有了很多改进，新的方案也不断涌现，但是，我们一致认为仍然没有一种解决方案足够的好，能让我们抛弃Sphinx将搜索平台迁移过去。

近年来，Sphinx/Coreseek的用户给了我们很多正面的反馈和建议，我们也不断改进和提高，并增加了Python数据源，将Sphinx /Coreseek的应用范围从已知世界扩展到未知世界，其应用场景也达到无限种可能；因此，显而易见的，Sphinx/Coreseek的开发过程将会继续（也许将持续到世界末日）。

2. 安装

2.1. 支持的操作系统

在绝大多数现代的Unix类操作系统（例如Linux、BSD等）上，只需要一个C++编译器就可以编译并运行Sphinx/Coreseek，而不需要对源码进行任何改动。

目前，Sphinx/Coreseek可以在以下系统上运行：

Linux 2.4.x, 2.6.x (包括各种发行版，如Redhat、Centos、Debian、OpenSuse等)
Windows 2000, 2003, XP, Vista, Windows7, Windows2008
FreeBSD 4.x, 5.x, 6.x, 7.x, 8.x
NetBSD 1.6, 3.0, 4.x, 5.x
Solaris 9, 11
Mac OS X

支持的CPU种类包括 X86, X86-64, AMD64, SPARC64。目前经过实际测试可以在主流BSD平台、Linux平台和Windows平台运行，详情可以查看Coreseek测试运行环境列表。

我们希望Sphinx/Coreseek也能够在其他的类Unix操作系统平台上工作，为所有需要解决中文搜索问题的用户服务，如果你运行Sphinx/Coreseek索使用的操作系统不在上面的名单中，请告诉我们（HonestQiao, <honestqiao(at)gmail.com>）。

目前的阶段，Sphinx/Coreseek的Windows版可用于测试、调试和普通生产环境，但不建议用于负载量较大的生产系统。限于Windows 操作系统自身的限制，最突出的两个问题是：1）并发查询的支持不好；2）缺少索引数据热切换的支持。虽然目前已经有用户成功的在生产环境克服了这两个问题，但是我们仍然不推荐在Windows下运行Sphinx/Coreseek提供高强度的搜索服务。我们推荐使用Linux或者BSD作为运行的操作系统平台，并可提供Linux、BSD系统下针对性的系统架构和性能优化支持服务。

2.2. 需要的工具

在类UNIX操作系统平台上，你需要以下的工具用来编译和安装Sphinx/Coreseek:

C++编译器。GNU gcc 就能够干这个活.
make程序。GNU make 就能够干这个活.
iconv库。GNU libiconv 就能够提供支持.
Python2.6。Python数据源需要Python2.6的支持.

在 Windows平台上，你需要Microsoft Visual C/C++ Studio .NET 2003 or 2005。如果你还需要使用Python数据源，推荐安装ActiveState Python2.6。其他的编译器/开发环境也许也能搞定这件事，但你可能需要自己手工制作他们所需的Makefile或者工程文件。

2.3. 在Linux、BSD上安装Sphinx/Coreseek

将你下载的tar包解压，并进入coreseek 子目录:

$ tar xzvf coreseek-3.2.14.tar.gz $ cd coreseek
首先安装MMSeg:

$ cd mmseg

$ ./configure --prefix=/usr/local/mmseg
$ make
$ make install
$ cd ..
运行配置程序:

$ ./configure

configure程序有很多运行选项。完整的列表可以通过使用 --help 开关得到。最重要的如下：

--prefix, 定义将Coreseek安装到何处;比如 --prefix=/usr/local/coreseek (以下全部示例都假定Coreseek安装在这个位置)
--with-mysql, 当自动检测失败时，指出在那里能找到MySQL 头文件和库文件;
--with-pgsql, 指出在那里能找到PostgreSQL头文件和库文件.
--with-mmseg, 启用基于MMSeg的中文分词法，并指出在那里能找到MMSeg头文件和库文件.
--with-python, 启用Python数据源支持. 需要预先安装Python2.6.

编译源代码生成二进制程序:

$ make
安装二进制程序到你设定的目录下: (类Unix操作系统下默认为 /usr/local/bin/ , 但是可以被 configure --prefix) 修改安装目录

$ make install

2.4. 在Windows上安装Sphinx/Coreseek

在Windows上安装通常比在Linux环境下容易一些。要不是为了给代码制作patch，一般安装预先编译好的二进制文件即可，它们可以在网站的下载区找到.

将你下载的.zip文件解压，比如 coreseek-3.2.14-win32.zip (或者 coreseek-3.2.13-win32-pgsql.zip 如果你需要PostgresSQL支持.) Windows XP及其后续版本都可以直接解压.zip压缩包，用免费的解压缩程序也可，比如 7Zip.
在本教程的其余部分，我们假定上述压缩包被解压到 C:\usr\local\coreseek, 这样 searchd.exe 对应的路径就是 C:\usr\local\coreseek\bin\searchd.exe. 如果你打算给安装目录或者配置文件用个不同的路径，请在相应的地方自行修改路径。
把 searchd 服务安装成一个Windows服务:
C:\usr\local\coreseek> C:\usr\local\coreseek\bin\searchd.exe --install --config C:\usr\local\coreseek\etc\coreseek.conf --servicename Coreseek
这样 searchd 服务应该出现在“控制面板->系统管理->服务”的列表中了. 服务应该出现在“控制面板->系统管理->服务”的列表中了，但还没有被启动，因为在启动它之前，我们还需要做些配置并用indexer建立索引 . 这些可以参考快速入门教程.

2.5. 已知的安装问题和解决办法

如果 configure 程序没有找到MySQL 的头文件和库文件, 请试试检查是否安装了 mysql-devel 或者 mysql-client 依赖包. 在有些系统上，默认安装包括这个包. 类似如此，libiconv等也可能会有类似的提示。

如果 make 程序给出如下错误提示

/bin/sh: g++: command not found
make[1]: *** [libsphinx_a-sphinx.o] Error 127

请检查是否安装了 gcc-c++ 包.

如果你在编译时得到如下错误

sphinx.cpp:67: error: invalid application of `sizeof' to
    incomplete type `Private::SizeError<false>'

这意味着某些编译时的类型检查失败了，一个最有可能的原因是在你的系统上类型off_t的长度小于64bit。一个快速的修复手段是，你可以修改 src/sphinx.h ，将在定义类型SphOffset_t 处，将off_t 替换成DWORD，需要注意，这种改动将使你的全文索引文件不能超过2GB。即便这种修改有用，也请汇报这一问题，在汇报中请包括具体的错误信息以及操作系统编译器的配置情况。这样，我们可能能够在下一个版本中解决这一问题。

如何你遇到了其他的任何问题，或者前面的建议对你没有帮助，别犹豫，请立刻联系我们.

2.6. Sphinx/Coreseek快速入门教程

以下所有的例子都假设你将Sphinx/Coreseek安装在目录 /usr/local/coreseek, 并且 searchd 对应的路径为 /usr/local/coreseek/bin/searchd.

为了使用Sphinx/Coreseek，你需要:

创建配置文件.
缺省的配置文件名为 csft.conf. 全部的Sphinx/Coreseek提供的程序默认都在当前工作的目录下寻找该文件.
由configure 程序生成的示例配置文件sphinx.conf.dist 中包括全部选项的注释，复制并编辑这个文件使之适用于你的具体情况： (请确认 Sphinx/Coreseek 安装在 /usr/local/coreseek/)

$ cd /usr/local/coreseek/etc $ cp sphinx.conf.dist csft.conf $ vi csft.conf

在示例配置文件中，将试图对MySQL数据库test中的 documents 表建立索引；因此在这里还提供了 example.sql 用于给测试表增加少量数据用于测试:

$ mysql -u test < /usr/local/coreseek/etc/example.sql
运行indexer 为你的数据创建全文索引:

$ cd /usr/local/coreseek/etc $ /usr/local/coreseek/bin/indexer --all
检索你新创建的索引!

你可以使用search（注意，是search而不是searchd）实用程序从命令行对索引进行检索:

$ cd /usr/local/coreseek/etc $ /usr/local/coreseek/bin/search test

如果要从PHP脚本检索索引，你需要:

运行守护进程searchd，PHP脚本需要连接到searchd上进行检索:

$ cd /usr/local/coreseek/etc $ /usr/local/coreseek/bin/searchd
运行PHP API 附带的test 脚本（运行之前请确认searchd守护进程已启动）:

$ cd /源代码目录/coreseek/api $ php test.php test
将API文件(位于api/sphinxapi.php) 包含进你自己的脚本，开始编程.

祝你搜索愉快!

3. 建立索引

3.1. 数据源

索引的数据可以来自各种各样不同的来源：SQL数据库、纯文本、HTML文件、邮件等等。从Sphinx/Coreseek的视角看，索引数据是一个结构化的文档的集合，其中每个文档是字段的集合，这和SQL数据库的视角有所不同，在那里，每一行代表一个文档，每一列代表一个字段。

由于数据来源的不同，需要不同的代码来获取数据、处理数据以供Sphinx/Coreseek进行索引的建立。这种代码被称之为数据源驱动程序（简称：驱动或数据源）。

在本文撰写时，Sphinx/Coreseek中包括MySQL和PostgreSQL数据源的驱动程序，这些驱动使用数据库系统提供的C/C++原生接口连接到数据库服务器并获取数据。此外，Sphinx/Coreseek还提供了额外的被称为xmlpipe的数据源驱动，该驱动运行某个具体的命令，并从该命令的stdout中读入数据。数据的格式在 Section 3.8, “xmlpipe 数据源” 中有介绍。经过发展，Coreseek还提供了具有特色的Python数据源驱动，可以使用Python编写数据获取脚本自定义数据源，从而得以获取任何已知世界和未知世界的数据。

如果确有必要，一个索引的数据可以来自多个数据源。这些数据将严格按照配置文件中定义的顺序进行处理。所有从这些数据源获取到的文档将被合并，共同产生一个索引，如同他们来源于同一个数据源一样。

3.2. 属性

属性是附加在每个文档上的额外的信息（值），可以在搜索的时候用于过滤和排序。

搜索结果通常不仅仅是进行文档的匹配和相关度的排序，经常还需要根据其他与文档相关联的值，对结果进行额外的处理。例如，用户可能需要对新闻检索结果依次按日期和相关度排序，检索特定价格范围内的产品，检索某些特定用户的blog日志，或者将检索结果按月分组。为了高效地完成上述工作，Sphinx允许给文档附加一些额外的属性，并把这些值存储在全文索引中，以便在对全文匹配结果进行过滤、排序或分组时使用。

属性与字段不同，不会被全文索引。他们仅仅是被存储在索引中，属性进行全文检索式不可能的。如果要对属性进行全文检索，系统将会返回一个错误。

例如，如果column被设置为属性，就不能使用扩展表达式@column 1去匹配column为1的文档；如果数字字段按照普通的方式被索引，那么就可以这样来匹配。

属性可用于过滤，或者限制返回的数据，以及排序或者结果分组; 也有可能是完全基于属性排序的结果, 而没有任何搜索相关功能的参与. 此外, 属性直接从搜索服务程序返回信息, 而被索引的文本内容则没有返回.

论坛帖子表是一个很好的例子。假设只有帖子的标题和内容这两个字段需要全文检索，但是有时检索结果需要被限制在某个特定的作者的帖子或者属于某个子论坛的帖子中（也就是说，只检索在SQL表的author_id和forum_id这两个列上有特定值的那些行），或者需要按post_date列对匹配的结果排序，或者根据post_date列对帖子按月份分组，并对每组中的帖子计数。

为实现这些功能，可以将上述各列（除了标题和内容列）作为属性做索引，之后即可使用API调用来设置过滤、排序和分组。以下是一个例子：

示例： sphinx.conf 片段:

...
sql_query = SELECT id, title, content, \
	author_id, forum_id, post_date FROM my_forum_posts
sql_attr_uint = author_id
sql_attr_uint = forum_id
sql_attr_timestamp = post_date
...

示例：应用程序代码 (PHP):

// only search posts by author whose ID is 123
$cl->SetFilter ( "author_id", array ( 123 ) );

// only search posts in sub-forums 1, 3 and 7
$cl->SetFilter ( "forum_id", array ( 1,3,7 ) );

// sort found posts by posting date in descending order
$cl->SetSortMode ( SPH_SORT_ATTR_DESC, "post_date" );

可以通过名字来指示特定的属性，并且这个名字是大小写无关的（注意：直到目前为止，Sphinx还不支持中文作为属性的名称）。属性并不会被全文索引，他们只是按原封不动的存储在索引文件中。目前支持的属性类型如下：

无符号整数（1-32位宽）;
UNIX 时间戳（timestamps）;
浮点值（32位，IEEE 754单精度）;
字符串序列 (尤其是计算出的整数值);
多值属性 MVA( multi-value attributes ) (32位无符号整型值的变长序列).

由各个文档的全部的属性信息构成了一个集合，它也被称为文档信息 docinfo. 文档信息可以按如下两种方式之一存储：

 与全文索引数据分开存储（“外部存储”，在.spa文件中存储）, 或者
 在全文索引数据中，每出现一次文档ID 就出现相应的文档信息（“内联存储”，在.spd文件中存储）

当采用外部存储方式时，searchd总是在RAM中保持一份.spa文件的拷贝（该文件包含所有文档的所有文档信息）。这是主要是为了提高性能，因为磁盘的随机访问太慢了。相反，内联存储并不需要任何额外的RAM，但代价是索引文件的体积大大地增加了；请注意，全部属性值在文档ID出现的每一处都被复制了一份，而文档ID出现的次数恰是文档中不同关键字的数目。仅当有一个很小的属性集、庞大的文本数据集和受限的RAM时，内联存储才是一个可考虑的选择。在大多数情况下，外部存储可令建立索引和检索的效率都大幅提高。

检索时，采用外部存储方式产生的的内存需求为 (1+number_of_attrs)*number_of_docs*4字节，也就是说，带有两个属性和一个时间戳的1千万篇文档会消耗(1+2+1)*10M*4 = 160 MB的RAM。这是每个检索的守护进程（PER DAEMON）消耗的量，而不是每次查询，searchd仅在启动时分配160MB的内存，读入数据并在不同的查询之间保持这些数据。子进程并不会对这些数据做额外的拷贝。

3.3. MVA (多值属性)

多值属性MVA (multi-valued attributes)是文档属性的一种重要的特例，MVA使得向文档附加一系列的值作为属性的想法成为可能。这对文章的tags，产品类别等等非常有用。MVA属性支持过滤和分组（但不支持分组排序）。

目前MVA列表项的值被限制为32位无符号整数。列表的长度不受限制，只要有足够的RAM，任意个数的值都可以被附加到文档上（包含MVA值的.spm文件会被searchd预缓冲到RAM中）。MVA的源数据来源既可以是一个单独的查询，也可以是文档属性，参考 sql_attr_multi中的来源类型。在第一种情况中，该查询须返回文档ID和MVA值的序对；而在第二种情况中，该字段被分析为整型值。对于多值属性的输入数据的顺序没有任何限制，在索引过程中这些值会自动按文档ID分组（而相同文档ID下的数据也会排序）。

在过滤过程中，MVA属性中的任何一个值满足过滤条件，则文档与过滤条件匹配（因此通过排他性过滤的文档不会包含任何被禁止的值）。按MVA属性分组时，一篇文档会被分到与多个不同MVA值对应的多个组。例如，如果文档集只包含一篇文档，它有一个叫做tag的MVA属性，该属性的值是5、7和11，那么按tag的分组操作会产生三个组，它们的@count都是 1，@groupby键值分别是5、7和11。还要注意，按MVA分组可能会导致结果集中有重复的文档：因为每篇文文档可能属于不同的组，而且它可能在多个组中被选为最佳结果，这会导致重复的ID。由于历史原因，PHP API对结果集的行进行按文档ID的有序hash，因此用PHP API进行对MVA属性的分组操作时你还需要使用 SetArrayResult().

3.4. 索引

为了快速地相应响应查询，Sphinx需要从文本数据中建立一种为查询做优化的特殊的数据结构。这种数据结构被称为索引（index）；而建立索引的过程也叫做索引或建立索引（indexing）。

不同的索引类型是为不同的任务设计的。比如，基于磁盘的B-Tree存储结构的索引可以更新起来比较简单（容易向已有的索引插入新的文档），但是搜起来就相当慢。因此Sphinx的程序架构允许轻松实现多种不同的索引类型。

目前在Sphinx中实现的唯一一种索引类型是为最优化建立索引和检索的速度而设计的。随之而来的代价是更新索引相当的很慢。理论上讲，更新这种索引甚至可能比从头重建索引还要慢。不过大多数情况下这可以靠建立多个索引来解决索引更新慢的问题，细节请参考 Section 3.11, “实时索引更新”.

实现更多的索引类型支持，已列入计划，其中包括一种可以实时更新的类型。

每个配置文件都可以按需配置足够多的索引。indexer 工具可以将它们同时重新索引（如果使用了--all选项）或者仅更新明确指出的一个。 searchd工具会为所有被指明的索引提供检索服务，而客户端可以在运行时指定使用那些索引进行检索。

3.5. 源数据的限制

Sphinx/Coreseek索引的源数据有一些限制，其中最重要的一条是:

所有文档的ID必须是唯一的无符号非零整数（根据Sphinx构造时的选项，可能是32位或64位）

如果不满足这个要求，各种糟糕的情况都可能发生。例如，Sphinx/Coreseek建立索引时可能在突然崩溃，或者由于冲突的文档ID而在索引结果中产生奇怪的结果。也可能，一只重达1000磅的大猩猩最后跳出你的电脑，向你扔臭蛋。我告诉过你咯！

3.6. 字符集、大小写转换和转换表

当建立索引时，Sphinx从指定的数据源获得文本文档，将文本分成词的集合，再对每个词做大小写转换，于是“Abc”，“ABC”和“abc”都被当作同一个词（word，或者更学究一点，词项term）

为了正确完成上述工作，Sphinx需要知道：

源文本是什么编码的;
那些字符是字母，哪些不是;
哪些字符需要被转换，以及被转换成什么.

这些都可以用charset_type 和 charset_table 选项为每个索引单独配置.charset_type指定文档的编码是单字节的（SBCS）还是UTF-8的。在Coreseek中，如果通过charset_dictpath设置中文词典启动了中文分词模式后，则可以使用GBK及BIG5的编码；但是在内部实现中，任然是预先转换成UTF-8编码在进行处理的.charset_table则指定了字母类字符到它们的大小写转换版本的对应表，没有在这张表中出现的字符被认为是非字母类字符，并且在建立索引和检索时被当作词的分割符来看待。

注意，尽管默认的转换表并不包含空格符 (ASCII code 0x20, Unicode U+0020) , 但是这么做是完全合法的. 这在某些情况下可能有用，比如在对tag云构造索引的时候，这样一个用空格分开的词集就可以被当作一个单独的查询项了.

默认转换表目前包括英文和俄文字符。请您提交您为其他语言撰写的转换表！

在Coreseek中，启用中文分词后，系统会使用MMSeg内置的码表（被硬编码在MMSeg的程序中），因此，charset_table在启用分词后将失效。

3.7. SQL 数据源 (MySQL, PostgreSQL)

对于所有的基于SQL驱动，建立索引的过程如下：

连接到数据库;
执行预查询 (参见 Section 9.1.11, “sql_query_pre”) ，以便完成所有必须的初始设置，比如为MySQL连接设置编码;
执行主查询 (参见 Section 9.1.12, “sql_query”) ，其返回的的数据将被索引;
执行后查询 (see Section 9.1.23, “sql_query_post”) ，以便完成所有必须的清理工作;
关闭到数据库的连接;
对短语进行排序 (或者学究一点, 索引类型相关的后处理);
再次建立到数据库的连接;
执行后索引查询 (参见 Section 9.1.24, “sql_query_post_index”) i，以便完成所有最终的清理善后工作;
再次关闭到数据库的连接.

大多数参数是很直观的，例如数据库的用户名、主机、密码。不过，还有一些细节上的问题需要讨论。

区段查询

索引系统需要通过主查询来获取全部的文档信息，一种简单的实现是将整个表的数据读入内存，但是这可能导致整个表被锁定并使得其他操作被阻止（例如：在MyISAM格式上的INSERT操作），同时，将浪费大量内存用于存储查询结果，诸如此类的问题吧。为了避免出现这种情况，Sphinx/Coreseek支持一种被称为 区段查询的技术. 首先，Sphinx/Coreseek从数据库中取出文档ID的最小值和最大值，将由最大值和最小值定义自然数区间分成若干份，一次获取数据，建立索引。现举例如下：

Example 1. 区段查询示例：

# in sphinx.conf

sql_query_range	= SELECT MIN(id),MAX(id) FROM documents
sql_range_step = 1000
sql_query = SELECT * FROM documents WHERE id>=$start AND id<=$end

如果这个表（documents）中，字段ID的最小值和最大值分别是1 和2345，则sql_query将执行3次：

将 $start 替换为1，并且将 $end 替换为 1000;
将 $start 替换为1001，并且将 $end 替换为 2000;
将 $start 替换为2001，并且将 $end 替换为 2345.

显然，这对于只有2000行的表，分区查询与整个读入没有太大区别，但是当表的规模扩大到千万级（特别是对于MyISAM格式的表），分区区段查询将提供一些帮助。

`后查询（sql_post）` vs. `索引后查询（sql_post_index）`

后查询和索引后查询的区别在于，当Sphinx获取到全部文档数据后，立即执行后查询，但是构建索引的过程仍然may因为某种原因失败。在另一方面，当索引后查询被执行时，可以理所当然的认为索引已经成功构造完了。因为构造索引可能是个漫长的过程，因此对与数据库的连接在执行后索引操作后被关闭，在执行索引后操作前被再次打开。

3.8. xmlpipe 数据源

xmlpipe 数据源是处于让用户能够将现有数据嵌入Sphinx而无需开发新的数据源驱动的目的被设计和提供的。它将每篇文档限制为只能包括两个可全文索引的字段，以及只能包括两个属性。xmlpipe数据源已经被废弃，在Section 3.9, “xmlpipe2 数据源”中描述了xmlpipe的替代品xmlpipe2数据源。对于新的数据，建议采用xmlpipe2。

为了使用xmlpipe，需要将配置文件改为类似如下的样子：

source example_xmlpipe_source
{
    type = xmlpipe
    xmlpipe_command = perl /www/mysite.com/bin/sphinxpipe.pl
}

indexer 实用程序将要运行 xmlpipe_command, 所指定的命令，而后读取其向标准输出stdout上输出的数据，并对之进行解析并建立索引。严格的说，是索引系统打开了一个与指定命令相连的管道，并从这个管道读取数据。

indexer 实用程序假定在从标准输入读入的XML格式的数据中中存在一个或更多的文档。下面是一个包括两个文档的文档数据流的例子：

Example 2. XMLpipe 文档数据流

<document>
<id>123</id>
<group>45</group>
<timestamp>1132223498</timestamp>
<title>test title</title>
<body>
this is my document body
</body>
</document>

<document>
<id>124</id>
<group>46</group>
<timestamp>1132223498</timestamp>
<title>another test</title>
<body>
this is another document
</body>
</document>

遗留的xmlpipe数据驱动使用内置的解析器来解析xml文档，这个解析器的速度非常快，但是并没有提供对XML格式完整支持。这个解析器需要文档中必须包括全部的字段，并且严格按照例子中给出的格式给出，而且字段的出现顺序需要严格按照例子中给出的顺序。仅有一个字段timestamp是可选的，它的缺省值为1。

3.9. xmlpipe2 数据源

xmlpipe2使你可以用另一种自定义的XML格式向Sphinx传输任意文本数据和属性数据。数据模式（即数据字段的集合或者属性集）可以由XML流本身指定，也可以在配置文件中数据源的配置部分中指定。

在对xmlpipe2数据源做索引时，索引器运行指定的命令，打开一个连接到前述命令标准输出的管道，并等待接受具有正确格式的XML数据流。以下是一个数据流的样本：

Example 3. xmlpipe2 文档流

<?xml version="1.0" encoding="utf-8"?>
<sphinx:docset>

<sphinx:schema>
<sphinx:field name="subject"/> 
<sphinx:field name="content"/>
<sphinx:attr name="published" type="timestamp"/>
<sphinx:attr name="author_id" type="int" bits="16" default="1"/>
</sphinx:schema>

<sphinx:document id="1234">
<content>this is the main content <![CDATA[[and this <cdata> entry
must be handled properly by xml parser lib]]></content>
<published>1012325463</published>
<subject>note how field/attr tags can be
in <b class="red">randomized</b> order</subject>
<misc>some undeclared element</misc>
</sphinx:document>

<!-- ... more documents here ... -->

</sphinx:docset>

任意多的数据字段和属性都是允许的。数据字段和属性在同一文档元素中出现的先后顺序没有特别要求。。单一字段数据的最大长度有限制，超过2MB的数据会被截短到2MB（但这个限制可以在配置文件中数据源部分中修改）。

XML数据模式（Schema），即数据字段和属性的完整列表，必须在任何文档被分析之前就确定。这既可以在配置文件中用xmlpipe_field和xmlpipe_attr_XXX选项指定，也可以就在数据流中用<sphinx:schema>元素指定。 <sphinx:schema>元素是可选的，但如果出现，就必须是<sphinx:docset>元素的第一个子元素。如果没有在数据流中内嵌的数据模式定义，配置文件中的相关设置就会生效，否则数据流内嵌的设置被优先采用。

未知类型的标签（既不是数据字段，也不是属性的标签）会被忽略，但会给出警告。在上面的例子中，<misc>标签会被忽略。所有嵌入在其他标签中的标签及其属性都会被无视（例如上述例子中嵌入在<subject>标签中的<b>标签）

支持输入数据流的何种字符编码取决于系统中是否安装了iconv. xmlpipe2是用 libexpat解析器解析的，该解析器内置对 US-ASCII, UTF-8, UTF-8 和一些 UTF-16 变体的支持. Sphinx/Coreseek的 configure 脚本也会检查 libiconv 是否存在并使用它来处理其他的字符编码。 libexpat 也隐含的要求在Sphinx/Coreseek端使用UTF-8，因为它返回的分析过的数据总是UTF-8的。

xmlpipe2可以识别的XML元素（标签）（以及前述元素可用的属性）如下：

sphinx:docset
顶级元素，用于标明并包括xmlpipe2文档.
sphinx:schema
可选元素，它要么是sphinx:docset的第一个子元素，要么干脆不出现。声明文档的模式。包括数据字段和属性的声明。若此元素出现，则它会覆盖配置文件中对数据源的设定.
sphinx:field
可选元素，sphinx:schema的子元素。声明一个全文数据字段。唯一可识别的属性是“name”，它指定了字段的名称，后续数据文档中具有此名称的元素的数据都被当作待检索的全文数据对待.
sphinx:attr
O可选元素，sphinx:schema的子元素。用于声明具体属性。其已知的属性有:

"name"，设定该属性名称，后续文档中具有该名称的元素应被当作一个属性对待。.
"type"，设定该属性的类型。可能的类型包括 "int", "timestamp", "str2ordinal", "bool", "float" 和 "multi".
"bits"，设定“int”型属性的宽度，有效值为1到32.
"default"，设定该属性的默认值，若后续文档中没有指定这个属性，则使用此默认值。

sphinx:document
必须出现的元素，必须是sphinx:docset的子元素。包含任意多的其他元素，这些子元素带有待索引的数据字段和属性值，而这些数据字段或属性值既可以是用sphinx:field和sphinx:attr元素声明的，也可以在配置文件中声明。唯一的已知属性是“id”，它必须包含一个唯一的整型的文档ID。

3.10. Python 数据源

Coreseek支持使用Python编写数据源脚本，从而可以很方便的扩展Sphinx/Coreseek的功能，来轻易的从任何Python可以操作的地方获取需要进行检索的数据。当前，Python几乎支持所有的SQL数据库以及NoSql存储系统，可以查看Python DatabaseInterfaces获得详细列表。

python #用于配置Python数据源程序的PYTHONPATH
{
    path = /usr/local/coreseek/etc/pysource
    path = /usr/local/coreseek/etc/pysource/csft_demo
}

source sourcename
{
    type = python            #数据类型
    name = csft_demo.MainSource   #调用的python的类名称
}

在以上配置中，对应的Python数据源脚本，为/usr/local/coreseek/etc/pysource/csft_demo/__init__.py，执行索引操作时，将从该脚本获取数据，请查看Section 10.3, “Python数据源程序接口”了解细节。

3.11. 实时索引更新

有这么一种常见的情况：整个数据集非常大，以至于难于经常性的重建索引，但是每次新增的记录却相当地少。一个典型的例子是：一个论坛有1000000个已经归档的帖子，但每天只有1000个新帖子。

在这种情况下可以用所谓的“主索引＋增量索引”（main+delta）模式来实现“近实时”的索引更新。

这种方法的基本思路是设置两个数据源和两个索引，对很少更新或根本不更新的数据建立主索引，而对新增文档建立增量索引。在上述例子中，那1000000个已经归档的帖子放在主索引中，而每天新增的1000个帖子则放在增量索引中。增量索引更新的频率可以非常快，而文档可以在出现几分种内就可以被检索到。

确定具体某一文档的分属那个索引的分类工作可以自动完成。一个可选的方案是，建立一个计数表，记录将文档集分成两部分的那个文档ID，而每次重新构建主索引时，这个表都会被更新。

Example 4. 全自动的即时更新

# in MySQL
CREATE TABLE sph_counter
(
    counter_id INTEGER PRIMARY KEY NOT NULL,
    max_doc_id INTEGER NOT NULL
);

# in sphinx.conf
source main
{
    # ...
    sql_query_pre = SET NAMES utf8
    sql_query_pre = REPLACE INTO sph_counter SELECT 1, MAX(id) FROM documents
    sql_query = SELECT id, title, body FROM documents \
        WHERE id<=( SELECT max_doc_id FROM sph_counter WHERE counter_id=1 )
}

source delta : main
{
    sql_query_pre = SET NAMES utf8
    sql_query = SELECT id, title, body FROM documents \
        WHERE id>( SELECT max_doc_id FROM sph_counter WHERE counter_id=1 )
}

index main
{
    source = main
    path = /path/to/main
    # ... all the other settings
}

# note how all other settings are copied from main,
# but source and path are overridden (they MUST be)
index delta : main
{
    source = delta
    path = /path/to/delta
}

请注意，上例中我们显示设置了数据源delta的sql_query_pre选项，覆盖了全局设置。必须显示地覆盖这个选项，否则对delta做索引的时候也会运行那条REPLACE查询，那样会导致delta源中选出的数据为空。可是简单地将delta的sql_query_pre设置成空也不行，因为在继承来的数据源上第一次运行这个指令的时候，继承来的所有值都会被清空，这样编码设置的部分也会丢失。因此需要再次显式调用编码设置查询。

3.12. 索引合并

合并两个已有的索引比重新对所有数据做索引更有效率，而且有时候必须这样做（例如在“主索引＋增量索引”分区模式中应合并主索引和增量索引，而不是简单地重新索引“主索引对应的数据）。因此indexer有这个选项。合并索引一般比重新索引快，但在大型索引上仍然不是一蹴而就。基本上，待合并的两个索引都会被读入内存一次，而合并后的内容需要写入磁盘一次。例如，合并100GB和1GB的两个索引将导致202GB的IO操作（但很可能还是比重新索引少）

基本的命令语法如下：

indexer --merge DSTINDEX SRCINDEX [--rotate]

SRCINDEX的内容被合并到DSTINDEX中，因此只有DSTINDEX索引会被改变。若DSTINDEX已经被searchd于提供服务，则--rotate参数是必须的。最初设计的使用模式是，将小量的更新从SRCINDEX合并到DSTINDEX中。因此，当属性被合并时，一旦出现了重复的文档ID，SRCINDEX中的属性值更优先（会覆盖DSTINDEX中的值）。不过要注意，“旧的”关键字在这个过程中并不会被自动删除。例如，在DSTINDEX中有一个叫做“old”的关键字与文档123相关联，而在SRCINDEX中则有关键字“new”与同一个文档相关，那么在合并后用这两个关键字都能找到文档123。您可以给出一个显式条件来将文档从DSTINDEX中移除，以便应对这种情况，相关的开关是--merge-dst-range:

indexer --merge main delta --merge-dst-range deleted 0 0

这个开关允许您在合并过程中对目标索引实施过滤。过滤器可以有多个，只有满足全部过滤条件的文档才会在最终合并后的索引中出现。在上述例子中，过滤器只允许“deleted”为0的那些条件通过，而去除所有标记为已删除（“deleted”）的记录（可以通过调用UpdateAttributes()设置文档的属性）。

4. 搜索

4.1. 匹配模式

有如下可选的匹配模式：

SPH_MATCH_ALL, 匹配所有查询词(默认模式);
SPH_MATCH_ANY, 匹配查询词中的任意一个;
SPH_MATCH_PHRASE, 将整个查询看作一个词组，要求按顺序完整匹配;
SPH_MATCH_BOOLEAN, 将查询看作一个布尔表达式 (参见 Section 4.2, “布尔查询语法”);
SPH_MATCH_EXTENDED, 将查询看作一个Sphinx/Coreseek内部查询语言的表达式 (参见 Section 4.3, “扩展查询语法”). 从版本Coreseek 3/Sphinx 0.9.9开始, 这个选项被选项SPH_MATCH_EXTENDED2代替，它提供了更多功能和更佳的性能。保留这个选项是为了与遗留的旧代码兼容——这样即使 Sphinx及其组件包括API升级的时候，旧的应用程序代码还能够继续工作。
SPH_MATCH_EXTENDED2, 使用第二版的“扩展匹配模式”对查询进行匹配.
SPH_MATCH_FULLSCAN, 强制使用下文所述的“完整扫描”模式来对查询进行匹配。注意，在此模式下，所有的查询词都被忽略，尽管过滤器、过滤器范围以及分组仍然起作用，但任何文本匹配都不会发生.

当如下条件满足时，SPH_MATCH_FULLSCAN模式自动代替其他指定的模式被激活:

1. 查询串是空的（即长度字符串为零）
docinfo 存储方式为 extern.

在完整扫描模式中，全部已索引的文档都被看作是匹配的。这类匹配仍然会被过滤、排序或分组，但是并不会做任何真正的全文检索。这种模式可以用来统一全文检索和非全文检索的代码，或者减轻SQL服务器的负担（有些时候Sphinx扫描的速度要优于类似的MySQL查询）。 “在论坛中搜索帖子”这件事可用作完整搜索模式的例子：用SetFilter()指定用户ID但不提供任何查询词，Sphinx会匹配SetFilter()所能匹配的全部文档，也就是这个用户ID对应的全部帖子。默认情况下，其结果的第一排序标准是相关度，其次是Sphinx文档ID，正序（较老的文档在前）。

注意，在完整扫描模式中，文档必须有至少一个属性。否则，即便设置docinfo的存储方式为extern，也无法启用完整扫描模式。

4.2. 布尔查询语法

布尔查询允许使用下列特殊操作符:

显式的与（AND）操作符:
```
hello & world
```
或（OR）操作符:
```
hello | world
```
非（NOT）操作符:
```
hello -world
hello !world
```
分组（grouping）:
```
( hello world )
```

以下是一个使用了如上全部操作符的例子：

Example 5. 布尔查询示例

( cat -dog ) | ( cat -mouse)

与(AND)操作符为默认操作，所以“hello world”其实就是“hello & world”

或(OR)操作符的优先级高于与操作符，因此“lookingfor cat | dog | mouse”意思是"looking for ( cat | dog | mouse )" 而不是 "(looking for cat) | dog | mouse"

像“-dog”这种查询不能被执行，因为它差不多包括索引所有文档。这既有技术上的原因，也有性能上的原因。从技术上说，Sphinx并不总是保持一个全部文档ID的列表。性能方面，当文档集非常大的时候（即10-100M个文档），对这种执行查询可能需要很长的时间。

4.3. 扩展查询语法

在扩展查询模式中可以使用如下特殊操作符：

 或（OR）操作符:
```
hello | world
```
 非（NOT）操作符:
```
hello -world
hello !world
```
 字段（field）搜索符:
```
@title hello @body world
```
 字段限位修饰符（版本Coreseek 3/Sphinx 0.9.9-rc1中引入）:
```
@body[50] hello
```
 多字段搜索符:
```
@(title,body) hello world
```
 全字段搜索符:
```
@* hello
```
 词组搜索符:
```
"hello world"
```
 近似搜索符:
```
"hello world"~10
```
 阀值匹配符:
```
"the world is a wonderful place"/3
```
 严格有序搜索符（即“在前”搜索符）:
```
aaa << bbb << ccc
```
 严格形式修饰符（版本Coreseek 3/Sphinx 0.9.9-rc1中引入）:
```
raining =cats and =dogs
```
 字段开始和字段结束修饰符 (版本Coreseek 3.1/Sphinx 0.9.9-rc2中引入):
```
^hello world$
```

以下是上述某些操作符的示例：

Example 6. 扩展查询示例

"hello world" @title "example program"~5 @body python -(php|perl) @* code

例子中查询的完整解释如下：

• 在文档的任意字段中找相邻的“hello”和“world”
• 不仅如此，符合上述条件的文档的title字段中还必须包含 “example”和“program”这两个词，并且他们之间至多有10个（不包括10个）其他的词（例如“example PHP program”可以匹配，但“example script to introduce outside data into the correct context for your program”就不行，因为中间有10个或以上的词。
• 同时，body字段必须含有词“python”，但既没有“php”也没有“perl”
最后, 任一字段中包含”code“.

与(AND)操作为默认操作，因此“hello world”意思是“hello”和“world”必须同时存在文档才能匹配。

或（OR）操作符的优先级要高于与操作符，因此"looking for cat | dog | mouse" 意思是"looking for ( cat | dog | mouse )" 而不是"(looking for cat) | dog | mouse"；

字段限制(field limit)符(field limit)将其后指定的搜索限制在某个特定的字段中。通常，如果给出的字段名实际并不存在，你会得到一条错误信息。但可以通过在查询的最开始处加上@@relaxed选项来放宽限制。

@@relaxed @nosuchfield my query

当搜索多个具有不同schema的索引时这可能有用

版本Coreseek 3/Sphinx 0.9.9-rc1又引入了字段限位（field position limit）符。它把搜索限制在指定字段（一个或多个）的前N个位置。例如“@body[50] hello”不会匹配那些body字段包含“hello”，但它出现在第51个位置或者更靠后的文档。

近似距离以词为单位，随词数变化而变化，并应用于引号中的全部词。举个例子，"cat dog mouse"~5 这个查询的意思是必须有一个少于8个词的词串，它要包含全部的三个词，也就是说"CAT aaa bbb ccc DOG eee fff MOUSE" 这个文档不会匹配这个查询，因为这个词串正好是8个词。

阀值匹配符引入了一种模糊匹配。它允许至少含有某个阈值数量个匹配词的文档通过。上述例子（"the world is a wonderful place"/3）会匹配含有指定的六个词中的至少三个的那些文档。上面例子中的一个查询”the world is a wonderful place”/3匹配的文档至少含有指定的6个词中的3个。

严格有序搜索符（即“在前”搜索符）是在版本0.9.9-rc2中引入的，它的几个参数在被匹配的文档中必须严格按查询中出现的顺序出现。例如，“black << cat”这个查询（不包括引号）可以匹配“black and white cat”，但不能匹配“the cat was black”。顺序操作符的优先级最低，它既可以应用在最简单的关键词上，也可以用在更复杂的表达式上，比如下面也是个正确的查询：

(bag of words) << "exact phrase" << red|green|blue

版本0.9.9-rc1引入了“严格形式”关键字修饰符，它保证关键词在匹配文档中严格以指定的形式出现，而默认行为只要求词根相同。例如，查询“runs”既可以匹配含有“runs”的文档，也可以匹配含有“running”的文档，因为这二者的词根都是“run”——而如果查询是“=runs”，那就只有前者能匹配。严格形式修饰符要求index_exact_words选项处于启用状态。这是个影响关键字的修饰符，可以与其他一些操作符混合使用，例如词组搜索符、近似搜索符和阈值搜索符等。

关键字修饰符“字段开始”和“字段结束”是在版本Coreseek 3.1/Sphinx 0.9.9-rc2中引入的，它们确保只在一个全文字段的最开始或最结束位置匹配关键字。例如，查询“^hello world$”(包括引号，也就是说这个查询是词组搜索符和字段起止修饰符的组合)匹配的文档必然包括某个严格只有“hello world”这个词组的字段。

自版本Coreseek 3/Sphinx 0.9.9-rc1始，可以嵌套任意层数的括号和“非”操作，但这类查询要想能够计算出结果，就必须保证不能隐含地涉及所有文档。

// 正确查询
aaa -(bbb -(ccc ddd))

// 不能计算的查询
-aaa
aaa | -bbb

4.4. 权值计算

采用何种权值计算函数（目前）取决于查询的模式。

权值计算函数进行如下两部分主要部分：

词组评分,
统计学评分.

词组评分根据文档和查询的最长公共子串（LCS，longest common subsequence）的长度进行。因此如果文档对查询词组有一个精确匹配（即文档直接包含该词组），那么它的词组评分就取得了可能的最大值，也就是查询中词的个数。

统计学评分基于经典的BM25函数，该函数仅考虑词频。如果某词在整个数据库中很少见（即文档集上的低频词）或者在某个特定文档中被经常提及（即特定文档上的高频词），那么它就得到一个较高的权重。最终的BM25权值是一个0到1之间的浮点数。

在所有模式中，数据字段的词组评分是LCS乘以用户指定的数据字段权值。数据字段权值是整数，默认为1，且字段的权值必须不小于1。

在SPH_MATCH_BOOLEAN模式中，不做任何权重估计，每一个匹配项的权重都是1。

在SPH_MATCH_ALL和SPH_MATCH_PHRASE模式中，最终的权值是词组评分的加权和。

在SPH_MATCH_ANY模式中，于前面述两模式的基本思想类似，只是每个数据字段的权重都再加上一个匹配词数目。在那之前，带权的词组相关度被额外乘以一个足够大的数，以便确保任何一个有较大词组评分的数据字段都会使整个匹配的相关度较高，即使该数据字段的权重比较低。

在SPH_MATCH_EXTENDED模式中，最终的权值是带权的词组评分和BM25权重的和，再乘以1000并四舍五入到整数。

这个行为将来会被修改，以便使MATCH_ALL和MATCH_ANY这两个模式也能使用BM25算法。这将使词组评分相同的搜索结果片断得到改进，这在只有一个词的查询中尤其有用。

关键的思想（对于除布尔模式以外的全部模式中）是子词组的匹配越好则评分越高，精确匹配（匹配整个词组）评分最高。作者的经验是，这种基于词组相似性的评分方法可以提供比任何单纯的统计模型（比如其他搜索引擎中广泛使用的BM25）明显更高的搜索质量。

4.5. 排序模式

可使用如下模式对搜索结果排序：

SPH_SORT_RELEVANCE 模式, 按相关度降序排列（最好的匹配排在最前面）
SPH_SORT_ATTR_DESC 模式, 按属性降序排列（属性值越大的越是排在前面）
SPH_SORT_ATTR_ASC 模式, 按属性升序排列（属性值越小的越是排在前面）
SPH_SORT_TIME_SEGMENTS 模式, 先按时间段（最近一小时/天/周/月）降序，再按相关度降序
SPH_SORT_EXTENDED 模式, 按一种类似SQL的方式将列组合起来，升序或降序排列。
SPH_SORT_EXPR 模式，按某个算术表达式排序。

SPH_SORT_RELEVANCE忽略任何附加的参数，永远按相关度评分排序。所有其余的模式都要求额外的排序子句，子句的语法跟具体的模式有关。 SPH_SORT_ATTR_ASC, SPH_SORT_ATTR_DESC以及SPH_SORT_TIME_SEGMENTS这三个模式仅要求一个属性名。 SPH_SORT_RELEVANCE模式等价于在扩展模式中按"@weight DESC, @id ASC"排序，SPH_SORT_ATTR_ASC 模式等价于"attribute ASC, @weight DESC, @id ASC"，而SPH_SORT_ATTR_DESC 等价于"attribute DESC, @weight DESC, @id ASC"。

SPH_SORT_TIME_SEGMENTS 模式

在SPH_SORT_TIME_SEGMENTS模式中，属性值被分割成“时间段”，然后先按时间段排序，再按相关度排序。

时间段是根据搜索发生时的当前时间戳计算的，因此结果随时间而变化。所说的时间段有如下这些值：

最近一小时
最近一天
最近一周
最近一月
最近三月
其他.

时间段的分法固化在搜索程序中了，但如果需要，也可以比较容易地改变（需要修改源码）。

这种模式是为了方便对Blog日志和新闻提要等的搜索而增加的。使用这个模式时，处于更近时间段的记录会排在前面，但是在同一时间段中的记录又根据相关度排序－这不同于单纯按时间戳排序而不考虑相关度。

SPH_SORT_EXTENDED 模式

在 SPH_SORT_EXTENDED 模式中，您可以指定一个类似SQL的排序表达式，但涉及的属性（包括内部属性）不能超过5个，例如：

@relevance DESC, price ASC, @id DESC

只要做了相关设置，不管是内部属性（引擎动态计算出来的那些属性）还是用户定义的属性就都可以使用。内部属性的名字必须用特殊符号@开头，用户属性按原样使用就行了。在上面的例子里，@relevance和@id是内部属性，而price是用户定义属性。

已知的内置属性：

@id (匹配文档的 ID)
@weight (匹配权值)
@rank (等同 weight)
@relevance (等同 weight)
@random (随机顺序返回结果)

@rank 和 @relevance 只是 @weight 的别名.

SPH_SORT_EXPR 模式

表达式排序模式使您可以对匹配项按任何算术表达式排序，表达式中的项可以是属性值，内部属性（@id和@weight），算术运算符和一些内建的函数。例如：

$cl->SetSortMode ( SPH_SORT_EXPR,
	"@weight + ( user_karma + ln(pageviews) )*0.1" );

支持的运算符和函数如下。它们是模仿MySQL设计的。函数接受参数，参数的数目根据具体函数的不同而不同。

运算符: +, -, *, /, <, > <=, >=, =, <>.
布尔操作符: AND, OR, NOT.
无参函数: NOW().
一元函数（一个参数）: ABS(), CEIL(), FLOOR(), SIN(), COS(), LN(), LOG2(), LOG10(), EXP(), SQRT(), BIGINT().
二元函数（两个参数）: MIN(), MAX(), POW(), IDIV().
其他函数: IF(), INTERVAL(), IN(), GEODIST().

计算可以以三种不同的精度进行：(a) 单精度32位IEEE754浮点值（默认情况），(b) 32位有符号整数，(c) 64位有符号整数。如果没有任何返回浮点数的操作，表达式分析器会自动切换到整数模式，否则使用默认的浮点模式。比如，对于表达式“a+b”，如果两个参数都是32位整数的，则它会被以32位整数模式计算，如果两个参数都是整数，而其中一个是64位的，则以64位整数模式计算，否则以浮点模式计算。然而表达式“a/b”或者“sqrt(a)”却总是使用浮点模式计算，因为这些操作返回非整数的结果，要让前者使用整数模式，可以使用IDIV()。另外，如果两个参数都是32位的，表达式“a*b”并不会自动提升到64位模式。要想强制64位模式，可以用BIGINT()。（但要注意的是，如果表达式中同时有浮点数，那么BIGINT()的命运就是简单地被忽略）

比较操作符（比如=和<=）在条件为真时返回1.0，否则返回0.0。例如(a=b)+3在属性“a”与属性“b”相等时返回4，否则返回3。与MySQL不同，相等性比较符（即=和<>）中引入了一个小的阈值（默认是1e-6）。如果被比较的两个值的差异在阈值之内，则二者被认为相等。

布尔操作符（AND,OR,NOT）是在版本Coreseek 3.1/Sphinx 0.9.9-rc2中引入的，其行为与一般的布尔操作没有两样。它们全部是左结合，而且比之其他操作符，它们有最低的优先级，其中NOT的优先级比AND 和OR高，但仍旧低于所有其他操作符。AND和OR有相同的优先级，因此建议使用括号来避免在复杂的表达式中出现混乱。

全部的一元和二元函数的意义都很明确，他们的行为跟在数学中的定义一样。但IF()的行为需要点详细的解释。它接受3个参数，检查第一个参数是否为0.0，若非零则返回第二个参数，为零时则返回第三个参数。注意，与比较操作符不同，IF()并不使用阈值！因此在第一个参数中使用比较结果是安全的，但使用算术运算符则可能产生意料之外的结果。比如，下面两个调用会产生不同的结果，虽然在逻辑上他们是等价的：

IF ( sqrt(3)*sqrt(3)-3<>0, a, b )
IF ( sqrt(3)*sqrt(3)-3, a, b )

在第一种情况下，由于有阈值，比较操作符<>返回0.0（逻辑假），于是IF()总是返回‘b’。在第二种情况下，IF()函数亲自擅自在没有阈值的情况下将同样的 sqrt(3)*sqrt(3)-3与零值做比较。但由于浮点数运算的精度问题，该表达式的结果与0值会有微小的差异，因此该值与零值的相等比较不会通过，上述第二种情况中IF()会返回‘a’做为结果。

函数BIGINT()于版本Coreseek 3/ Sphinx 0.9.9-rc1引入，它将它的整型参数强行提升到64位，而对浮点参数无效。引入它是为了可以强制某些表达式（如“a*b”）用64位模式计算，即使所有的参数都是32位的。

IDIV() 函数用于两个参数的取整. 其结果为整数, 与 "a/b" 的结果不同.

版本Coreseek 3/ Sphinx 0.9.9-rc1引入了函数IN(expr, val1, val2, …)，它需要两个或更多参数，如果第一个参数与后续任何一个参数（val1到valN）相等则返回1，否则返回0。目前，所有被测试是否相等的参数（不包括expr本身）必须是常量。（支持任意表达式在技术上是可以实现的，未来我们会这么做）。这些常量经过预先排序，测试相等时可以使用二元查找以提高效率，因此即使参数列表很长IN()也还可以提供较高的速度。自版本0.9.9-rc2始，第一个参数可以是一个MVA多值属性，这种情况下只要MVA中的任何一个值与后面列表中的任何一个值相等IN()就返回1。

版本0.9.9-rc1引入了函数INTERVAL(expr, point1, point2, point3, …)，它接受2个或更多参数，返回第一个小于第一个参数expr的参数的下标：如果expr<point1，返回0；如果 point1<=expr<point2，返回1，一次类推。显然，必须有point1<point2<…<pointN 才能保证这个函数正确工作。

版本0.9.9-rc1引入了函数NOW()，这是个工具函数，将当前时间戳作为32位整数返回。

版本0.9.9-rc2引入函数GEODIST(lat1, long1, lat2, long2)，它根据坐标计算两个指定点之间的地表距离。请注意经纬度都要以角度为单位，而结果是以米为单位的。四个参数都可以是任意表达式。当其中一对参数引用的是文档属性对而另一对参数是常数，系统会自动选择一条优化的路径。

4.6. 结果分组（聚类）

有时将搜索结果分组（或者说“聚类”）并对每组中的结果计数是很有用的－例如画个漂亮的图来展示每个月有多少的blog日志，或者把Web搜索结果按站点分组，或者把找到的论坛帖子按其作者分组。

理论上，这可以分两步实现：首先在Sphinx中做全文检索，再在SQL服务器端对得到的ID分组。但是现实中在大结果集（10K到10M个匹配）上这样做通常会严重影响性能。

为避免上述问题，Sphinx提供了一种“分组模式”，可以用API调用SetGroupBy()来开启。在分组时，根据group-by值给匹配项赋以一个分组。这个值用下列内建函数之一根据特定的属性值计算：

SPH_GROUPBY_DAY, 从时间戳中按YYYYMMDD格式抽取年、月、日;
SPH_GROUPBY_WEEK, 从时间戳中按YYYYNNN格式抽取年份和指定周数（自年初计起）的第一天;
SPH_GROUPBY_MONTH, 从时间戳中按YYYYMM格式抽取月份;
SPH_GROUPBY_YEAR, 从时间戳中按YYYY格式抽取年份;
SPH_GROUPBY_ATTR, 使用属性值自身进行分组.

最终的搜索结果中每组包含一个最佳匹配。分组函数值和每组的匹配数目分别以“虚拟”属性@group 和@count 的形式返回.

结果集按group-by排序子句排序，语法与SPH_SORT_EXTENDED 排序子句的语法相似。除了@id和@weight，分组排序子句还包括：

@group (groupby函数值),
@count (组中的匹配数目).

默认模式是根据groupby函数值降序排列，即按照 "@group desc".

排序完成时，结果参数total_found会包含在整个索引上匹配的组的总数目。

注意: 分组操作在固定的内存中执行，因此它给出的是近似结果；所以total_found报告的数目可能比实际给出的个分组数目的和多。@count也可能被低估。要降低不准确性，应提高max_matches。如果max_matches允许存储找到的全部分组，那结果就是百分之百准确的。

例如，如果按相关度排序，同时用SPH_GROUPBY_DAY函数按属性"published"分组，那么：

 结果中包含每天的匹配结果中最相关的那一个，如果那天有记录匹配的话,
 结果中还附加给出天的编号和每天的匹配数目,
 结果以天的编号降序排列（即最近的日子在前面）.

从版本0.9.9-rc2开始, 当使用GROUP BY时，可以通过SetSelect() API调用聚合函数 (AVG(), MIN(), MAX(), SUM())

4.7. 分布式搜索

为提高可伸缩性，Sphnix提供了分布式检索能力。分布式检索可以改善查询延迟问题（即缩短查询时间）和提高多服务器、多CPU或多核环境下的吞吐率（即每秒可以完成的查询数）。这对于大量数据（即十亿级的记录数和TB级的文本量）上的搜索应用来说是很关键的。

其关键思想是对数据进行水平分区（HP，Horizontally partition），然后并行处理。

分区不能自动完成，您需要

在不同服务器上设置Sphinx程序集（indexer和searchd）的多个实例;
让这些实例对数据的不同部分做索引（并检索）;
在searchd的一些实例上配置一个特殊的分布式索引;
然后对这个索引进行查询.

这个特殊索引只包括对其他本地或远程索引的引用，因此不能对它执行重新建立索引的操作，相反，如果要对这个特殊索引进行重建，要重建的是那些被这个索引被引用到的索引。

当searchd收到一个对分布式索引的查询时，它做如下操作

连接到远程代理;
执行查询;
（在远程代理执行搜索的同时）对本地索引进行查询;
接收来自远程代理的搜索结果;
将所有结果合并，删除重复项;
将合并后的结果返回给客户端.

在应用程序看来，普通索引和分布式索引完全没有区别。也就是说，分布式索引对应用程序而言是完全透明的，实际上也无需知道查询使用的索引是分布式的还是本地的。 (就算是在0.9.9之中， Sphinx也不支持以其他的方式来结合分布式索引进行搜索, 也许在将来会去掉该限制.)

任一个searchd实例可以同时做为主控端（master，对搜索结果做聚合）和从属端（只做本地搜索）。这有如下几点好处：

集群中的每台机器都可以做为主控端来搜索整个集群，搜索请求可以在主控端之间获得负载平衡，相当于实现了一种HA（high availability，高可用性），可以应对某个节点失效的情况。
如果在单台多CPU或多核机器上使用，一个做为代理对本机进行搜索的searchd实例就可以利用到全部的CPU或者核。

如果在单台多CPU或多核机器上使用，一个做为代理对本机进行搜索的searchd实例就可以利用到全部的CPU或者核。

4.8. `searchd`查询日志格式

searchd 将全部成功执行的搜索查询都记录在查询日志文件中。以下是一个类似记录文件的例子：

[Fri Jun 29 21:17:58 2007] 0.004 sec [all/0/rel 35254 (0,20)] [lj] test
[Fri Jun 29 21:20:34 2007] 0.024 sec [all/0/rel 19886 (0,20) @channel_id] [lj] test

日志格式如下

[query-date] query-time [match-mode/filters-count/sort-mode
    total-matches (offset,limit) @groupby-attr] [index-name] query

匹配模式（match-mode）可以是如下值之一

"all" 代表 SPH_MATCH_ALL 模式;
"any" 代表 SPH_MATCH_ANY 模式;
"phr" 代表 SPH_MATCH_PHRASE 模式;
"bool" 代表 SPH_MATCH_BOOLEAN 模式;
"ext" 代表 SPH_MATCH_EXTENDED 模式;
"ext2" 代表 SPH_MATCH_EXTENDED2 模式;
"scan" 代表使用了完整扫描模式，这可能是由于设置了SPH_MATCH_FULLSCAN模式导致的，也可能是因为查询是空的。 (参见文档匹配模式)

排序模式（sort-mode）可以取如下值之一:

"rel" 代表 SPH_SORT_RELEVANCE 模式;
"attr-" 代表 SPH_SORT_ATTR_DESC 模式;
"attr+" 代表 SPH_SORT_ATTR_ASC 模式;
"tsegs" 代表 SPH_SORT_TIME_SEGMENTS 模式;
"ext" 代表 SPH_SORT_EXTENDED 模式.

此外，如果searchd 启动的时候带参数 --iostats，那么在列出被搜索的全部索引后还会给出一块数据。.

一个查询日志项看起来就像这样:

[Fri Jun 29 21:17:58 2007] 0.004 sec [all/0/rel 35254 (0,20)] [lj]
   [ios=6 kb=111.1 ms=0.5] test

多出来的这块数据是关于搜索中执行的I/O操作的信息，包括执行的I/O操作次数、从索引文件中读取数据的kb数和I/O操作占用的时间（尽管这个时间还包括一个后台处理组件所占用的，但主要是I/O时间）

4.9. MySQL 协议支持与 SphinxQL

Sphinx的searchd守护程序从版本0.9.9-rc2开始支持MySQL二进制网络协议，并且能够通过标准的MySQL API访问。例如，“mysql”命令行程序可以很好地工作。以下是用MySQL客户端对Sphinx进行查询的例子：

$ mysql -P 9306
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1
Server version: 0.9.9-dev (r1734)

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> SELECT * FROM test1 WHERE MATCH('test') 
    -> ORDER BY group_id ASC OPTION ranker=bm25;
+------+--------+----------+------------+
| id   | weight | group_id | date_added |
+------+--------+----------+------------+
|    4 |   1442 |        2 | 1231721236 |
|    2 |   2421 |      123 | 1231721236 |
|    1 |   2421 |      456 | 1231721236 |
+------+--------+----------+------------+
3 rows in set (0.00 sec)

请注意mysqld甚至根本没有在测试机上运行。所有事情都是searchd自己搞定的。

新的访问方法是对原生API的一种补充，原生API仍然完美可用。事实上，两种访问方法可以同时使用。另外，原生API仍旧是默认的访问方法。MySQL协议支持需要经过额外的配置才能启用。当然这只需要更动一行配置文件，加入一个协议为mysql41的监听器（listener）就可以了：

listen = localhost:9306:mysql41

如果仅仅支持这个协议但不支持SQL语法，那没什么实际意义。因此Sphinx现在还支持SQL的一个很小的子集，我们给这个子集起个绰号，叫SphinxQL。目前已经实现的语句有：

SELECT
SHOW WARNINGS
SHOW STATUS
SHOW META

SELECT 语句，语法仿照标准SQL，但有一些Sphinx特有的扩展，也缺少一些标准SQL的特性（比如（目前）不支持JOIN）。具体地说：

列列表子句。列名、任意表达式以及星号（“*”）都允许出现在列列表中（即“SELECT @id, group_id*123+456 FROM test1”是合法的）。与标准SQL不同，任何计算出的表达式都必须有一个有效的标识符作为别名。目前，特殊名称必须有一个前导的“at”符号（@），例如@id和@weight。这个限制未来会被放宽。.
• FROM子句。FROM子句列举了要从哪些索引中进行搜索。与标准SQL不同，逗号的意思类似它在Query()API调用中的意思，代表全文索引的枚举，而不代表JOIN。
• WHERE子句。这个子句的内容既可以对应到全文查询，也可以对应过滤器。比较操作符(=, !=, <, >, <=, >=)、IN()、AND、NOT和BETWEEN等都被支持，她们直接映射成过滤器。而OR操作符尚未得到支持，但未来会支持。支持 MATCH(‘query’)这种形式，它被映射成一个全文查询。系统按照全文查询规则理解查询。在WHERE子句中最多只能有一个MATCH()。
• GROUP BY子句。目前仅支持根据一个列进行分组，但这个列可以是一个计算出来的表达式。
```
SELECT *, group_id*1000+article_type AS gkey FROM example GROUP BY gkey
```
系统支持将聚集函数（AVG()，MIN()，MAC()，SUM()）用在列列表子句中。这些聚集函数的参数既可以是简单的属性也可以是任意表达式。 COUNT(*)被隐含支持，因为使用GROUP BY就会导致@count这列自动被包括在结果集合中。未来可能会添加显式的支持。COUNT(DISTINCT attr)也被支持。目前每个查询中至多只能有一个COUNT(DISTINCT)，而且参数必须是属性。这两种限制未来都可能被放宽。
```
SELECT *, AVG(price) AS avgprice, COUNT(DISTINCT storeid)
FROM products
WHERE MATCH('ipod')
GROUP BY vendorid
```

WITHIN GROUP ORDER BY子句。这个子句是Sphinx引入的，它使我们可以控制一个分组中最优的行是怎样选出的。这个自己的语法跟标准的ORDER BY子句相同：

SELECT *, INTERVAL(posted,NOW()-7*86400,NOW()-86400) AS timeseg
FROM example WHERE MATCH('my search query')
GROUP BY siteid
WITHIN GROUP ORDER BY @weight DESC
ORDER BY timeseg DESC, @weight DESC

ORDER BY子句。不同于标准SQL，只能根据列名（而不是表达式）排序，必须显式地写明ASC（升序）或者DESC（降序）。不过列名可以是通过表达式计算出来的。
```
SELECT *, @weight*10+docboost AS skey FROM example ORDER BY skey
```
LIMIT子句。支持LIMIT N和LIMIT M,N两种格式。与标准SQL不同（但是就像在Sphinx API中那样），默认有个隐含的LIMIT 0,20。
• OPTION子句。这是Sphinx引入的特殊扩展，它使我们可以设置一些只影响一个查询的选项。语法如下：
```
OPTION <optionname>=<value> [ , ... ]
```
支持设置的选项和允许设置的值如下：例子:
```
SELECT * FROM test WHERE MATCH('@title hello @body world')
OPTION ranker=bm25, max_matches=3000
```

'ranker' - 以下值之一 'proximity_bm25', 'bm25', 'none', 'wordcount', 'proximity', 'matchany', 或者 'fieldmask'
'max_matches' - 整数（当前查询的最大匹配数目）
'cutoff' - 整数（最大匹配数阈值）
'max_query_time' - 整数（最大搜索时间阈值，毫秒）
'retry_count' - 整数（分布式重试数目）
'retry_delay' - 整数（分布式重试的延迟时间，毫秒）

SHOW WARNINGS 语句，用于获取上一条查询产生的警告信息。返回的信息还包括该查询本身：

mysql> SELECT * FROM test1 WHERE MATCH('@@title hello') \G
ERROR 1064 (42000): index test1: syntax error, unexpected TOK_FIELDLIMIT
near '@title hello'

mysql> SELECT * FROM test1 WHERE MATCH('@title -hello') \G
ERROR 1064 (42000): index test1: query is non-computable (single NOT operator)

mysql> SELECT * FROM test1 WHERE MATCH('"test doc"/3') \G
*************************** 1. row ***************************
        id: 4
    weight: 2500
  group_id: 2
date_added: 1231721236
1 row in set, 1 warning (0.00 sec)

mysql> SHOW WARNINGS \G
*************************** 1. row ***************************
  Level: warning
   Code: 1000
Message: quorum threshold too high (words=2, thresh=3); replacing quorum operator
         with AND operator
1 row in set (0.00 sec)

SHOW STATUS 语句，显示一些很有用的性能计数器。仅当searchd启动时带有--iostats和--cpustats开关时，IO和CPU计数器才分别可用。

mysql> SHOW STATUS;
+--------------------+-------+
| Variable_name      | Value |
+--------------------+-------+
| uptime             | 216   |
| connections        | 3     |
| maxed_out          | 0     |
| command_search     | 0     |
| command_excerpt    | 0     |
| command_update     | 0     |
| command_keywords   | 0     |
| command_persist    | 0     |
| command_status     | 0     |
| agent_connect      | 0     |
| agent_retry        | 0     |
| queries            | 10    |
| dist_queries       | 0     |
| query_wall         | 0.075 |
| query_cpu          | OFF   |
| dist_wall          | 0.000 |
| dist_local         | 0.000 |
| dist_wait          | 0.000 |
| query_reads        | OFF   |
| query_readkb       | OFF   |
| query_readtime     | OFF   |
| avg_query_wall     | 0.007 |
| avg_query_cpu      | OFF   |
| avg_dist_wall      | 0.000 |
| avg_dist_local     | 0.000 |
| avg_dist_wait      | 0.000 |
| avg_query_reads    | OFF   |
| avg_query_readkb   | OFF   |
| avg_query_readtime | OFF   |
+--------------------+-------+
29 rows in set (0.00 sec)

SHOW META 语句，显示关于上一条查询的一些额外的元信息（meta-information），比如查询时间和关于关键词的统计信息：

mysql> SELECT * FROM test1 WHERE MATCH('test|one|two');
+------+--------+----------+------------+
| id   | weight | group_id | date_added |
+------+--------+----------+------------+
|    1 |   3563 |      456 | 1231721236 |
|    2 |   2563 |      123 | 1231721236 |
|    4 |   1480 |        2 | 1231721236 |
+------+--------+----------+------------+
3 rows in set (0.01 sec)

mysql> SHOW META;
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| total         | 3     |
| total_found   | 3     |
| time          | 0.005 |
| keyword[0]    | test  |
| docs[0]       | 3     |
| hits[0]       | 5     |
| keyword[1]    | one   |
| docs[1]       | 1     |
| hits[1]       | 2     |
| keyword[2]    | two   |
| docs[2]       | 1     |
| hits[2]       | 2     |
+---------------+-------+
12 rows in set (0.00 sec)

5. 命令行工具参考

就像其他地方已经提到的，Sphinx不是个名叫“sphinx”的单独可执行程序，而是由四个独立的程序共同组成的。本节介绍这些工具和他们的用法。

5.1. `indexer`命令参考

indexer 是Sphinx的两个关键工具之一。不管是从命令行直接调用，还是作为一个较大的脚本的一部分使用，indexer都只负责一件事情——收集要被检索的数据。

indexer的调用语法基本上是这样：

indexer [OPTIONS] [indexname1 [indexname2 [...]]]

用户可以在sphinx.conf中设置好可能有哪些索引（index）（这些索引可以在晚些时候别搜索），因此在调用indexer的时候，最简单的情况下，只需要告诉它你要简历哪个（或者哪些）索引就行了。

假设 sphinx.conf 包含了两个索引的具体设置， mybigindex 和 mysmallindex, ，你可以这么调用:

$ indexer mybigindex
$ indexer mysmallindex mybigindex

在配置文件sphinx.conf里面，用户可以为他们的数据指定一个或多个索引。然后调用indexer来对其中一个特定的索引进行重新编制索引操作，或者是重新编制所有索引——不限于某一个或同时全部，用户总是可以指定现有索引的一个组合。

indexer的大部分选项都可以在配置文件中给出，然而有一部分选项还需要在命令行上指定，这些选项影响编制索引这一操作是如何进行的。这些选项列举如下：

--config <file> (简写为-c <file>) 使 indexer 将指定的文件file作为配置文件。通常，indexer是会在安装目录（例如e.g. /usr/local/sphinx/etc/sphinx.conf ，如果sphinx被安装在 /usr/local/sphinx）中寻找sphinx.conf，若找不到，则继续在用户在shell中调用indexer时所在的目录中寻找。这个选项一般在共享sphinx安装的情况下使用，比如二进制文件安装在/usr/local/sphinx，而不同用户都有权定制自己的sphinx设置。或者在同一个服务器上运行多个实例的情况下使用。在上述两中情况中，用户可以创建自己的sphinx.conf文件，然后把它做为参数传给indexer。例如：
```
$ indexer --config /home/myuser/sphinx.conf myindex
```
--all使indexer对sphinx.conf文件中列出的所有索引进行重新编制索引，这样就不比一次列出每个索引的名字了。这个选项在配置文件较小的情况下，或者在类似基于cron的维护工作中很有用。在上述情况中，整个索引集每天或每周或别的什么合适的时间间隔中就重新建立一次。用法示例：
```
$ indexer --config /home/myuser/sphinx.conf --all
```
--rotate用于轮换索引。对新的文档建立索引时几乎肯定都确保搜索服务仍然可用，除非你有信心在搜索服务停止同时不给你的用户带来困扰。--rotate建立一个额外的索引，并列于原有索引（与原有索引在相同目录，简单地在原有索引文件名基础上加一个.new后缀）。一旦这个额外的索引建立完成，indexer给searchd发一个SIGHUP信号做为通知。searchd会尝试将索引重新命名（给原有索引加上.old后缀，而把带有.new后缀的新索引改为原名，以达替换之目的），继而用新的文件重启服务。依 seamless_rotate 选项设定之不同，在新索引可用之前可能有一点小的延迟。用法示例：
```
$ indexer --rotate --all
```
--quiet 使indexer不输出除错误（error）外的任何东西。这个选项仍然拽可用在cron定时任务的情境下或者脚本中，这些情况下大部分输出是无关紧要或完全没用的，除非是发生了某些种类的错误。用法示例：
```
$ indexer --rotate --all --quiet
```
--noprogress 不随时显示进度信息，而是仅在索引结束时报告最终的状态细节（例如为哪些文档建立了索引，建立索引的速度等）。当脚本没有运行在一个控制台（console，或“tty”）时，这个选项是默认的。用法示例：
```
$ indexer --rotate --all --noprogress
```
--buildstops <outputfile.text> <N> 像建立索引一样扫描索引对应的数据源，产生一个最终会被加入索引的词项的列表。换种说法，产生一个用这个索引可以检索的词项的列表。注意，这个选项使indexer并不真正更新指定的索引，而只是“假装”建在立索引似地处理一遍数据，包括运行sql_query_pre或者sql_query_post选项指定的查询。outputfile.txt文件最终会包含一个词表，每行一个词，按词频排序，高频在前。参数N指定了列表中最多可出现的词项数目，如果N比索引中全部词项的数目还大，则返回的词项数就是全部词项数。客户端应用程序利用这种字典式的词表来提供“您是要搜索。。。吗？(Did you mean…)”的功能，通常这个选项与下面要讲的--buildfreqs选项一同使用。示例：
```
$ indexer myindex --buildstops word_freq.txt 1000
```
这条命令在当前目录产生一个word_freq.txt文件，内含myindex这个索引中最常用的1000个词，且最常用的排在最前面。注意，当指定了多个索引名或使用了--all选项（相当于列出配置文件中的所有索引名）时，这个选项对其中的最后一个索引起作用。
--buildfreqs 与 --buildstops一同使用 (如果没有指定 --buildstops 则--buildfreqs也被忽略). 它给--buildstops产生的词表的每项增加一个计数信息，即该词在索引中共出现了多少次，这在建立停用词（stop words，出现特别普遍的词）表时可能有用。在开发“您是要搜索。。。吗？(Did you mean…)”的功能时这个选项也能帮上忙，因为有了它你就能知道一个词比另一个相近的词出现得更频繁的程度。示例：
```
$ indexer myindex --buildstops word_freq.txt 1000 --buildfreqs
```
这个命令将产生一个类似于上一条命令的word_freq.txt ，但不同在于，每个词的后面都会附加一个数字，指明在指定的索引中这个词出现了多少次。
--merge <dst-index> <src-index> 用于在物理上将多个索引合并，比方说你在使用“主索引＋增量索引”模式，主索引很少改变，但增量索引很频繁地重建，而--merge选项允许将这两个索引合而为一。操作是从右向左进行的，即先考察src-index的内容，然后在物理上将之与dst-index合并，最后结果留在dst-index里。用伪代码说就是dst-index += src-index。示例：
```
$ indexer --merge main delta --rotate
```
上例中main是主索引，很少更动，delta是增量索引，频繁更新。上述命令调用indexer将delta的内容合并到main里面并且对索引进行轮换。
--merge-dst-range <attr> <min> <max> 在合并索引的时候运行范围过滤。具体地说，向目标索引 (是 --merge 的一个参数，如果没有指定 --merge，则--merge-dst-range 也被忽略)合并时，indexer会对将要合并进去的文档做一次过滤，只有通过过滤才能最终出现在目标索引中。举一个实用的例子，假设某个索引有一个“已删除（deleted）”属性，0代表“尚未删除”。这样一个索引可以用如下命令进行合并：
```
$ indexer --merge main delta --merge-dst-range deleted 0 0
```
这样标记为已删除的文档（值为1）就不会出现在新生成的目标索引中了。这个选项可以在命令行上指定多次，以便指定多个相继的过滤，这样一个文档要想合并到最终的目标索引中去，就必须依次通过全部这些过滤。

5.2. `searchd`命令参考

searchd 也是sphinx的两个关键工具之一。 searchd是系统实际上处理搜索的组件，运行时它表现得就像一种服务，他与客户端应用程序调用的五花八门的API通讯，负责接受查询、处理查询和返回数据集。

不同于 indexer, searchd 并不是设计用来在命令行或者一般的脚本中调用的，相反，它或者做为一个守护程序（daemon）被init.d调用（在Unix/Linux类系统上），或者做为一种服务（在Windows类系统上），因此并不是所有的命令行选项都总是有效，这与构建时的选项有关。

调用 searchd 就像这么简单：

$ searchd [OPTIONS]

不管 searchd 是如何构建的，下列选项总是可用：

--help (可以简写为 -h ) 列出可以在你当前的 searchd 构建上调用的参数。
--config <file> (可简写为 -c <file>) 使 searchd 使用指定的配置文件，与上述indexer的--config开关相同。
--stop 用来停掉 searchd，使用sphinx.conf中所指定的PID文件，因此您可能还需要用--config选项来确认searchd使用哪个配置文件。值得注意的是，调用 --stop 会确保用 UpdateAttributes() 对索引进行的更动会反应到实际的索引文件中去。示例：
```
$ searchd --config /home/myuser/sphinx.conf --stop
```
--status 用来查询运行中的searchd实例的状态，，使用指定的（也可以不指定，使用默认）配置文件中描述的连接参数。它通过配置好的第一个UNIX套接字或TCP端口与运行中的实例连接。一旦连接成功，它就查询一系列状态和性能计数器的值并把这些数据打印出来。在应用程序中，可以用Status() API调用来访问相同的这些计数器。示例：
```
$ searchd --status
$ searchd --config /home/myuser/sphinx.conf --status
```
--pidfile 用来显式指定一个PID文件。PID文件存储着关于searchd的进程信息，这些信息用于进程间通讯（例如indexer需要知道这个PID以便在轮换索引的时候与searchd进行通讯）searchd在正常模式运行时会使用一个PID（即不是使用--console选项启动的），但有可能存在searchd在控制台（--console）模式运行，而同时正在索引正在进行更新和轮换操作的情况，此时就需要一个PID文件。
```
$ searchd --config /home/myuser/sphinx.conf --pidfile /home/myuser/sphinx.pid
```
--console 用来强制searchd以控制台模式启动；典型情况下searchd像一个传统的服务器应用程序那样运行，它把信息输出到（sphinx.conf配置文件中指定的）日志文件中。但有些时候需要调试配置文件或者守护程序本身的问题，或者诊断一些很难跟踪的问题，这时强制它把信息直接输出到调用他的控制台或者命令行上会使调试工作容易些。同时，以控制台模式运行还意味着进程不会fork（因此搜索操作都是串行执行的），也不会写日志文件。（要特别注意，searchd并不是被主要设计用来在控制台模式运行的）。可以这样调用searchd：
```
$ searchd --config /home/myuser/sphinx.conf --console
```
--iostats 当使用日志时（必须在sphinx.conf中启用query_log选项）启用--iostats会对每条查询输出关于查询过程中发生的输入输出操作的详细信息，会带来轻微的性能代价，并且显然会导致更大的日志文件。更多细节请参考 query log format 一节。可以这样启动searchd：
```
$ searchd --config /home/myuser/sphinx.conf --iostats
```
--cpustats 使实际CPU时间报告（不光是实际度量时间（wall time））出现在查询日志文件（每条查询输出一次）和状态报告（累加之后）中。这个选项依赖clock_gettime()系统调用，因此可能在某些系统上不可用。可以这样启动searchd：
```
$ searchd --config /home/myuser/sphinx.conf --cpustats
```
--port portnumber (可简写为 -p) 指定searchd监听的端口，通常用于调试。这个选项的默认值是9312，但有时用户需要它运行在其他端口上。在这个命令行选项中指定端口比配置文件中做的任何设置优先级都高。有效的端口范围是0到65535，但要使用低于1024的端口号可能需要权限较高的账户。使用示例：
```
$ searchd --port 9313
```
--index <index> 强制searchd只提供针对指定索引的搜索服务。跟上面的--port相同，这主要是用于调试，如果是长期使用，则应该写在配置文件中。使用示例：
```
$ searchd --index myindex
```

searchd在Windows平台上有一些特有的选项，与它做为windows服务所产生的额外处理有关，这些选项只存在于Windows二进制版本。

注意，在Windows上searchd默认以--console模式运行，除非用户将它安装成一个服务。

--install 将searchd安装成一个微软管理控制台（Microsoft Management Console，控制面板 / 管理工具 / 服务）中的服务。如果一条命令指定了--install，那么同时使用的其他所有选项，都会被保存下来，服务安装好后，每次启动都会调用这些命令。例如，调用searchd时，我们很可能希望用--config指定要使用的配置文件，那么在使用--install的同时也要加入这个选项。一旦调用了这个选项，用户就可以在控制面板中的管理控制台中对searchd进行启动、停止等操作，因此一切可以开始、停止和重启服务的方法对searchd也都有效。示例：
```
C:\WINDOWS\system32> C:\Sphinx\bin\searchd.exe --install
   --config C:\Sphinx\sphinx.conf
```
如果每次启动searchd你都希望得到I/O stat信息，那就应该把这个选项也用在调用--install的命令行里：
```
C:\WINDOWS\system32> C:\Sphinx\bin\searchd.exe --install
   --config C:\Sphinx\sphinx.conf --iostats
```
--delete 在微软管理控制台（Microsoft Management Console）和其他服务注册的地方删除searchd，当然之前要已经通过--install安装过searchd服务。注意，这个选项既不删除软件本身，也不删除任何索引文件。调用这个选项之后只是使软件提供的服务不能从windows的服务系统中调用，也不能在机器重启后自动启动了。如果调用时searchd正在做为服务运行中，那么现有的示例并不会被结束（一直会运行到机器重启或调用--stop）。如果服务安装时（用--servicename）指定了自定义的名字，那在调用此选项卸载服务时里也需要用--servicename指定相同的名字。示例：
```
C:\WINDOWS\system32> C:\Sphinx\bin\searchd.exe --delete
```
--servicename <name> 在安装或卸载服务时指定服务的名字，这个名字会出现在管理控制台中。有一个默认的名字searchd，但若安装服务的系统可能有多个管理员登录，或同时运行多个searchd实例，那么起一个描述性强的名字将是个好好主意。注意，只有在与--install或者--delete同时使用的时候--servicename才有效，否则这个选项什么都不做。示例：
```
C:\WINDOWS\system32> C:\Sphinx\bin\searchd.exe --install
   --config C:\Sphinx\sphinx.conf --servicename SphinxSearch
```
--ntservice 在Windows平台，管理控制台将searchd做为服务调用时将这个选项传递给它。通常没有必要直接调用这个开关，它是为Windows系统准备的，当服务启动时，系统把这个参数传递给searchd。然而理论上，你也可以用这个开关从命令行将searchd启动成普通服务模式（与--console代表的控制台模式相对）

最后但并非最不重要的，类似其他的守护进程（daemon），searchd多种信号。

SIGTERM
进行一次平滑的重启。新的请求不会被接受；但是已经开始的请求不会被强行中断。
SIGHUP
启动索引轮询。取决于seamless_rotate 的设置，新的请求可能会在短期内陷入停顿；客户端将接收到临时错误。
SIGUSR1
强制重新打开searchd日志和查询日志，使得日志轮询可以进行。

5.3. `search`命令参考

search是Sphinx中的一个辅助工具。searchd负责服务器类环境中的搜索，而search专注于在命令行上对索引进行快速测试，而不需要构建一个复杂的架构来处理到服务器端的连接和处理服务器返回的响应。

注意：search并不是设计用来做为客户端应用程序的一部分。我们强烈建议用户不要针对search编写接口，相反，应该针对searchd。Sphinx提供的任何客户端API也都不支持这种用法。（任何时候search总是每次都重新调入索引，而searchd会把索引缓冲在内存中以利性能）。

澄清了这些我们就可以继续了。很多通过API构造的查询也可以用search来做到，然而对于非常复杂的查询，可能还是用个小脚本和对应的API调用来实现比较简单。除此之外，可能有些新的特性先在searchd系统中实现了而尚未引入到search中。

search 的调用语法如下：

search [OPTIONS] word1 [word2 [word3 [...]]]

调用search并不要求searchd正在运行，只需运行search的账户对配置文件和索引文件及其所在路径有读权限即可。

默认行为是对在配置文件中设置的全部索引的全部字段搜索word1（AND word2 AND word3….）。如果用API调用来构建这个搜索，那相当于向SetMatchMode传递参数SPH_MATCH_ALL，然后在调用Query的时候指定要查询的索引是*。

search有很多选项。首先是通用的选项：

--config <file> (可简写为 -c <file> ) 使search使用指定的配置文件，这与上述indexer的对应选项相同。
--index <index> (可简写为 -i <index> ) 使search仅搜索指定的索引。通常它会尝试搜索sphinx.conf中列出的全部物理索引，不包括分布式索引。
--stdin 使search接受标准输入（STDIN）上传入的查询，而不是命令行上给出的查询。有时你要用脚本通过管道给search传入查询，这正是这个选项的用武之地。

设置匹配方式的选项：

--any (可简写为 -a) 更改匹配模式，匹配指定的任意一个词（word1 OR word2 OR word3），这对应API调用中向SetMatchMode传递参数SPH_MATCH_ANY。
--phrase (可简写为 -p ) 更改匹配模式，将指定的全部词做为一个词组（不包括标点符号）构成查询，这对应API调用中向SetMatchMode传递参数SPH_MATCH_PHRASE。
--boolean (可简写为-b ) 将匹配模式设为 Boolean matching。注意如果在命令行上使用布尔语法，可能需要对某些符号（用反斜线“\”）加以转义，以避免外壳程序（shell）或命令行处理器对这些符号做特殊理解，例如，在Unix/Linux系统上必须转义“&”以防止search被fork成一个后台进程，尽管这个问题也可以像下文一样通过使用--stdin选项来解决。这个选项对应API调用中向SetMatchMode传递参数SPH_MATCH_BOOLEAN。
--ext (可简写为 -e ) 将匹配模式设为Extended matching。这对应与API调用中向SetMatchMode传递参数SPH_MATCH_EXTENDED。要注意的是因为已经有了更好的扩展匹配模式版本2，所以并不鼓励使用这个选项，见下一条说明。
--ext2 (可简写为 -e2 ) 将匹配模式设为 Extended matching, version 2。这个选项对应在API调用中向SetMatchMode传递参数SPH_MATCH_EXTENDED2。要注意这个选项相比老的扩展匹配模式更有效也提供更多的特性，因此推荐使用这个新版的选项。
--filter <attr> <v> (可简写为 -f <attr> <v> ) 对结果进行过滤，只有指定的属性attr匹配指定的值v时才能通过过滤。例如--filter deleted 0 只匹配那些有deleted属性，并且其值是0的文档。也可以在命令行上多次给出--filter以便指定多重过滤，但是如果重复定义针对同一个属性的过滤器，那么第二次指定的过滤条件会覆盖第一次的。

用于处理搜索结果的选项：

--limit <count> (可简写为 -l count ) 限制返回的最多匹配结果数。如果指定了分组（group）选项，则表示的是返回的最多匹配组数。默认值是20个结果（与API相同）
--offset <count> (可简写为 -o <count> ) 从第count个结果开始返回，用于给搜索结果分页。如果想要每页20个结果，那么第二页就从偏移量20开始，第三页从偏移量40开始，以此类推。
--group <attr> (可简写为-g <attr> ) 搜索结果按照指定的属性attr进行分组。类似SQL中的GROUP BY子句，这会将attr属性值一致的结果结合在一起，返回的结果集中的每条都是一组中最好的那条结果。如果没有特别指定，那“最好”指的是相关度最大的。
--groupsort <expr> (可简写为 -gs <expr> ) 尽搜索结果根据-group分组后，再用表达式<expr>的值决定分组的顺序。注意，这个选项指定的不是各组内部哪条结果是最好的，而是分组本身返回的顺序。
--sortby <clause> (可简写为 -s <clause> ) 指定结果按照<clause>中指定的顺序排序。这使用户可以控制搜索结果展现时的顺序，即根据不同的列排序。例如，--sortby "@weight DESC entrytime DESC" 的意思是将结果首先按权值（相关度）排序，如果有两条或以上结果的相关度相同，则他们的顺序由时间值entrytime决定，时间最近（值最大）的排在前面。通常需要将这些项目放在引号里(--sortby "@weight DESC")或者用逗号隔开(--sortby @weight,DESC)，以避免它们被分开处理。另外，与通常的排序模式相同，如果指定了--group(分组)，这个选项就影响分组内部的结果如何排序。
--sortexpr expr (可简写为 -S expr ) 搜索结果展现的顺序由指定的算术表达式expr决定。例如： --sortexpr "@weight + ( user_karma + ln(pageviews) )*0.1"（再次提示，要用引号来避免shell对星号*做特殊处理）。扩展排序模式在Sorting modes 一章下的SPH_SORT_EXTENDED条目下具体讨论。
--sort=date 搜索结果按日期升序（日期较久远的在前）排列。要求索引中有一个属性被指定为时间戳。要求索引中有一个属性被指定为时间戳。
--rsort=date specifies that the results should be sorted by ascending (i.e. oldest first) date. This requires that there is an attribute in the index that is set as a timestamp.
--sort=ts 搜索结果按时间戳分成组。先返回时间戳在最近一小时内的这组结果，在组内部按相关度排序。其后返回时间戳为最近一天之内的结果，也按相关度排序。再之后是最近一周的，最后是最近一个月的。在Sorting modes 一章的SPH_SORT_TIME_SEGMENTS 条目下对此有更详细的讨论。

其他选项：

--noinfo (可简写为-q ) 令search不在SQL数据库中查询文档信息（Document Info）。具体地说，为了调试search和MySQL共同使用时出现的问题，你可以在使用这个选项的同时提供一个根据文档ID搜索整个文章全文的查询。细节可参考sql_query_info指令。

5.4. `spelldump`命令参考

spelldump 是Sphinx的一个辅助程序。

用于从ispell或者MySpell格式的字典文件中可用来辅助建立词形列表（wordforms）的内容——词的全部可能变化都预先构造好。

一般用法如下：

spelldump [options] <dictionary> <affix> [result] [locale-name]

两个主要参数是词典的主文件（[language-prefix].dict）和词缀文件（[language-prefix].aff）；通常这两种文件被命名为[语言简写].dict和[语言简写].aff，大多数常见的Linux发行版中都有这些文件，网上也到处找得到。

[result] 指定的是字典数据的输出位置，而[locale-name]指定了具体使用的区域设置(locale)

还有一个-c [file]选项，用来指定一个包含大小写转换方面细节的文件。

用法示例：

spelldump en.dict en.aff
spelldump ru.dict ru.aff ru.txt ru_RU.CP1251
spelldump ru.dict ru.aff ru.txt .1251

结果文件会包含字典中包含的全部词，字典序排列，wordforms文件格式。可以根据具体的使用环境定制这些文件。结果文件的一个例子：

zone > zone
zoned > zoned
zoning > zoning

5.5. `indextool`命令参考

indextool 是版本0.9.9-rc2中引入的辅助工具。用于输出关于物理索引的多种调试信息。（未来还计划加入索引验证等功能，因此起名较indextool而不是indexdump）。基本用法如下：

indextool <command> [options]

唯一一个所有命令都有的选项是--config，用于指定配置文件：

--config <file> (可简写为 -c <file> ) 覆盖默认的配置文件名。

其他可用的命令如下：

--dumpheader FILENAME.sph 在设计任何其他索引文件甚至配置文件的前提下，快速输出索引头文件的内容，包括索引的全部设置，尤其是完整的属性列表、字段列表。在版本0.9.9-rc2之前，这个命令是由search工具提供的。
--dumpheader INDEXNAME 输出给定索引名的索引头内容，索引头文件的路径是在配置文件中查得的。
--dumpdocids INDEXNAME 输出给定索引名涉及的文档ID。数据是从属性文件(.spa)中抽取的，因此要求doc_info=extern正常工作。
--dumphitlist INDEXNAME KEYWORD 输出指定关键字KEYWORD在执行索引中的的全部出现。

6. API参考

Sphnix有几种不同编程语言的searchd客户端API的实现。在本文完成之时，我们对我们自己的PHP，Python和java实现提供官方支持。此外，也有一些针对Perl，Ruby和C++的第三方免费、开源API实现。

API的参考实现是用PHP写成的，因为（我们相信）较之其他语言，Sphinx在PHP中应用最广泛。因此这份参考文档基于PHP API的参考，而且这节中的所有的代码样例都用PHP给出。

当然，其他所有API都提供相同的方法，也使用完全相同的网络协议。因此这份文档对他们同样适用。在方法命名习惯方面或者具体数据结构的使用上可能会有小的差别。但不同语言的API提供的功能上绝不会有差异。

6.1. 通用API方法

6.1.1. GetLastError （错误信息）

原型： function GetLastError()

以可读形式返回最近的错误描述信息。如果前一次API调用没有错误，返回空字符串。

任何其他函数（如 Query()）失败后（函数失败一般返回false），都应该调用这个函数，它将返回错误的描述。

此函数本身并不重置对错误描述，因此如有必要，可以多次调用。

6.1.2. GetLastWarning （告警信息）

原型： function GetLastWarning ()

以可读格式返回最近的警告描述信息。如果前一次API调用没有警告，返回空字符串。

您应该调用这个函数来确认您的请求（如 Query()）是否虽然完成了但产生了警告。例如，即使几个远程代理超时了，对分布式索引的搜索查询也可能成功完成。这时会产生一个警告信息。

此函数本身不会重置警告信息，因此如有必要，可以多次调用。

6.1.3. SetServer (设置搜索服务)

原型： function SetServer ( $host, $port )

设置searchd的主机名和TCP端口。此后的所有请求都使用新的主机和端口设置。默认的主机和端口分别是“localhost”和9312。

6.1.4. SetRetries (设置失败重试)

原型： function SetRetries ( $count, $delay=0 )

设置分布式搜索重试的次数和延迟时间。

对于暂时的失败，searchd对每个代理重试至多$count次。$delay是两次重试之间延迟的时间，以毫秒为单位。默认情况下，重试是禁止的。注意，这个调用不会使API本身对暂时失败进行重试，它只是让searchd这样做。目前暂时失败包括connect()调用的各种失败和远程代理超过最大连接数（过于繁忙）的情况。

6.1.5. SetConnectTimeout （设置超时时间）

原型： function SetConnectTimeout ( $timeout )

设置连接超时时间，在与服务器连接时，如果超过这个时间没有连上就放弃。

有时候服务器在响应上会有所延迟，这有可能由于网络的延时，也有可能是因为服务器未处理完的查询太多，堆积所致。不管是什么情况，有了这个选项，就给客户端应用程序提供了一定的控制权，让它可以决定当searchd不可用的时候如何处理，而且可以避免脚本由于超过运行限制而运行失败（尤其是在PHP里）

当连接失败的而时候，会将合适的错误码返回给应用程序，以便在应用程序级别进行错误处理和通知用户。

6.1.6. SetArrayResult （设置结果返回格式）

原型： function SetArrayResult ( $arrayresult )

PHP专用。控制搜索结果集的返回格式（匹配项按数组返回还是按hash返回）

$arrayresult 参数应为布尔型。如果$arrayresult为false（默认），匹配项以PHP hash格式返回，文档ID为键，其他信息（权重、属性）为值。如果$arrayresult为true，匹配项以普通数组返回，包括匹配项的全部信息（含文档ID）

这个调用是对MVA属性引入分组支持时同时引入的。对MVA分组的结果可能包含重复的文档ID。因此需要将他们按普通数组返回，因为hash对每个文档ID仅能保存一个记录。

6.1.7. IsConnectError （检查链接错误）

原型： function IsConnectError ()

检查上一个错误是API层面的网络错误还是searchd返回的远程错误。如果是上一次连接searchd的尝试在API层面失败了，返回真，否则返回假（错误发生在远程，或者根本没有尝试连接）。这是在版本0.9.9-rc1引入的。

6.2. 通用搜索设置

6.2.1. SetLimits （设置结果集偏移量）

原型： function SetLimits ( $offset, $limit, $max_matches=0, $cutoff=0 )

给服务器端结果集设置一个偏移量（$offset）和从那个偏移量起向客户端返回的匹配项数目限制（$limit）。并且可以在服务器端设定当前查询的结果集大小（$max_matches），另有一个阈值（$cutoff），当找到的匹配项达到这个阀值时就停止搜索。全部这些参数都必须是非负整数。

前两个参数的行为与MySQL LIMIT子句中参数的行为相同。他们令searchd从编号为$offset的匹配项开始返回最多$limit个匹配项。偏移量($offset)和结果数限制($limit)的默认值分别是0和20，即返回前20个匹配项。

max_matches这个设置控制搜索过程中searchd在内存中所保持的匹配项数目。一般来说，即使设置了max_matches为1，全部的匹配文档也都会被处理、评分、过滤和排序。但是任一时刻只有最优的N个文档会被存储在内存中，这是为了性能和内存使用方面的原因，这个设置正是控制这个N的大小。注意，max_matches在两个地方设置。针对单个查询的限制由这个API调用指定。但还有一个针对整个服务器的限制，那是由配置文件中的max_matches设置控制的。为防止滥用内存，服务器不允许单个查询的限制高于服务器的限制。

在客户端不可能收到超过max_matches个匹配项。默认的限制是1000，您应该不会遇到需要设置得更高的情况。1000个记录足够向最终用户展示了。如果您是想将结果传输给应用程序以便做进一步排序或过滤，那么请注意，在Sphinx端完成效率要高得多。

$cutoff 设置是为高级性能优化而提供的。它告诉searchd 在找到并处理$cutoff个匹配后就强制停止。

6.2.2. SetMaxQueryTime （设置最大搜索时间）

原型： function SetMaxQueryTime ( $max_query_time )

设置最大搜索时间，以毫秒为单位。参数必须是非负整数。默认值为0，意思是不做限制。

这个设置与SetLimits()中的$cutoff相似，不过这个设置限制的是查询时间，而不是处理的匹配数目。一旦处理时间已经太久，本地搜索查询会被停止。注意，如果一个搜索查询了多个本地索引，那这个限制独立地作用于这几个索引。

6.2.3. SetOverride （设置临时属性值覆盖）

原型： function SetOverride ( $attrname, $attrtype, $values )

设置一个临时的（只对单个查询有效）针对不同文档的属性值覆盖。只支持标量属性。$value是一个哈希表，他的键是要覆盖属性的文档ID，之是对应该文档ID的要覆盖的值。于版本0.9.9-rc1引入。

属性覆盖特性使用户可以针对一次查询“临时性地”修改一些文档的值，不影响其他查询。这个函数可以用来进行数据个性化。例如，假设正在实现一个个性化搜索函数，用来将朋友推荐的帖子排在前面，这类数据不仅是动态的，而且是个性化的，因此不能简单地把这种数据放入索引，因为不能影响其他用户的搜索。而覆盖机制是针对单个查询的，不会影响其他人。因此可以，比如说，给每个文档设置一个“friends_weight”属性，默认值是0，然后临时将文档 123，456，789（当前用户的朋友推荐的）的这个属性设置为1，最后用这个值进行相关度计算。

6.2.4. SetSelect (设置返回信息的内容)

原型： function SetSelect ( $clause )

设置select子句，列出具体要取出的属性以及要计算并取出的expressions。子句的语法模仿了SQL。于版本0.9.9-rc1引入。

SetSelect()于标准SQL查询中SELECT和FROM之间的部分非常相近。它允许你指定要取出哪些属性（列），以及在这些列上要计算和取出哪些表达式。与SQL语言的区别是，表达式必须用关键字AS给每个表达式取一个别名，别名必须是有效的标识符（由字母和数字组成）。在SQL里面可以这样做，但是不是强制的。Sphinx强制必须有别名，以便计算结果总是可以以一个“正常”的名字在结果集中返回，或者在其他子句中引用，等等。

其他方面基本上等同于SQL。支持星号（“*”），支持函数，支持任意数目的表达式。计算出的表达式可以用于排序、过滤和分组，这与其他常规属性相同。

从版本0.9.9-rc2开始，允许使用GROUP BY的时候使用聚集函数（AVG(), MIN(), MAX(), SUM()）。

表达式排序（Section 4.5, “SPH_SORT_EXPR 模式”）和地表距离计算函数（Section 6.4.5, “SetGeoAnchor （设置地表距离锚点）”）现在的内部实现就是这种表达式计算机制，分别使用“魔法名字”“@expr”和“@geodist”。

示例：

$cl->SetSelect ( "*, @weight+(user_karma+ln(pageviews))*0.1 AS myweight" );
$cl->SetSelect ( "exp_years, salary_gbp*{$gbp_usd_rate} AS salary_usd,
   IF(age>40,1,0) AS over40" );
$cl->SetSelect ( "*, AVG(price) AS avgprice" );

6.3. 全文搜索设置

6.3.1. SetMatchMode （设置匹配模式）

原型： function SetMatchMode ( $mode )

设置全文查询的匹配模式，见Section 4.1, “匹配模式”中的描述。参数必须是一个与某个已知模式对应的常数。

警告： （仅PHP）查询模式常量不能包含在引号中，那给出的是一个字符串而不是一个常量：

$cl->SetMatchMode ( "SPH_MATCH_ANY" ); // INCORRECT! will not work as expected
$cl->SetMatchMode ( SPH_MATCH_ANY ); // correct, works OK

6.3.2. SetRankingMode （设置评分模式）

原型： function SetRankingMode ( $ranker )

设置评分模式。目前只在SPH_MATCH_EXTENDED2这个匹配模式中提供。参数必须是与某个已知模式对应的常数。

Sphinx默认计算两个对最终匹配权重有用的因子。主要是查询词组与文档文本的相似度。其次是称之为BM25的统计函数，该函数值根据关键字文档中的频率（高频导致高权重）和在整个索引中的频率（低频导致高权重）在0和1之间取值。

然而，有时可能需要换一种计算权重的方法——或者可能为了提高性能而根本不计算权值，结果集用其他办法排序。这个目的可以通过设置合适的相关度计算模式来达到。

已经实现的模式包括：

SPH_RANK_PROXIMITY_BM25, 默认模式，同时使用词组评分和BM25评分，并且将二者结合。
SPH_RANK_BM25, 统计相关度计算模式，仅使用BM25评分计算（与大多数全文检索引擎相同）。这个模式比较快，但是可能使包含多个词的查询的结果质量下降。
SPH_RANK_NONE, 禁用评分的模式，这是最快的模式。实际上这种模式与布尔搜索相同。所有的匹配项都被赋予权重1。
SPH_RANK_WORDCOUNT, 根据关键词出现次数排序。这个排序器计算每个字段中关键字的出现次数，然后把计数与字段的权重相乘，最后将积求和，作为最终结果。
SPH_RANK_PROXIMITY, 版本0.9.9-rc1新增，将原始的词组相似度作为结果返回。在内部，这个模式被用来模拟SPH_MATCH_ALL的查询。
SPH_RANK_MATCHANY, 版本0.9.9-rc1新增，返回之前在SPH_MATCH_ANY中计算的位次，在内部这个模式用于模拟SPH_MATCH_ANY的查询。
SPH_RANK_FIELDMASK, 版本0.9.9-rc2新增，返回一个32位掩码，其中第N位对应第N个全文字段，从0开始计数，如果某个字段中出现了满足查询的关键词，则对应的标志位被置1。

6.3.3. SetSortMode （设置排序模式）

原型： function SetSortMode ( $mode, $sortby="" )

设置匹配项的排序模式，见Section 4.5, “排序模式”中的描述。参数必须为与某个已知模式对应的常数。

警告： （仅PHP）查询模式常量不能包含在引号中，那给出的是一个字符串而不是一个常量：

$cl->SetSortMode ( "SPH_SORT_ATTR_DESC" ); // INCORRECT! will not work as expected
$cl->SetSortMode ( SPH_SORT_ATTR_ASC ); // correct, works OK

6.3.4. SetWeights （设置权重）

原型： function SetWeights ( $weights )

按在索引中出现的先后顺序给字段设置权重。不推荐使用, 建议使用 SetFieldWeights()。

6.3.5. SetFieldWeights （设置字段权重）

原型： function SetFieldWeights ( $weights )

按字段名称设置字段的权值。参数必须是一个hash（关联数组），该hash将代表字段名字的字符串映射到一个整型的权值上。

字段权重影响匹配项的评级。Section 4.4, “权值计算” 解释了词组相似度如何影响评级。这个调用用于给不同的全文数据字段指定不同于默认值的权值。

给定的权重必须是正的32位整数。最终的权重也是个32位的整数。默认权重为1。未知的属性名会被忽略。

目前对权重没有强制的最大限制。但您要清楚，设定过高的权值可能会导致出现32位整数的溢出问题。例如，如果设定权值为10000000并在扩展模式中进行搜索，那么最大可能的权值为10M（您设的值）乘以1000（BM25的内部比例系数，参见Section 4.4, “权值计算”, “权值计算”）再乘以1或更多（词组相似度评级）。上述结果最少是100亿，这在32位整数里面没法存储，将导致意想不到的结果。

6.3.6. SetIndexWeights （设置索引权重）

原型： function SetIndexWeights ( $weights )

设置索引的权重，并启用不同索引中匹配结果权重的加权和。参数必须为在代表索引名的字符串与整型权值之间建立映射关系的hash（关联数组）。默认值是空数组，意思是关闭带权加和。

当在不同的本地索引中都匹配到相同的文档ID时，Sphinx默认选择查询中指定的最后一个索引。这是为了支持部分重叠的分区索引。

然而在某些情况下索引并不仅仅是被分区了，您可能想将不同索引中的权值加在一起，而不是简单地选择其中的一个。SetIndexWeights()允许您这么做。当开启了加和功能后，最后的匹配权值是各个索引中的权值的加权合，各索引的权由本调用指定。也就是说，如果文档123在索引A被找到，权值是2，在B中也可找到，权值是3，而且您调用了SetIndexWeights ( array ( "A"=>100, "B"=>10 ) )，那么文档123最终返回给客户端的权值为2*100+3*10 = 230。

6.4. 结果集过滤设置

6.4.1. SetIDRange （设置查询ID范围）

原型： function SetIDRange ( $min, $max )

设置接受的文档ID范围。参数必须是整数。默认是0和0，意思是不限制范围。

此调用执行后，只有ID在$min和$max（包括$min和$max）之间的文档会被匹配。

6.4.2. SetFilter （设置属性过滤）

原型： function SetFilter ( $attribute, $values, $exclude=false )

增加整数值过滤器。

此调用在已有的过滤器列表中添加新的过滤器。$attribute是属性名。$values是整数数组。$exclude是布尔值，它控制是接受匹配的文档（默认模式，即$exclude为false时）还是拒绝它们。

只有当索引中$attribute列的值与$values中的任一值匹配时文档才会被匹配（或者拒绝，如果$exclude值为true）

6.4.3. SetFilterRange （设置属性范围）

原型： function SetFilterRange ( $attribute, $min, $max, $exclude=false )

添加新的整数范围过滤器。

此调用在已有的过滤器列表中添加新的过滤器。$attribute是属性名, $min 、$max定义了一个整数闭区间，$exclude布尔值，它控制是接受匹配的文档（默认模式，即$exclude为false时）还是拒绝它们。

只有当索引中$attribute列的值落在$min 和 $max之间（包括$min 和 $max），文档才会被匹配（或者拒绝，如果$exclude值为true）。

6.4.4. SetFilterFloatRange （设置浮点数范围）

原型： function SetFilterFloatRange ( $attribute, $min, $max, $exclude=false )

增加新的浮点数范围过滤器。

此调用在已有的过滤器列表中添加新的过滤器。$attribute是属性名, $min 、$max定义了一个浮点数闭区间，$exclude必须是布尔值，它控制是接受匹配的文档（默认模式，即$exclude为false时）还是拒绝它们。

只有当索引中$attribute列的值落在$min 和 $max之间（包括$min 和 $max），文档才会被匹配（或者拒绝，如果$exclude值为true）。

6.4.5. SetGeoAnchor （设置地表距离锚点）

原型： function SetGeoAnchor ( $attrlat, $attrlong, $lat, $long )

为地表距离计算设置锚点，并且允许使用它们。

$attrlat 和 $attrlong是字符串，分别指定了对应经度和纬度的属性名称。$lat 和 $long是浮点值，指定了锚点的经度和纬度值，以角度为单位。

一旦设置了锚点，您就可以在您的过滤器和/或排序表达式中使用"@geodist"特殊属性。Sphinx将在每一次全文检索中计算给定经纬度与锚点之前的地表距离，并把此距离附加到匹配结果上去。SetGeoAnchor和索引属性数据中的经纬度值都是角度。而结果会以米为单位返回，因此地表距离1000.0代表1千米。一英里大约是1609.344米。

6.5. 分组设置

6.5.1. SetGroupBy （设置分组的属性）

原型： function SetGroupBy ( $attribute, $func, $groupsort="@group desc" )

设置进行分组的属性、函数和组间排序模式，并启用分组（参考Section 4.6, “结果分组（聚类）”中的描述）。

$attribute是字符串，为进行分组的属性名。$func为常数，它指定内建函数，该函数以前面所述的分组属性的值为输入，目前的可选的值为： SPH_GROUPBY_DAY、SPH_GROUPBY_WEEK、 SPH_GROUPBY_MONTH、 SPH_GROUPBY_YEAR、SPH_GROUPBY_ATTR 。$groupsort 是控制分组如何排序的子句。其语法与Section 4.5, “SPH_SORT_EXTENDED 模式”中描述的相似。

分组与SQL中的GROUP BY子句本质上相同。此函数调用产生的结果与下面伪代码产生的结果相同。

SELECT ... GROUP BY $func($attribute) ORDER BY $groupsort

注意，影响最终结果集中匹配项顺序的是$groupsort。排序模式（见Section 6.3.3, “SetSortMode （设置排序模式）”）影响每个分组内的顺序，即每组内哪些匹配项被视为最佳匹配。比如，组之间可以根据每组中的匹配项数量排序的同时每组组内又根据相关度排序。

从版本 0.9.9-rc2 开始, 聚合函数 (AVG(), MIN(), MAX(), SUM()) 可以在GROUP BY时被 SetSelect() API 调用。

6.5.2. SetGroupDistinct （设置分组计算不同值的属性）

原型： function SetGroupDistinct ( $attribute )

设置分组中需要计算不同取值数目的属性名。只在分组查询中有效。

$attribute是包含属性名的字符串。每个组的这个属性的取值都会被储存起来（只要内存允许），其后此属性在此组中不同值的总数会被计算出来并返回给客户端。这个特性与标准SQL中的COUNT(DISTINCT)子句类似。因此如下Sphinx调用

$cl->SetGroupBy ( "category", SPH_GROUPBY_ATTR, "@count desc" );
$cl->SetGroupDistinct ( "vendor" );

等价于如下的SQL语句：

SELECT id, weight, all-attributes,
	COUNT(DISTINCT vendor) AS @distinct,
	COUNT(*) AS @count
FROM products
GROUP BY category
ORDER BY @count DESC

在上述示例伪代码中，SetGroupDistinct()调用只与COUNT(DISINCT vendor)对应。GROUP BY，ORDER By和COUNT(*)子句则与SetGroupBY()调用等价。两个查询都会在每类中返回一个匹配的行。除了索引中的属性，匹配项还可以包含每类的匹配项计数和每类中不同来源 ID的计数。

6.6. 搜索数据

6.6.1. Query （查询）

原型： function Query ( $query, $index="*", $comment="" )

连接到searchd服务器，根据服务器的当前设置执行给定的查询，取得并返回结果集。

$query是查询字串，$index是包含一个或多个索引名的字符串。一旦发生一般错误，则返回假并设置GetLastError()信息。若成功则返回搜索的结果集。此外, $comment 将被发送到查询日志中搜索部分的前面，这对于调试是非常有用的。目前，注释的长度限制为128个字符以内。

$index的默认值是"*"，意思是对全部本地索引做查询。索引名中允许的字符包括拉丁字母（a-z），数字（0-9），减号（-）和下划线（_），其他字符均视为分隔符。因此，下面的示例调用都是有效的，而且会搜索相同的两个索引：

$cl->Query ( "test query", "main delta" );
$cl->Query ( "test query", "main;delta" );
$cl->Query ( "test query", "main, delta" );

给出多个索引时的顺序是有意义的。如果同一个文档ID的文档在多个索引中找到，那么权值和属性值会取最后一个索引中所存储的作为该文档ID的权值和属性值，用于排序、过滤，并返回给客户端（除非用SetIndexWeights()显式改变默认行为）。因此在上述示例中，索引“delta”中的匹配项总是比索引“main”中的更优先。

如果搜索成功，Query()返回的结果集包含找到的全部匹配项中的一部分（根据SetLimits()之设定）和与查询相关的统计数据。结果集是hash（仅PHP，其他语言的API可能使用其他数据结构），包含如下键和值：

"matches":
是一个hash表，存储文档ID以及其对应的另一个包含文档权重和属性值的hash表（或者是数组，如果启用了SetArrayResult()）。
"total":
此查询在服务器检索所得的匹配文档总数（即服务器端结果集的大小）。这是在当前设置下，用当前查询可以从服务器端获得的匹配文档数目的上限。
"total_found":
（服务器上找到和处理了的）索引中匹配文档的总数。
"words":
一个hash，它将查询关键字（关键字已经过大小写转换，取词干和其他处理）映射到一个包含关于关键字的统计数据（“docs”——在多少文档中出现，“hits”——共出现了多少次）的小hash表上。
"error":
searchd报告的错误信息（人类可读的字符串）。若无错误则为空字符串。
"warning":
searchd报告的警告信息（人类可读字符串）。若无警告则为空串。

需要指出的是 Query() 索执行的操作，与没有中间步骤的 AddQuery()和 RunQueries() 相同；它类似一次单独的AddQuery()调用，紧跟一次相应的RunQueries()调用，然后返回匹配的第一个数组元素（从第一次，也是仅有的一次查询返回）。

6.6.2. AddQuery （增加批量查询）

原型： function AddQuery ( $query, $index="*", $comment="" )

向批量查询增加一个查询。$query为查询串。$index为包含一个或多个索引名的字符串。此外, 如果提供了$comment，它将被发送到查询日志中搜索部分的前面，这对于调试是非常有用的。目前，注释的长度限制为128个字符以内。返回RunQueries()返回的数组中的一个下标。

批量查询（或多查询）使searchd能够进行可能的内部优化，并且无论在任何情况下都会减少网络连接和进程创建方面的开销。相对于单独的查询，批量查询不会引入任何额外的开销。因此当您的Web页运行几个不同的查询时，一定要考虑使用批量查询。

例如，多次运行同一个全文查询，但使用不同的排序或分组设置，这会使searchd仅运行一次开销昂贵的全文检索和相关度计算，然后在此基础上产生多个分组结果。

有时您不仅需要简单地显示搜索结果，而且要显示一些与类别相关的计数信息，例如按制造商分组后的产品数目，此时批量查询会节约大量的开销。若无批量查询，您会必须将这些本质上几乎相同的查询运行多次并取回相同的匹配项，最后产生不同的结果集。若使用批量查询，您只须将这些查询简单地组成一个批量查询，Sphinx会在内部优化掉这些冗余的全文搜索。

AddQuery() 在内部存储全部当前设置状态以及查询，您也可在后续的AddQuery()调用中改变设置。早先加入的查询不会被影响，实际上没有任何办法可以改变它们。下面是一个示例：

$cl->SetSortMode ( SPH_SORT_RELEVANCE );
$cl->AddQuery ( "hello world", "documents" );

$cl->SetSortMode ( SPH_SORT_ATTR_DESC, "price" );
$cl->AddQuery ( "ipod", "products" );

$cl->AddQuery ( "harry potter", "books" );

$results = $cl->RunQueries ();

用上述代码，第一个查询会在“documents”索引上查询“hello world”并将结果按相关度排序，第二个查询会在“products”索引上查询“ipod”并将结果按价格排序，第三个查询在“books”索引上搜索“harry potter”，结果仍按价格排序。注意，第二个SetSortMode()调用并不会影响第一个查询（因为它已经被添加了），但后面的两个查询都会受影响。

此外，在AddQuery()之前设置的任何过滤，都会被后续查询继续使用。因此，如果在第一个查询前使用SetFilter()，则通过AddQuery()执行的第二个查询（以及随后的批量查询）都会应用同样的过滤，除非你先调用ResetFilters()来清除过滤规则。同时，你还可以随时加入新的过滤规则

AddQuery()并不修改当前状态。也就是说，已有的全部排序、过滤和分组设置都不会因这个调用而发生改变，因此后续的查询很容易地复用现有设置。

AddQuery()返回RunQueries()结果返回的数组中的一个下标。它是一个从0开始的递增整数，即，第一次调用返回0，第二次返回1，以此类推。这个方便的特性使你在需要这些下标的时候不用手工记录它们。

6.6.3. RunQueries （执行批量查询）

原型： function RunQueries ()

连接到searchd，运行由AddQuery()添加的全部查询，获取并返回它们的结果集。若发生一般错误（例如网络I/O失败）则返回假并设置GetLastError()信息。若成功则返回结果集的简单数组。

该数组中的每一个结果集都跟Query()返回的结果集完全相同。

注意，批量查询请求自身几乎总是成功——除非有网络错误、正在进行索引轮换，或者其他导致整个查询无法被处理的因素。

然而其中的单个的查询很可能失败。此时与之对应的结果集只包含一个非空的"error"信息，而没有关于匹配或查询的统计信息。在极端情况下，批量查询中的所有单个查询可能都失败。但这仍然不会导致报告一般错误，因为API已经成功地连接到searchd，提交了批量查询并得到返回结果——但每个结果集都只包含特定的错误信息。

6.6.4. ResetFilters （清除当前设置的过滤器）

原型： function ResetFilters ()

清除当前设置的过滤器。

通常此调用在使用批量查询的时候会用到。您可能需要为批量查询中的不同查询提供不同的过滤器，为达到这个目的，您需要调用ResetFilters()然后用其他调用增加新的过滤器。

6.6.5. ResetGroupBy （清除现有的分组设置）

原型： function ResetGroupBy ()

清除现有的全部分组设置，并关闭分组。

通常此调用在使用批量查询的时候会用到。单独的分组设置可以用SetGroupBy()和SetGroupDistinct()来改变，但它们不能关闭分组。ResetGroupBy()将之前的分组设置彻底重置并在当前状态下关闭分组模式，因此后续的AddQuery()可以进行无分组的搜索。

6.7. 附加方法

6.7.1. BuildExcerpts （产生文本摘要和高亮）

原型： function BuildExcerpts ( $docs, $index, $words, $opts=array() )

该函数用来产生文档片段（摘要）。连接到searchd，要求它从指定文档中产生片段（摘要），并返回结果。

$docs为包含各文档内容的数组。$index为包含索引名字的字符串。给定索引的不同设置（例如字符集、形态学、词形等方面的设置）会被使用。$words为包含需要高亮的关键字的字符串。它们会按索引的设置被处理。例如，如果英语取词干（stemming）在索引中被设置为允许，那么即使关键词是“shoe”，“shoes”这个词也会被高亮。从版本0.9.9-rc1开始，关键字可以包含通配符，与查询支持的star-syntax类似。$opts为包含其他可选的高亮参数的hash表：

"before_match":
在匹配的关键字前面插入的字符串。默认为"<b>"。
"after_match":
在匹配的关键字后面插入的字符串。默认为 "<b>".
"chunk_separator":
在摘要块（段落）之间插入的字符串。默认为" ... ".
"limit":
摘要最多包含的符号（码点）数。整数，默认为256.
"around":
每个关键词块左右选取的词的数目。整数，默认为5.
"exact_phrase":
是否仅高亮精确匹配的整个查询词组，而不是单独的关键词。布尔值，默认为false.
"single_passage":
是否仅抽取最佳的一个段落。布尔值，默认为false.
"weight_order":
对于抽取出的段落，要么根据相关度排序（权重下降），要么根据出现在文档中的顺序（位置递增）。布尔型，默认是false.

失败时返回false。成功时返回包含有片段（摘要）字符串的数组。

6.7.2. UpdateAttributes （更新属性）

原型： function UpdateAttributes ( $index, $attrs, $values )

立即更新指定文档的指定属性值。成功则返回实际被更新的文档数目（0或更多），失败则返回-1。

$index 为待更新的（一个或多个）索引名。$attrs为属性名字符串的数组，其所列的属性会被更新。$attrs为hash表，$values表的键为文档ID，$values表的值为新的属性值的简单数组。

$index 既可以是一个单独的索引名，也可以是一个索引名的列表，就像Query()的参数。与Query()不同的是不允许通配符，全部待更新的索引必须明确指出。索引名列表可以包含分布式索引。对分布式索引，更新会同步到全部代理上。

只有在docinfo=extern这个存储策略下才可以运行更新。更新非常快，因为操作完全在内存中进行，但它们也可以变成持久的，更新会在searchd干净关闭时（收到SIGTERM信号时）被写入磁盘。在额外限制条件下，MVA属性也可以被更新，参见mva_updates_pool详细了解。

使用示例

$cl->UpdateAttributes ( "test1", array("group_id"), array(1=>array(456)) );
$cl->UpdateAttributes ( "products", array ( "price", "amount_in_stock" ),
	array ( 1001=>array(123,5), 1002=>array(37,11), 1003=>(25,129) ) );

第一条示例语句会更新索引“test1”中的文档1，设置“group_id”为456.第二条示例语句则更新索引“products”中的文档 1001，1002和1003。文档1001的“price”会被更新为123，“amount_in_stock”会被更新为5；文档 1002，“price”变为37而“amount_in_storage”变为11，等等。

6.7.3. BuildKeywords （获取分词结果）

原型： function BuildKeywords ( $query, $index, $hits )

根据指定索引的符号化（tokenizer）方式的设置，从查询中抽取关键词，也可以同时返回每个关键词出现次数的统计信息。返回一个数组，其元素是一些字典，每个字典包含一个关键字的信息。

$query 是抽取关键字的目标。$index是某个索引的名字，系统会使用这个索引的符号化（tokenizer）设置，关键词出现次数的统计信息也从这个索引中得出。$hits是一个布尔值，它指定了是否需要返回关键词出现此处的信息。

使用示例：

$keywords = $cl->BuildKeywords ( "this.is.my query", "test1", false );

6.7.4. EscapeString （转义特殊字符）

原型： function EscapeString ( $string )

查询语言分析器将某些字符理解成特殊操作符，这个函数对字符串中的那些有特殊意义的字符进行转义。返回转义后的字符串。

$string 是待转义的字符串。

表面上看这个函数是多余的，因为可以很容易地在可能调用这个函数的程序里实现这个转义功能。然而这些特殊字符的集合可能随着时间而改变，因此理应提供一个API调用来完成这个功能，并保证任何时候都可以正确地转义全部特殊字符。

使用示例：

$escaped = $cl->EscapeString ( "escaping-sample@query/string" );

6.7.5. Status （查询服务状态）

原型： function Status ()

查询searchd的状态，返回一个数组，数组元素是由状态变量名和值的键值对构成。

使用示例：

$status = $cl->Status ();
foreach ( $status as $row )
	print join ( ": ", $row ) . "\n";

6.8. 持久连接

“持久连接”特性允许利用一个单独的网络连接来运行本来需要多个连接的多个命令。

6.8.1. Open (打开连接)

原型： function Open ()

打开到服务器的持久连接。

6.8.2. Close （关闭连接）

原型： function Close ()

关闭先前打开的持久连接。

Sphinx--强大的开源全文检索引擎，Coreseek--免费开源的中文全文检索引擎

1. 简介

1.1. 什么是Sphinx/Coreseek

1.2. Sphinx/Coreseek 的特性

1.3. 如何得到Sphinx/Coreseek

1.4. 许可协议

1.5. 作者和贡献者

作者

贡献者

1.6. 历史

2. 安装

2.1. 支持的操作系统

2.2. 需要的工具

2.3. 在Linux、BSD上安装Sphinx/Coreseek

2.4. 在Windows上安装Sphinx/Coreseek

2.5. 已知的安装问题和解决办法

2.6. Sphinx/Coreseek快速入门教程

3. 建立索引

3.1. 数据源

3.2. 属性

示例： sphinx.conf 片段:

示例： 应用程序代码 (PHP):

3.3. MVA (多值属性)

3.4. 索引

3.5. 源数据的限制

3.6. 字符集、大小写转换和转换表

3.7. SQL 数据源 (MySQL, PostgreSQL)

区段查询

后查询（sql_post） vs. 索引后查询（sql_post_index）

3.8. xmlpipe 数据源

3.9. xmlpipe2 数据源

3.10. Python 数据源

3.11. 实时索引更新

3.12. 索引合并

4. 搜索

4.1. 匹配模式

4.2. 布尔查询语法

4.3. 扩展查询语法

4.4. 权值计算

4.5. 排序模式

SPH_SORT_TIME_SEGMENTS 模式

SPH_SORT_EXTENDED 模式

SPH_SORT_EXPR 模式

4.6. 结果分组（聚类）

4.7. 分布式搜索

4.8. searchd查询日志格式

4.9. MySQL 协议支持与 SphinxQL

5. 命令行工具参考

5.1. indexer命令参考

5.2. searchd命令参考

5.3. search命令参考

5.4. spelldump命令参考

5.5. indextool命令参考

6. API参考

6.1. 通用API方法

6.1.1. GetLastError （错误信息）

6.1.2. GetLastWarning （告警信息）

6.1.3. SetServer (设置搜索服务)

6.1.4. SetRetries (设置失败重试)

6.1.5. SetConnectTimeout （设置超时时间）

6.1.6. SetArrayResult （设置结果返回格式）

6.1.7. IsConnectError （检查链接错误）

6.2. 通用搜索设置

6.2.1. SetLimits （设置结果集偏移量）

6.2.2. SetMaxQueryTime （设置最大搜索时间）

6.2.3. SetOverride （设置临时属性值覆盖）

6.2.4. SetSelect (设置返回信息的内容)

示例：

6.3. 全文搜索设置

6.3.1. SetMatchMode （设置匹配模式）

6.3.2. SetRankingMode （设置评分模式）

6.3.3. SetSortMode （设置排序模式）

6.3.4. SetWeights （设置权重）

6.3.5. SetFieldWeights （设置字段权重）

6.3.6. SetIndexWeights （设置索引权重）

6.4. 结果集过滤设置

6.4.1. SetIDRange （设置查询ID范围）

6.4.2. SetFilter （设置属性过滤）

6.4.3. SetFilterRange （设置属性范围）

6.4.4. SetFilterFloatRange （设置浮点数范围）

示例：应用程序代码 (PHP):

`后查询（sql_post）` vs. `索引后查询（sql_post_index）`

4.8. `searchd`查询日志格式

5.1. `indexer`命令参考

5.2. `searchd`命令参考

5.3. `search`命令参考

5.4. `spelldump`命令参考

5.5. `indextool`命令参考