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 ()

關閉先前打開的持久鏈接。