[coreseek/sphinx学习笔记5]--通用API

[参考Coreseek 全文检索服务器 2.0 (Sphinx 0.9.8)参考手册，详情见http://www.coreseek.cn/docs/sphinx_doc_zhcn_0.9.pdf ] 

function GetLastError()
以人类可读形式返回最近的错误描述信息。如果前一次 API 调用没有错误，返回空字符串。此函数本身并不重置对错误描述，因此如有必要，可以多次调用。

function GetLastWarning ()
以人类可读格式返回最近的警告描述信息。如果前一次 API 调用没有警告，返回空字符串。此函数本身不会重置警告信息，因此如有必要，可以多次调用。

function GetLastWarning ()
以人类可读格式返回最近的警告描述信息。如果前一次 API 调用没有警告，返回空字符串。此函数本身不会重置警告信息，因此如有必要，可以多次调用。

function SetServer ( $host, $port )
设置 searchd 的主机名和 TCP 端口。此后的所有请求都使用新的主机和端口设置。默认的主机和端口分别是“localhost”和 3312。

function SetRetries ( $count, $delay=0 )
设置分布式搜索重试的次数和延迟时间。对于暂时的失败，searchd 对每个代理重试至多$count 次。$delay 是两次重试之间延迟的时间，以毫秒为单位。默认情况下，重试是禁止的

function SetArrayResult ( $arrayresult )
PHP 专用。控制搜索结果集的返回格式（匹配项按数组返回还是按 hash 返回）
$arrayresult 参数应为布尔型。如果$arrayresult 为假（默认），匹配项以 PHP hash 格式返回，文档 ID 为键，其他信息（权重、属性）为值。如果$arrayresult 为真，匹配项以普通数组返回，包括匹配项的全部信息（含文档 ID）

function SetLimits ( $offset, $limit, $max_matches=0, $cutoff=0 )
给服务器端结果集设置一个偏移量（$offset）和从那个偏移量起向客户端返回的匹配项数目限制（$limit）。并且可以在服务器端设定当前查询的结果集大小（$max_matches），另有一个阈值（$cutoff），当找到的匹配项达到这个阀值时就停止搜索。全部这些参数都必须是非负整数。
前两个参数的行为与 MySQL LIMIT 子句中参数的行为相同。偏移量($offset)和结果数限制($limit)的默认值分别是0 和 20，即返回前 20 个匹配项。
    max_match 这个设置控制搜索过程中 searchd 在内存中所保持的匹配项数目。一般来说，即使设置了 max_matches 为 1，全部的匹配文档也都会被处理、评分、过滤和排序。但还有一个针对整个服务器的限制，那是由配置文件中的 max_matches 设置控制的。为防止滥用内存，服务器不允许单个查询的限制高于服务器的限制。
    在客户端不可能收到超过 max_matches 个匹配项。默认的限制是 1000，您应该不会遇到需要设置得更高的情况。1000 个记录足够向最终用户展示了。如果您是想将结果传输给应用程序以便做进一步排序或过滤，那么请注意，在 Sphinx 端完成效率要高得多。    
    $cutoff 设置是为高级性能优化而提供的。它告诉 searchd 在找到并处理$cutoff 个匹配后就强制停止。

function SetMaxQueryTime ( $max_query_time )
设置最大搜索时间，以毫秒为单位。参数必须是非负整数。默认值为 0，意思是不做限制。
这个设置与 SetLimits()中的$cutoff 相似，不过这个设置限制的是查询时间，而不是处理的匹配数目。一旦处理时间已经太久，本地搜索查询会被停止。注意，如果一个搜索查询了多个本地索引，那这个限制独立地作用于这几个索引。

function SetMatchMode ( $mode )
设置全文查询的匹配模式，参见节 4.1 “匹配模式”中的描述。参数必须是一个与某个已知模式对应的常数。
警告：（仅 PHP）查询模式常量不能包含在引号中，那给出的是一个字符串而不是一个常量。

function SetRankingMode ( $ranker )
设置评分模式。目前只在 SPH_MATCH_EXTENDED2 这个匹配模式中提供。参数必须是与某个已知模式对应的常数。
Sphinx 默认计算两个对最终匹配权重有用的因子。主要是查询词组与文档文本的相似度。其次是称之为 BM25 的统计函数，该函数值根据关键字文档中的频率（高频导致高权重）和在整个索引中的频率（低频导致高权重）在 0 和 1 之间取值。
已经实现的模式包括：
    SPH_RANK_PROXIMITY_BM25， 默认模式，同时使用词组评分和 BM25 评分，并且将二者结合。
    SPH_RANK_BM25，统计相关度计算模式，仅使用 BM25 评分计算（与大多数全文检索引擎相同）。这个模式比较快，但是可能使包含多个词的查询的结果质量下降。
    SPH_RANK_NONE，禁用评分的模式，这是最快的模式。实际上这种模式与布尔搜索相同。所有的匹配项都被赋予权重 1。

function SetSortMode ( $mode, $sortby="" )
参数必须为与某个已知模式对应的常数。
警告：（仅 PHP）查询模式常量不能包含在引号中，那给出的是一个字符串而不是一个常量。

function SetWeights ( $weights )
按在索引中出现的先后顺序给字段设置权重。不推荐，请使用 SetFieldWeights() 。

function SetFieldWeights ( $weights )
按字段名称设置字段的权值。参数必须是一个 hash（关联数组），该 hash 将代表字段名字的字符串映射到一个整型的权值上。
    字段权重影响匹配项的评级。这个调用用于给不同的全文数据字段指定不同于默认值的权值。给定的权重必须是正的 32 位整数。最终的权重也是个 32 位的整数。默认权重为 1。未知的属性名会被忽略。目前对权重没有强制的最大限制。但您要清楚，设定过高的权值可能会导致出现 32 位整数的溢出问题。

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

function SetIDRange ( $min, $max )
设置接受的文档 ID 范围。参数必须是整数。默认是 0 和 0，意思是不限制范围。此调用执行后，只有 ID 在$min 和$max（包括$min 和$max）之间的文档会被匹配。

function SetFilter ( $attribute, $values, $exclude=false )
增加整数值过滤器。此调用在已有的过滤器列表中添加新的过滤器。
$attribute 是属性名。$values 是整数数组。$exclude 是布尔值，它控制是接受匹配的文档（默认模式，即$exclude 为假时）还是拒绝它们。只有当索引中$attribute 列的值与$values 中的任一值匹配时文档才会被匹配（或者拒绝，如果$exclude 值为真）

function SetFilterRange ( $attribute, $min, $max, $exclude=false )
添加新的整数范围过滤器。此调用在已有的过滤器列表中添加新的过滤器。
$attribute 是属性名,$min、$max 定义了一个整数闭区间，$exclude 布尔值，它控制是接受匹配的文档（默认模式，即$exclude 为假时）还是拒绝它们。
只有索引中$attribute 列的值落在$min 和$max 之间（包括$min 和$max），文档才会被匹配（或者拒绝，如果$exclude 值为真）。

function SetFilterFloatRange ( $attribute, $min, $max, $exclude=false )
增加新的浮点数范围过滤器。此调用在已有的过滤器列表中添加新的过滤器。
$attribute 是属性名,$min、$max 定义了一个浮点数闭区间，$exclude 必须是布尔值，它控制是接受匹配的文档（默认模式，即$exclude 为假时）还是拒绝它们。只有当索引中$attribute 列的值落在$min 和$max 之间（包括$min 和$max），文档才会被匹配（或者拒绝，如果$exclude 值为真）。

function SetGeoAnchor ( $attrlat, $attrlong, $lat, $long )
为地表距离计算设置锚点，并且允许使用它们。
$attrlat 和$attrlong 是字符串，分别指定了对应经度和纬度的属性名称。$lat 和$long 是浮点值，指定了锚点的经度和纬度值，以角度为单位。

function SetGroupBy ( $attribute, $func, $groupsort="@group desc" )
设置进行分组的属性、函数和组间排序模式，并启用分组
    $attribute 是字符串，为进行分组的属性名。
    $func 为常数，它指定内建函数，该函数以前面所述的分组属性的值为输入，目前的可选的值为：SPH_GROUPBY_DAY， SPH_GROUPBY_WEEK， SPH_GROUPBY_MONTH，SPH_GROUPBY_YEAR， SPH_GROUPBY_ATTR 。
    $groupsort 是控制分组如何排序的子句。其语法与节4.5, “SPH_SORT_EXTENDED模式”中描述的相似。分组与 SQL 中的 GROUP BY 子句本质上相同。此函数调用产生的

function SetGroupDistinct ( $attribute )
设置分组中需要计算不同取值数目的属性名。只在分组查询中有效。
$attribute 是包含属性名的字符串。每个组的这个属性的取值都会被储存起来（只要内存允许），其后此属性在此组中不同值的总数会被计算出来并返回给客户端。这个特性与标准SQL 中的COUNT（DISTINCT）子句类似。

function Query ( $query, $index="*" )
    连接到 searchd 服务器，根据服务器的当前设置执行给定的查询，取得并返回结果集。
    $query 是查询字串，$index 是包含一个或多个索引名的字符串。一旦发生一般错误，则返回假并设置 GetLastError()信息。若成功则返回搜索的结果集。$index 的默认值是“*”，意思是对全部本地索引做查询。索引名中允许的字符包括拉丁字母（a-z），数字（0-9），减号（-）和下划线（_），其他字符均视为分隔符。
    结果集是 hash（仅 PHP，其他语言的 API 可能使用其他数据结构），包含如下键和值：
    "matches":是一个 hash 表，存储文档 ID 以及其对应的另一个包含文档权重和属性值的 hash 表（或者是数组，如果启用了 SetArrayResult()）。
    "total":此查询在服务器检索所得的匹配文档总数（即服务器端结果集的大小）。这是在当前设置下，用当前查询可以从服务器端获得的匹配文档数目的上限。
    "total_found":（服务器上找到和处理了的）索引中匹配文档的总数。
    "words":一个 hash，它将查询关键字（关键字已经过大小写转换，取词干和其他处理）映射到一个包含关于关键字的统计数据（“docs”——在多少文档中出现，hits”——共出现了多少次）的小 hash 表上。
    "error":searchd 报告的错误信息（人类可读的字符串）。若无错误则为空字符串。
    "warning":searchd 报告的警告信息（人类可读字符串）。若无警告则为空串。

function AddQuery ( $query, $index="*" )
向批量查询增加一个查询。$query 为查询串。$index 为包含一个或多个索引名的字符串。返回 RunQueries()返回的数组中的一个下标。

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

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

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

function BuildExcerpts ( $docs, $index, $words, $opts=array() )
该函数用来产生文档片段（摘要）。连接到 searchd，要求它从指定文档中产生片段（摘要），并返回结果。
    $docs 为包含各文档内容的数组。$index 为包含索引名字的字符串。给定索引的不同设置（例如字符集、形态学、词形等方面的设置）会被使用。
    $words 为包含需要高亮的关键字的字符串。它们会按索引的设置被处理。例如，如果英语取词干stemming）在索引中被设置为允许，那么即使关键词是“shoe”，“shoes”这个词也会被高亮。
    $opts 为包含其他可选的高亮参数的 hash：
        "before_match":在匹配的关键字前面插入的字符串。默认为“<b>”
        "chunk_separator":在摘要块（段落）之间插入的字符串。默认为“...”
        "limit":摘要最多包含的符号（码点）数。整数，默认为 256
        "around":每个关键词块左右选取的词的数目。整数，默认为 5.
        "exact_phrase":是否仅高亮精确匹配的整个查询词组，而不是单独的关键词。布尔值，默认为假。
        "single_passage":是否仅抽取最佳的一个段落。布尔值，默认为否。失败时返回假。成功时返回包含有片段（摘要）字符串的数组。

function UpdateAttributes ( $index, $attrs, $values )
立即更新指定文档的指定属性值。成功则返回实际被更新的文档数目（0 或更多），失败则返回-1。
    $index 为待更新的（一个或多个）索引名。既可以是一个单独的索引名，也可以是一个索引名的列表.
    $attrs 为属性名字符串的数组，其所列的属性会被更新。
    $values 为 hash 表，$values 表的键为文档 ID，$values 表的值为新的属性值的简单数组。
    $index 既可以是一个单独的索引名，也可以是一个索引名的列表，就像 Query()的参数。索引名列表可以包含分布式索引(更新会同步到全部代理上)
    只有在 docinfo=extern 这个存储策略下才可以运行更新。更新非常快，因为操作完全在内存中进行，但它们也可以变成持久的，更新会在 searchd 干净关闭时（收到 SIGTERM 信号时）被写入磁盘.

文章来源：http://my.oschina.net/wzwitblog/blog/109999