Book/sphinx-Phpdoc专题

Sphinx 客户端

简介
安装／配置
预定义常量
范例
SphinxClient — SphinxClient 类
- SphinxClient::addQuery — Add query to multi-query batch
- SphinxClient::buildExcerpts — Build text snippets
- SphinxClient::buildKeywords — Extract keywords from query
- SphinxClient::close — 关闭先前打开的持久连接
- SphinxClient::__construct — Create a new SphinxClient object
- SphinxClient::escapeString — Escape special characters
- SphinxClient::getLastError — Get the last error message
- SphinxClient::getLastWarning — Get the last warning
- SphinxClient::open — 建立到搜索服务端的持久连接
- SphinxClient::query — 执行搜索查询
- SphinxClient::resetFilters — Clear all filters
- SphinxClient::resetGroupBy — Clear all group-by settings
- SphinxClient::runQueries — Run a batch of search queries
- SphinxClient::setArrayResult — 控制搜索结果集的返回格式
- SphinxClient::setConnectTimeout — Set connection timeout
- SphinxClient::setFieldWeights — Set field weights
- SphinxClient::setFilter — 增加整数值过滤器
- SphinxClient::setFilterFloatRange — Add new float range filter
- SphinxClient::setFilterRange — Add new integer range filter
- SphinxClient::setGeoAnchor — Set anchor point for a geosphere distance calculations
- SphinxClient::setGroupBy — Set grouping attribute
- SphinxClient::setGroupDistinct — Set attribute name for per-group distinct values count calculations
- SphinxClient::setIDRange — Set a range of accepted document IDs
- SphinxClient::setIndexWeights — Set per-index weights
- SphinxClient::setLimits — 设置返回结果集偏移量和数目
- SphinxClient::setMatchMode — 设置全文查询的匹配模式
- SphinxClient::setMaxQueryTime — Set maximum query time
- SphinxClient::setOverride — Sets temporary per-document attribute value overrides
- SphinxClient::setRankingMode — Set ranking mode
- SphinxClient::setRetries — Set retry count and delay
- SphinxClient::setSelect — Set select clause
- SphinxClient::setServer — 设置searchd的主机名和TCP端口
- SphinxClient::setSortMode — Set matches sorting mode
- SphinxClient::status — Queries searchd status
- SphinxClient::updateAttributes — Update document attributes

简介

SphinxClient 为 Sphinx 提供了面向对象的接口.

类摘要

SphinxClient

class SphinxClient {

/* 方法 */

public int addQuery ( string $query [, string $index = "*" [, string $comment = "" ]] )

public arrayfalse buildExcerpts ( array $docs , string $index , string $words [, array $opts ] )

public array buildKeywords ( string $query , string $index , bool $hits )

public bool close ( void )

public __construct ( void )

public string escapeString ( string $string )

public string getLastError ( void )

public string getLastWarning ( void )

public bool open ( void )

public array query ( string $query [, string $index = "*" [, string $comment = "" ]] )

public void resetFilters ( void )

public void resetGroupBy ( void )

public array runQueries ( void )

public bool setArrayResult ( bool $array_result = false )

public bool setConnectTimeout ( float $timeout )

public bool setFieldWeights ( array $weights )

public bool setFilter ( string $attribute , array $values [, bool $exclude = false ] )

public bool setFilterFloatRange ( string $attribute , float $min , float $max [, bool $exclude = false ] )

public bool setFilterRange ( string $attribute , int $min , int $max [, bool $exclude = false ] )

public bool setGeoAnchor ( string $attrlat , string $attrlong , float $latitude , float $longitude )

public bool setGroupBy ( string $attribute , int $func [, string $groupsort = "@group desc" ] )

public bool setGroupDistinct ( string $attribute )

public bool setIDRange ( int $min , int $max )

public bool setIndexWeights ( array $weights )

public bool setLimits ( int $offset , int $limit [, int $max_matches = 0 [, int $cutoff = 0 ]] )

public bool setMatchMode ( int $mode )

public bool setMaxQueryTime ( int $qtime )

public bool setOverride ( string $attribute , int $type , array $values )

public bool setRankingMode ( int $ranker )

public bool setRetries ( int $count [, int $delay = 0 ] )

public bool setSelect ( string $clause )

public bool setServer ( string $server , int $port )

public bool setSortMode ( int $mode [, string $sortby ] )

public array status ( void )

public int updateAttributes ( string $index , array $attributes , array $values [, bool $mva = false ] )

}

