This document lays out the methods from the Sphinx PHP API and gives examples in their use. It is current as of Sphinx 0.9.8-r1065.
As with all PHP libraries, be sure to require the API file before use.
require('/path/to/sphinxapi.php');
Several methods need revision/clarification
SphinxClient() is the constructor method for the SphinxClient class. Its sole purpose is to instantiate the class and set default variables. There are no arguments.
$cl = new SphinxClient();
Returns last error thrown by the Sphinx API.
Returns the last warning thrown by the Sphinx API.
string host, int port
This function sets the API's searchd server location if it isn't the default of localhost:3312.
$cl->SetServer('10.1.1.4', 3312);
int offset, int limit, int max (default: 0), int cutoff (default: 0)
Much like LIMIT in a SQL query, SetLimits() returns a section of the total results. offset allows one to view records starting from the offset. limit returns n results per query. max limits the maximum results returned overall, and cutoff shears all but the last n results from your query. For example, if you return 50 results sorted by newest first with a cutoff of 5, the 5 oldest documents will be returned.
More clarification on max and cutoff could be used, especially the purpose of cutoff.
$cl->SetLimits(0, 5); // Returns the first 5 results. "page 1" $cl->SetLimits(5, 5); // Returns the next 5 results. "page 2" $cl->SetLimits(50, 25, 60); // Returns the last 10 documents. This configuration limits the search to a maximum of 60 results. $cl->SetLimits(0, 25, 60, 5); // Returns the last 5 results of all 60 results. Setting the offset here to greater than 4 will return a blank result set.
int time (Added 0.9.8-r1065)
This function sets the query timeout to the time in milliseconds.
$cl->SetMaxQueryTime(5000); // Timeout search queries after 5 seconds.
int mode
The matching mode can be set to one of six values:
These values are constants defined by the Sphinx API. You can use them anywhere after you've included in sphinxapi.php.
For explanations of the different match modes, see the matching modes.
int mode
Sets the ranking mode for weighting. Valid values are:
The default is SPH_RANK_PROXIMITY_BM25.
int mode, string sortby
The sorting mode can be one of five values:
SPH_SORT_ATTR_DESC, SPH_SORT_ATTR_ASC, SPH_SORT_TIME_SEGMENTS, and SPH_SORT_EXTENDED all use the options value.
See sorting modes for more detailed information on sorting.
// only search posts by author whose author id is 123 $cl->SetFilter('author_id', array (123)); // only search posts in sub-forums 1, 3 and 7 $cl->SetFilter('forum_id', array (1,3,7)); // sort found posts by posting date in descending order $cl->SetSortMode(SPH_SORT_ATTR_DESC, 'post_date'); // sort results first by relevance (best first), price (lowest first), and finally by the document id (greatest first). $cl->SetSortMode(SPH_SORT_EXTENDED, '@relevance DESC, price ASC, @id DESC');
array weights
As of Sphinx 0.9.8-r1065 this function is deprecated. Use SetFieldWeights() instead.
SetWeights() sets the weighting of certain columns in your sql_query by order.
sql_query = SELECT id, title, summary FROM documents
// In this example we give title a weight of 10, and summary a weight of 40. $cl->SetWeights(array(10, 40));
array weights (Added 0.9.8-r1065)
SetFieldWeights() sets the weighting of named columns in your sql_query by associative array.
sql_query = SELECT id, title, summary FROM documents
// In this example we give title a weight of 10, and summary a weight of 40. $cl->SetFieldWeights(array('title' => 10, 'summary' => 40));
array weights
SetIndexWeights() sets the weighting of separate indexes as defined in sphinx.conf when searching. The weights are set via associative array.
// Here we give the thread index a weight of 10, and post a weight of 5. $cl->SetIndexWeights(array('thread' => 10, 'post' => 5));
int min, int max
Inclusive ranged filter which only shows results which have a document id between min and max (including min and max).
Do not use this function for pagination. Use SetLimit() for that functionality.
// Search would return documents 1, 2, 6, 8, and 24. We only want documents with ids below 10. $cl->SetIDRange(1, 10);
string attribute, array values, bool exclude (default: FALSE)
SetFilter() filters returned results by the attributes defined in the indexer configuration.
Attributes are string values which list the name of the column to sort by, and values are an array of values to filter with. Exclude is a boolean value to invert matches.
You may call this function for as many filters as you need. To clear filters, see ResetFilters().
// Filter search by forumid. We need results from forum 13, 22, and 42. $cl->SetFilter('forumid', array(22, 42, 13); // Filter by a single author. $cl->SetFilter('userid', array(42)); // Show all results except from forum 49 and 50. $cl->SetFilter('forumid', array(49, 50), TRUE);
string attribute, int min, int max, bool exclude (default: FALSE)
SetFilterRange() is much like SetFilter(), except it finds values between min and max. It is inclusive of the min and max values. Setting exclude TRUE will invert the search to all values except those between min and max, including min and max.
Do not use this function for pagination. Use SetLimit() for that ability.
// Filter results to those with the categories 5 to 15. $cl->SetFilterRange('category', 5, 15); // Show results unless page hits is between 0 and 1500. Only show results with 1501 or greater hits. Equivalent to >. $cl->SetFilterRange('hits', 0, 1500, TRUE);
Tip: To allow ranged filters to completely duplicate the behavior of MySQL's >, <, >=, ⇐ comparison operators, increment and decrement the min and max values as necessary before setting the filter.
string attribute, float min, float max, bool exclude (default: FALSE) (Added 0.9.8)
SetFilterFloatRange() is identical to SetFilterRange(), only for use with floating point values.
See SetFilterRange() for usage.
string attribute_lat, string attribute_long, float lat, float long (Added 0.9.8)
This function's description needs revision and verification.
SetGeoAnchor() is required for use of @geodist in filters and sorting. Distance will be calculated from this point. attribute_lat and attribute_long refer to the column name of the latitude and longitude. lat and long must be in radians.
string attribute, int function, string groupsort (default: @group desc)
In grouping mode, all matches are assigned to different groups based on grouping function value. Each group keeps track of the total match count, and the best match (in this group) according to current sorting function. The final result set contains one best match per group, with the grouping function value and matches count attached. Groups in result set could be sorted by any sorting clause, including both document attributes and the following special internal Sphinx attributes:
The default groupsort mode is to sort by groupby function value in descending order, ie. by @group desc. total_found would contain total amount of matching groups over the whole index. See SPH_SORT_EXTENDED for more information on how to build group/attribute sorting expressions.
The grouping function can be:
WARNING: Grouping is done in fixed memory and thus its results are only approximate; so there might be more groups reported in total_found than actually present. @count might also be underestimated. For example, if sorting by relevance and grouping by “published” attribute with SPH_GROUPBY_DAY mode, then the result set will contain one most relevant match per each day when there were any matches published, with day number and per-day match count attached, and sorted by day number in descending order (ie. recent days first).
// Group reports by month $cl->SetGroupBy('date', SPH_GROUPBY_MONTH, '@group DESC');
string attribute (Added 0.9.8)
Sets a grouping attribute as count-distinct
This function needs examples/clarification
int count, int delay (Added 0.9.8)
SetRetries() is a function which sets distributed index retry count and retry delay.
Is delay in milliseconds or seconds?
(Added 0.9.8)
Clears all filters.
(Added 0.9.8)
Clears all grouping columns and modes.
string query, string index (default: *)
Query() executes a query using the given query and index. index can be blank and will by-default search all indexes. You can limit the search to certain indexes separated by anything other than letters, numbers, underscores, and dashes.
// All valid $cl->Query('test', 'main delta'); $cl->Query('test', 'main;delta'); $cl->Query('test', 'main, delta'); $cl->Query('test', 'main:delta');
The order of the indexes is important. If a document exists in two indexes (i.e. updated document in a delta index), Sphinx will use the last index listed for weight and attributes for sorting and returning to the client. In the above example, documents in the delta index will always be used over those in the main index.
This function returns FALSE on failure, and an array on success.
Query() does not return the contents of the fulltext fields of each match. It only returns integer attributes and the document ids (in order). You will have to perform additional SQL query to retrieve the documents data.
// Query Sphinx $res = $cl->Query('test', 'idx_test'); // Pass results to function for processing and retrieval GetMyMatches($res['matches']);
For more information on handling results, see Tips and Tricks, Code Snippets, and Tutorials.
string query, string index (default: *) (Added 0.9.8)
AddQuery() has the same parameters as Query(), only it adds the query to a batch which are all executed by RunQueries(). For multiple queries, this reduces network overhead and allows Sphinx to perform internal optimization, especially on group queries with the same query but different group settings.
$cl->SetGroupBy('date', SPH_GROUPBY_MONTH); $cl->AddQuery('income'); $cl->SetGroupBy('date', SPH_GROUPBY_YEAR); $cl->AddQuery('income'); $result = $cl->RunQueries();
(Added 0.9.8)
RunQueries() is used to execute a batch of queries built by AddQuery(). Returns an array with each query's resultant array.
array documents, string index, string words, array options (default: see below)
This function connects to searchd and generates an array of string excerpts from the indexes. documents is an array of strings which represent the document's contents. index specifies the index from which the settings will be used for stemming, lexing, and case folding. words contains the terms to highlight.
options is an array to change the way BuildExcerpts() highlights the specified words.
$documents = array ( "this is my test text to be highlighted, and for the sake of the testing we need to pump its length somewhat", "another test text to be highlighted, below limit", "test number three, without phrase match", "final test, not only without phrase match, but also above limit and with swapped phrase text test as well", ); $options = array ( 'before_match' => '<b>', 'after_match' => '</b>', 'chunk_separator' => ' ... ', 'limit' => 60, 'around' => 3, ); $res = $cl->BuildExcerpts($documents, 'idx_test', 'test text', $options);
Result:
[0] => this is my test text to be highlighted, and for the sake of …
[1] => another test text to be highlighted, below limit
[2] => test number three, without phrase match
[3] => … also above limit and with swapped phrase text test as well
For more, see the api/test2.php file found in the Sphinx distribution.
string index, array attributes, array values
UpdateAttributes() updates the specified index's document attributes.
attributes is an array of attribute names to update. values is an array which specifies which documents to update and the values to update to.
$index = 'main'; $attributes = array('updated', 'wordcount'); $values = array( 3 => array(1200678982, 7921), 7 => array(1200671982, 1023), ); $cl->UpdateAttributes($index, $attributes, $values);
