sphinx调用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 ()

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