SphinxClient::addQuery

Add query to multi-query batch

说明

public int SphinxClient::addQuery ( string $query [, string $index = "*" [, string $comment = "" ]] )

Adds query with the current settings to multi-query batch. This method doesn't affect current settings (sorting, filtering, grouping etc.) in any way.

参数

query
Query string.

index
An index name (or names).

comment

返回值

Returns an index in an array of results that will be returned by call or false on error.

参见

SphinxClient::buildExcerpts

Build text snippets

说明

public arrayfalse SphinxClient::buildExcerpts ( array $docs , string $index , string $words [, array $opts ] )

Connects to searchd, requests it to generate excerpts (snippets) from the given documents, and returns the results.

参数

docs
Array of strings with documents' contents.

index
Index name.

words
Keywords to highlight.

opts
Associative array of additional highlighting options (see below).

Option	Description
"before_match"	A string to insert before a keyword match. Default is "\<b>".
"after_match"	A string to insert after a keyword match. Default is "\</b>".
"chunk_separator"	A string to insert between snippet chunks (passages). Default is " ... ".
"limit"	Maximum snippet size, in symbols (codepoints). Integer, default is 256.
"around"	How much words to pick around each matching keywords block. Integer, default is 5.
"exact_phrase"	Whether to highlight exact query phrase matches only instead of individual keywords. Boolean, default is `false`.
"single_passage"	Whether to extract single best passage only. Boolean, default is `false`.

返回值

Returns array of snippets on success 或者在失败时返回 false.

SphinxClient::buildKeywords

Extract keywords from query

说明

public array SphinxClient::buildKeywords ( string $query , string $index , bool $hits )

Extracts keywords from query using tokenizer settings for the given index, optionally with per-keyword occurrence statistics.

参数

query
A query to extract keywords from.

index
An index to get tokenizing settings and keyword occurrence statistics from.

hits
A boolean flag to enable/disable keyword statistics generation.

返回值

Returns an array of associative arrays with per-keyword information.

SphinxClient::close

关闭先前打开的持久连接

说明

public bool SphinxClient::close ( void )

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

参数

此函数没有参数。

更新日志

PECL/sphinx 版本	说明
1.0.3	新增函数 SphinxClient::close(), 仅在编译时使用 libsphinxclient >= 0.9.9 有效.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::__construct

Create a new SphinxClient object

说明

public SphinxClient::__construct ( void )

Creates a new SphinxClient object.

参数

此函数没有参数。

SphinxClient::escapeString

Escape special characters

说明

public string SphinxClient::escapeString ( string $string )

Escapes characters that are treated as special operators by the query language parser.

参数

string
String to escape.

返回值

Returns escaped string.

SphinxClient::getLastError

Get the last error message

说明

public string SphinxClient::getLastError ( void )

Returns string with the last error message. If there were no errors during the previous API call, empty string is returned. This method doesn't reset the error message, so you can safely call it several times.

参数

此函数没有参数。

返回值

Returns the last error message or an empty string if there were no errors.

参见

SphinxClient::getLastWarning

Get the last warning

说明

public string SphinxClient::getLastWarning ( void )

Returns last warning message. If there were no warnings during the previous API call, empty string is returned. This method doesn't reset the warning, so you can safely call it several times.

参数

此函数没有参数。

返回值

Returns the last warning message or an empty string if there were no warnings.

参见

SphinxClient::open

建立到搜索服务端的持久连接

说明

public bool SphinxClient::open ( void )

建立到搜索服务端的持久连接.

参数

此函数没有参数。

更新日志

PECL/sphinx 版本	说明
1.0.3	新增函数 SphinxClient::open(), 仅在编译时使用 libsphinxclient >= 0.9.9 有效.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::query

执行搜索查询

说明

public array SphinxClient::query ( string $query [, string $index = "*" [, string $comment = "" ]] )

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

参数

query
查询字符串.

index
索引名称 (可以为多个，使用逗号分割，或者为“*”表示全部索引).

comment
发送到searchd的查询日志的注释内容

返回值

如果搜索成功, SphinxClient::query 返回的结果集列表包含找到的全部匹配项中的一部分，以及与查询相关的统计数据. 结果集是哈希结构，包含如下键和值:

