The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


Sphinx::Search - Sphinx search engine API Perl client


Please note that you *MUST* install a version which is compatible with your version of Sphinx.

This version is 0.12

Use version 0.12 for Sphinx 0.9.8 and later

Use version 0.11 for Sphinx 0.9.8-rc1 and later

Use version 0.10 for Sphinx 0.9.8-svn-r1112

Use version 0.09 for Sphinx 0.9.8-svn-r985

Use version 0.08 for Sphinx 0.9.8-svn-r871

Use version 0.06 for Sphinx 0.9.8-svn-r820

Use version 0.05 for Sphinx 0.9.8-cvs-20070907

Use version 0.02 for Sphinx 0.9.8-cvs-20070818


    use Sphinx::Search;

    $sphinx = Sphinx::Search->new();

    $results = $sphinx->SetMatchMode(SPH_MATCH_ALL)
                      ->Query("search terms");


This is the Perl API client for the Sphinx open-source SQL full-text indexing search engine,



    $sph = Sphinx::Search->new;
    $sph = Sphinx::Search->new(\%options);

Create a new Sphinx::Search instance.



Specify an optional logger instance. This can be any class that provides error, warn, info, and debug methods (e.g. see Log::Log4perl). Logging is disabled if no logger instance is provided.


Debug flag. If set (and a logger instance is specified), debugging messages will be generated.



    $error = $sph->GetLastError;

Get last error message (string)


    $warning = $sph->GetLastWarning;

Get last warning message (string)


    $sph->SetServer($host, $port);

Set the host (string) and port (integer) details for the searchd server. Returns $sph.



Set server connection timeout (in seconds).

Returns $sph.


    $sph->SetLimits($offset, $limit);
    $sph->SetLimits($offset, $limit, $max);

Set match offset/limits, and optionally the max number of matches to return.

Returns $sph.



Set maximum query time, in milliseconds, per index.

The value may not be negative; 0 means "do not limit".

Returns $sph.



Set match mode, which may be one of:


    Match all words


    Match any words


    Exact phrase match


    Boolean match, using AND (&), OR (|), NOT (!,-) and parenthetic grouping.


    Extended match, which includes the Boolean syntax plus field, phrase and proximity operators.

Returns $sph.



Set ranking mode, which may be one of:


    Default mode, phrase proximity major factor and BM25 minor one


    Statistical mode, BM25 ranking only (faster but worse quality)


    No ranking, all matches get a weight of 1


    Simple word-count weighting, rank is a weighted sum of per-field keyword occurence counts

Returns $sph.


    $sph->SetSortMode($mode, $sortby);

Set sort mode, which may be any of:

SPH_SORT_RELEVANCE - sort by relevance

Sort by attribute descending/ascending. $sortby specifies the sorting attribute.


Sort by time segments (last hour/day/week/month) in descending order, and then by relevance in descending order. $sortby specifies the time attribute.


Sort by SQL-like syntax. $sortby is the sorting specification.


Returns $sph.


    $sph->SetWeights([ 1, 2, 3, 4]);

This method is deprecated. Use SetFieldWeights instead.

Set per-field (integer) weights. The ordering of the weights correspond to the ordering of fields as indexed.

Returns $sph.



Set per-field (integer) weights by field name. The weights hash provides field name to weight mappings.

Takes precedence over SetWeights.

Unknown names will be silently ignored. Missing fields will be given a weight of 1.

Returns $sph.



Set per-index (integer) weights. The weights hash is a mapping of index name to integer weight.

Returns $sph.


    $sph->SetIDRange($min, $max);

Set IDs range only match those records where document ID is between $min and $max (including $min and $max)

Returns $sph.


    $sph->SetFilter($attr, \@values);
    $sph->SetFilter($attr, \@values, $exclude);

Sets the results to be filtered on the given attribute. Only results which have attributes matching the given (numeric) values will be returned.

This may be called multiple times with different attributes to select on multiple attributes.

If 'exclude' is set, excludes results that match the filter.

Returns $sph.


    $sph->SetFilterRange($attr, $min, $max);
    $sph->SetFilterRange($attr, $min, $max, $exclude);

Sets the results to be filtered on a range of values for the given attribute. Only those records where $attr column value is between $min and $max (including $min and $max) will be returned.

$min and $max must be integers. Use SetFilterFloatRange for floating point values.

If 'exclude' is set, excludes results that fall within the given range.

Returns $sph.


    $sph->SetFilterFloatRange($attr, $min, $max, $exclude);

Same as SetFilterRange, but allows floating point values.

Returns $sph.


    $sph->SetGeoAnchor($attrlat, $attrlong, $lat, $long);

Setup anchor point for using geosphere distance calculations in filters and sorting. Distance will be computed with respect to this point

$attrlat is the name of latitude attribute
$attrlong is the name of longitude attribute
$lat is anchor point latitude, in radians
$long is anchor point longitude, in radians

Returns $sph.


    $sph->SetGroupBy($attr, $func);
    $sph->SetGroupBy($attr, $func, $groupsort);

Sets attribute and function of results grouping.

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 grouping function value and matches count attached.

$attr is any valid attribute. Use ResetGroupBy to disable grouping.

