Sphnix有几种不同编程语言的searchd客户端 API的实现。在本文完成之时,我们对我们自己的PHP,Python和java实现提供官方支持。此外,也有一些针对 Perl,">Ruby和C++++的第三方免费、开源API实现。
API的参考实现是用PHP写成的,因为(我们相信)较之其他语言,Sphinx在PHP中应用最广泛。因此这份参考文档基于 PHP API的参考,而且这节中的所有的代码样例都用PHP给出。
当然,其他所有 API都提供相同的方法,也使用完全相同的网络协议。因此这份文档对他们同样适用。在方法命名习惯方面或者具体数据结构的使用上可能会有小的差别。但不同语言的API提供的功能上绝不会有差异。
5.1.通用API方法
5.1.1. GetLastError
原型: function GetLastError()
以人类可读形式返回最近的错误描述信息。如果前一次 API调用没有错误,返回空字符串。
任何其他函数(如 Query() )失败后(函数失败一般返回 false),都应该调用这个函数,它将返回错误的描述。
此函数本身并不重置对错误描述,因此如有必要,可以多次调用。
5.1.2. GetLastWarning原型: function GetLastWarning ()
Returns last warning message, as a string, in human readable format. If there were no warnings during the previous API call, empty string is returned.
以人类可读格式返回最近的警告描述信息。如果前一次 API调用没有警告,返回空字符串。
您应该调用这个函数来确认您的请求(如 Query() )是否虽然完成了但产生了警告。例如,即使几个远程代理超时了,对分布式索引的搜索查询也可能成功完成。这时会产生一个警告信息。
此函数本身不会重置警告信息,因此如有必要,可以多次调用。
5.1.3. SetServer
原型:function SetServer ( $host, $port )
设置searchd的主机名和TCP端口。此后的所有请求都使用新的主机和端口设置。默认的主机和端口分别是“localhost”和3312。
5.1.4. SetRetries
原型: function SetRetries ( $count, $delay=0 )
设置分布式搜索重试的次数和延迟时间。
对于暂时的失败,searchd对每个代理重试至多$count次。$delay是两次重试之间延迟的时间,以毫秒为单位。默认情况下,重试是禁止的。注意,这个调用不会使API本身对暂时失败进行重试,它只是让 searchd这样做。目前暂时失败包括 connect()调用的各种失败和远程代理超过最大连接数(过于繁忙)的情况。
5.1.5. SetArrayResult
原型: function SetArrayResult ( $arrayresult )
PHP专用。控制搜索结果集的返回格式(匹配项按数组返回还是按hash返回)
$arrayresult参数应为布尔型。如果$arrayresult为假(默认),匹配项以PHP hash格式返回,文档ID为键,其他信息(权重、属性)为值。如果$arrayresult为真,匹配项以普通数组返回,包括匹配项的全部信息(含文档ID)
这个调用是对 MVA属性引入分组支持时同时引入的。对 MVA分组的结果可能包含重复的文档ID。因此需要将他们按普通数组返回,因为hash对每个文档ID仅能保存一个记录。
5.2.通用搜索设置
5.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_match这个设置控制搜索过程中searchd在内存中所保持的匹配项数目。一般来说,即使设置了 max_matches为1,全部的匹配文档也都会被处理、评分、过滤和排序。但是任一时刻只有最优的N个文档会被存储在内存中,这是为了性能和内存使用方面的原因,这个设置正是控制这个N的大小。注意,max_matches在两个地方设置。针对单个查询的限制由这个API调用指定。但还有一个针对整个服务器的限制,那是由配置文件中的max_matches设置控制的。为防止滥用内存,服务器不允许单个查询的限制高于服务器的限制。
在客户端不可能收到超过max_matches个匹配项。默认的限制是1000,您应该不会遇到需要设置得更高的情况。1000个记录足够向最终用户展示了。如果您是想将结果传输给应用程序以便做进一步排序或过滤,那么请注意,在Sphinx端完成效率要高得多。
$cutoff设置是为高级性能优化而提供的。它告诉 searchd在找到并处理$cutoff个匹配后就强制停止。
5.2.2. SetMaxQueryTime
原型: function SetMaxQueryTime ( $max_query_time )
设置最大搜索时间,以毫秒为单位。参数必须是非负整数。默认值为0,意思是不做限制。
这个设置与SetLimits()中的$cutoff相似,不过这个设置限制的是查询时间,而不是处理的匹配数目。一旦处理时间已经太久,本地搜索查询会被停止。注意,如果一个搜索查询了多个本地索引,那这个限制独立地作用于这几个索引。