键	值说明
"matches"	存储文档ID以及其对应的另一个包含文档权重和属性值的hash表
"total"	此查询在服务器检索所得的匹配文档总数（即服务器端结果集的大小，且与相关设置有关）
"total_found"	（服务器上找到和处理了的）索引中匹配文档的总数
"words"	将查询关键字（关键字已经过大小写转换，取词干和其他处理）映射到一个包含关于关键字的统计数据（“docs”——在多少文档中出现，“hits”——共出现了多少次）的小hash表上。
"error"	searchd报告的错误信息
"warning"	searchd报告的警告信息

参见

SphinxClient::resetFilters

Clear all filters

说明

public void SphinxClient::resetFilters ( void )

Clears all currently set filters. This call is normally required when using multi-queries. You might want to set different filters for different queries in the batch. To do that, you should call SphinxClient::resetFilters and add new filters using the respective calls.

返回值

没有返回值。

参见

SphinxClient::resetGroupBy

Clear all group-by settings

说明

public void SphinxClient::resetGroupBy ( void )

Clears all currently group-by settings, and disables group-by. This call is normally required only when using multi-queries.

返回值

没有返回值。

参见

SphinxClient::runQueries

Run a batch of search queries

说明

public array SphinxClient::runQueries ( void )

Connects to searchd, runs a batch of all queries added using , obtains and returns the result sets.

返回值

Returns false on failure and array of result sets on success.

参见

SphinxClient::setArrayResult

控制搜索结果集的返回格式

说明

public bool SphinxClient::setArrayResult ( bool $array_result = false )

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

参数

array_result
如果 array_result 设置为 false, 匹配项以PHP hash格式返回，文档ID为键，其他信息（权重、属性）为值。如果 array_result 设置为 true, 匹配项以普通数组返回，包括匹配项的全部信息（含文档ID）.

返回值

总是返回 true.

SphinxClient::setConnectTimeout

Set connection timeout

说明

public bool SphinxClient::setConnectTimeout ( float $timeout )

Sets connection timeout (in seconds) for searchd connection.

参数

timeout
Timeout in seconds.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::setFieldWeights

Set field weights

说明

public bool SphinxClient::setFieldWeights ( array $weights )

Binds per-field weights by name.

Match ranking can be affected by per-field weights. See » Sphinx documentation for an explanation on how phrase proximity ranking is affected. This call lets you specify non-default weights for full-text fields.

The weights must be positive 32-bit integers, so be careful not to hit 32-bit integer maximum. The final weight is a 32-bit integer too. Default weight value is 1. Unknown field names are silently ignored.

参数

weights
Associative array of field names and field weights.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::setFilter

增加整数值过滤器

说明

public bool SphinxClient::setFilter ( string $attribute , array $values [, bool $exclude = false ] )

在已有的过滤器列表中添加新的过滤器.

参数

attribute
属性名称.

values
整数值数组.

exclude
如果设置为 true, 则匹配该过滤规则的文档会被排除在结果之外.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::setFilterFloatRange

Add new float range filter

说明

public bool SphinxClient::setFilterFloatRange ( string $attribute , float $min , float $max [, bool $exclude = false ] )

Adds new float range filter to the existing list of filters. Only those documents which have attribute value stored in the index between min and max (including values that are exactly equal to min or max) will be matched (or rejected, if exclude is true).

参数

attribute
An attribute name.

min
Minimum value.

max
Maximum value.

exclude
If set to true, matching documents are excluded from the result set.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::setFilterRange

Add new integer range filter

说明

public bool SphinxClient::setFilterRange ( string $attribute , int $min , int $max [, bool $exclude = false ] )

Adds new integer range filter to the existing list of filters. Only those documents which have attribute value stored in the index between min and max (including values that are exactly equal to min or max) will be matched (or rejected, if exclude is true).

参数

attribute
An attribute name.

min
Minimum value.

max
Maximum value.

exclude
If set to true, matching documents are excluded from the result set.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::setGeoAnchor

Set anchor point for a geosphere distance calculations

说明

public bool SphinxClient::setGeoAnchor ( string $attrlat , string $attrlong , float $latitude , float $longitude )

Sets anchor point for a geosphere distance (geodistance) calculations and enables them.