$func is one of:


    Group by day (assumes timestamp type attribute of form YYYYMMDD)


    Group by week (assumes timestamp type attribute of form YYYYNNN)


    Group by month (assumes timestamp type attribute of form YYYYMM)


    Group by year (assumes timestamp type attribute of form YYYY)


    Group by attribute value


    Group by two attributes, being the given attribute and the attribute that immediately follows it in the sequence of indexed attributes. The specified attribute may therefore not be the last of the indexed attributes.

Groups in the set of results can be sorted by any SQL-like sorting clause, including both document attributes and the following special internal Sphinx attributes:

@id - document ID;
@weight, @rank, @relevance - match weight;
@group - group by function value;
@count - number of matches in group.

The default mode is to sort by groupby value in descending order, ie. by "@group desc".

In the results set, "total_found" contains the total amount of matching groups over the whole index.

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 a "published" attribute with SPH_GROUPBY_DAY function, then the result set will contain only the most relevant match for 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).



Set count-distinct attribute for group-by queries


    $sph->SetRetries($count, $delay);

Set distributed retries count and delay



Clear all filters.



Clear all group-by settings (for multi-queries)


    $results = $sph->Query($query, $index);

Connect to searchd server and run given search query.

query is query string
index is index name to query, default is "*" which means to query all indexes. Use a space or comma separated list to search multiple indexes.

Returns undef on failure

Returns hash which has the following keys on success:


Array containing hashes with found documents ( "doc", "weight", "group", "stamp" )


Total amount of matches retrieved (upto SPH_MAX_MATCHES, see sphinx.h)


Total amount of matching documents in index


Search time


Hash which maps query terms (stemmed!) to ( "docs", "hits" ) hash

Returns the results array on success, undef on error.


   $sph->AddQuery($query, $index);

Add a query to a batch request.

Batch queries enable searchd to perform internal optimizations, if possible; and reduce network connection overheads in all cases.

For instance, running exactly the same query with different groupby settings will enable searched to perform expensive full-text search and ranking operation only once, but compute multiple groupby results from its output.

Parameters are exactly the same as in Query() call.

Returns corresponding index to the results array returned by RunQueries() call.



Run batch of queries, as added by AddQuery.

Returns undef on network IO failure.

Returns an array of result sets on success.

Each result set in the returned array is a hash which contains the same keys as the hash returned by Query, plus:

  • error

    Errors, if any, for this query.

  • warnings

    Any warnings associated with the query.


    $excerpts = $sph->BuildExcerpts($docs, $index, $words, $opts)

Generate document excerpts for the specified documents.


An array reference of strings which represent the document contents


A string specifiying the index whose settings will be used for stemming, lexing and case folding


A string which contains the words to highlight


A hash which contains additional optional highlighting parameters:

before_match - a string to insert before a set of matching words, default is "<b>"
after_match - a string to insert after a set of matching words, default is "<b>"
chunk_separator - a string to insert between excerpts chunks, default is " ... "
limit - max excerpt size in symbols (codepoints), default is 256
around - how many words to highlight around each match, default is 5
exact_phrase - whether to highlight exact phrase matches only, default is false
single_passage - whether to extract single best passage only, default is false

Returns undef on failure.

Returns an array of string excerpts on success.


    $results = $sph->BuildKeywords($query, $index, $hits)

Generate keyword list for a given query Returns undef on failure, Returns an array of hashes, where each hash describes a word in the query with the following keys:

  • tokenized

    Tokenised term from query

  • normalized

    Normalised term from query

  • docs

    Number of docs in which word was found (if $hits is true)

  • hits

    Number of occurrences of word (if $hits is true)


    $escaped = $sph->EscapeString('abcde!@#$%')

Inserts backslash before all non-word characters in the given string.


    $sph->UpdateAttributes($index, \@attrs, \%values);

Update specified attributes on specified documents


Name of the index to be updated


Array of attribute name strings


A hash with key as document id, value as an array of new attribute values

Returns number of actually updated documents (0 or more) on success

Returns undef on failure

Usage example:

 $sph->UpdateAttributes("test1", [ qw/group_id/ ], { 1 => [ 456] }) );



There is a bundled in the contrib area of the Sphinx source distribution, which was used as the starting point of Sphinx::Search. Maintenance of that version appears to have lapsed at sphinx-0.9.7, so many of the newer API calls are not available there. Sphinx::Search is mostly compatible with the old except:

On failure, Sphinx::Search returns undef rather than 0 or -1.
Sphinx::Search 'Set' functions are cascadable, e.g. you can do Sphinx::Search->new ->SetMatchMode(SPH_MATCH_ALL) ->SetSortMode(SPH_SORT_RELEVANCE) ->Query("search terms")

Sphinx::Search also provides documentation and unit tests, which were the main motivations for branching from the earlier work.


Jon Schutz


Please report any bugs or feature requests to bug-sphinx-search at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc Sphinx::Search

You can also look for information at:


This module is based on (not deployed to CPAN) for Sphinx version 0.9.7-rc1, by Len Kranendonk, which was in turn based on the Sphinx PHP API.


Copyright 2007 Jon Schutz, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License.