Once an anchor point is set, you can use magic "@geodist" attribute name in your filters and/or sorting expressions.

参数

attrlat
Name of a latitude attribute.

attrlong
Name of a longitude attribute.

latitude
Anchor latitude in radians.

longitude
Anchor longitude in radians.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::setGroupBy

Set grouping attribute

说明

public bool SphinxClient::setGroupBy ( string $attribute , int $func [, string $groupsort = "@group desc" ] )

Sets grouping attribute, function, and group sorting mode, and enables grouping.

Grouping feature is very similar to GROUP BY clause in SQL. Results produced by this function call are going to be the same as produced by the following pseudo code: SELECT ... GROUP BY $func($attribute) ORDER BY $groupsort.

参数

attribute
A string containing group-by attribute name.

func
Constant, which sets a function applied to the attribute value in order to compute group-by key.

groupsort
An optional clause controlling how the groups are sorted.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::setGroupDistinct

Set attribute name for per-group distinct values count calculations

说明

public bool SphinxClient::setGroupDistinct ( string $attribute )

Sets attribute name for per-group distinct values count calculations. Only available for grouping queries. For each group, all values of attribute will be stored, then the amount of distinct values will be calculated and returned to the client. This feature is similar to COUNT(DISTINCT) clause in SQL.

参数

attribute
A string containing group-by attribute name.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::setIDRange

Set a range of accepted document IDs

说明

public bool SphinxClient::setIDRange ( int $min , int $max )

Sets an accepted range of document IDs. Default range is from 0 to 0, i.e. no limit. Only those records that have document ID between min and max (including IDs exactly equal to min or max) will be matched.

参数

min
Minimum ID value.

max
Maximum ID value.

返回值

成功时返回 true，或者在失败时返回 false。

SphinxClient::setIndexWeights

Set per-index weights

说明

public bool SphinxClient::setIndexWeights ( array $weights )

Sets per-index weights and enables weighted summing of match weights across different indexes.

参数

weights
An associative array mapping string index names to integer weights. Default is empty array, i.e. weighting summing is disabled.

返回值

成功时返回 true，或者在失败时返回 false。

SphinxClient::setLimits

设置返回结果集偏移量和数目

说明

public bool SphinxClient::setLimits ( int $offset , int $limit [, int $max_matches = 0 [, int $cutoff = 0 ]] )

给服务器端结果集设置一个偏移量 offset 从那个偏移量起向客户端返回的匹配项数目限制(limit) . 并且可以在服务器端设定当前查询的结果集大小 (max_matches) ，另有一个阈值 (cutoff)，当找到的匹配项达到这个阀值时就停止搜索。

参数

offset
结果集的偏移量.

limit
返回的匹配项数目.

max_matches
设置控制搜索过程中searchd在内存中所保持的匹配项数目.

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

返回值

成功时返回 true，或者在失败时返回 false。

SphinxClient::setMatchMode

设置全文查询的匹配模式

说明

public bool SphinxClient::setMatchMode ( int $mode )

设置全文查询的匹配模式. mode 是以下列出的常量之一.

Constant	Description
SPH_MATCH_ALL	匹配所有查询词（默认模式）.
SPH_MATCH_ANY	匹配查询词中的任意一个.
SPH_MATCH_PHRASE	将整个查询看作一个词组，要求按顺序完整匹配.
SPH_MATCH_BOOLEAN	将查询看作一个布尔表达式.
SPH_MATCH_EXTENDED	将查询看作一个Sphinx内部查询语言的表达式.
SPH_MATCH_FULLSCAN	使用完全扫描，忽略查询词汇.
SPH_MATCH_EXTENDED2	类似 `SPH_MATCH_EXTENDED` ，并支持评分和权重.

参数

mode
匹配模式.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::setMaxQueryTime

Set maximum query time

说明

public bool SphinxClient::setMaxQueryTime ( int $qtime )

Sets maximum search query time.

参数

qtime
Maximum query time, in milliseconds. It must be a non-negative integer. Default value is 0, i.e. no limit.

返回值

成功时返回 true，或者在失败时返回 false。

SphinxClient::setOverride

Sets temporary per-document attribute value overrides

说明

public bool SphinxClient::setOverride ( string $attribute , int $type , array $values )

Sets temporary (per-query) per-document attribute value overrides. Override feature lets you "temporary" update attribute values for some documents within a single query, leaving all other queries unaffected. This might be useful for personalized data

参数

attribute
An attribute name.

type
An attribute type. Only supports scalar attributes.

values
Array of attribute values that maps document IDs to overridden attribute values.

更新日志

PECL/sphinx 版本	说明
PECL sphinx 1.0.3	Added SphinxClient::setOverride(), available only if compiled with libsphinxclient >= 0.9.9.

返回值

成功时返回 true，或者在失败时返回 false。

SphinxClient::setRankingMode

Set ranking mode

说明

public bool SphinxClient::setRankingMode ( int $ranker )

Sets ranking mode. Only available in SPH_MATCH_EXTENDED2 matching mode.

Constant	Description
SPH_RANK_PROXIMITY_BM25	Default ranking mode which uses both proximity and BM25 ranking.
SPH_RANK_BM25	Statistical ranking mode which uses BM25 ranking only (similar to most of other full-text engines). This mode is faster, but may result in worse quality on queries which contain more than 1 keyword.
SPH_RANK_NONE	Disables ranking. This mode is the fastest. It is essentially equivalent to boolean searching, a weight of 1 is assigned to all matches.

参数

ranker
Ranking mode.

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::setRetries

Set retry count and delay

说明

public bool SphinxClient::setRetries ( int $count [, int $delay = 0 ] )

Sets distributed retry count and delay.

On temporary failures searchd will attempt up to count retries per agent. delay is the delay between the retries, in milliseconds. Retries are disabled by default. Note that this call will not make the API itself retry on temporary failure; it only tells searchd to do so.

参数

count
Number of retries.

delay
Delay between retries, in milliseconds.

返回值

成功时返回 true，或者在失败时返回 false。

SphinxClient::setSelect

Set select clause

说明

public bool SphinxClient::setSelect ( string $clause )

Sets the select clause, listing specific attributes to fetch, and expressions to compute and fetch.

参数

clause
SQL-like clause.

更新日志

PECL/sphinx 版本	说明
PECL sphinx 1.0.1	Added SphinxClient::setSelect(), available only if compiled with libsphinxclient >= 0.9.9.

返回值

成功时返回 true，或者在失败时返回 false。

SphinxClient::setServer

设置searchd的主机名和TCP端口

说明

public bool SphinxClient::setServer ( string $server , int $port )

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

参数

server
IP 或者主机名.

port
端口.

返回值

成功时返回 true，或者在失败时返回 false。

SphinxClient::setSortMode

Set matches sorting mode

说明

public bool SphinxClient::setSortMode ( int $mode [, string $sortby ] )

Sets matches sorting mode. See available modes below.

Constant	Description
SPH_SORT_RELEVANCE	Sort by relevance in descending order (best matches first).
SPH_SORT_ATTR_DESC	Sort by an attribute in descending order (bigger attribute values first).
SPH_SORT_ATTR_ASC	Sort by an attribute in ascending order (smaller attribute values first).
SPH_SORT_TIME_SEGMENTS	Sort by time segments (last hour/day/week/month) in descending order, and then by relevance in descending order.
SPH_SORT_EXTENDED	Sort by SQL-like combination of columns in ASC/DESC order.
SPH_SORT_EXPR	Sort by an arithmetic expression.

参数

mode
Sorting mode.

sortby

返回值

成功时返回 true，或者在失败时返回 false。

参见

SphinxClient::status

Queries searchd status

说明

public array SphinxClient::status ( void )

Queries searchd status, and returns an array of status variable name and value pairs.

参数

此函数没有参数。

更新日志

PECL/sphinx 版本	说明
PECL sphinx 1.0.3	Added SphinxClient::status(), available only if compiled with libsphinxclient >= 0.9.9.

返回值

Returns an associative array of search server statistics 或者在失败时返回 false.

SphinxClient::updateAttributes

Update document attributes

说明

public int SphinxClient::updateAttributes ( string $index , array $attributes , array $values [, bool $mva = false ] )

Instantly updates given attribute values in given documents.

参数

index
Name of the index (or indexes) to be updated.

attributes
Array of attribute names, listing attributes that are updated.

values
Associative array containing document IDs as keys and array of attribute values as values.

返回值

Returns number of actually updated documents (0 or more) on success, or false on failure.