Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Ruby Client API for Sphinx

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


This client has been written to interface with Sphinx[]. It is written by
{Pat Allan}[], and has been influenced by both Dmytro Shteflyuk's Ruby
client and the original PHP client - credit where credit's due, after all.

It does not follow the same syntax as those two, though (not much point writing this otherwise) -
opting for a more Ruby-like structure.

The easiest way to install is to grab the gem (available since 0.9.8r1112 only):

  sudo gem install riddle

However, if you're so inclined, you can grab sourcecode via subversion. If you
are after a specific release, use the tag as follows:

  svn co riddle

Or for the most current, just use trunk:

  svn co riddle

Please note that at the time of writing, the following versions are supported (if you get the appropriate tag):

* 0.9.8-r871
* 0.9.8-r909
* 0.9.8-r985
* 0.9.8-r1065
* 0.9.8-r1112
* 0.9.8-rc1 (gem version:
* 0.9.8-rc2 (gem version:

To get started, just instantiate a Client object:

  client = # defaults to localhost and port 3312
  client = "sphinxserver.domain.tld", 3333 # custom settings
And then set the parameters to what you want, before running a query:

  client.match_mode = :extended
  client.query "Pat Allan @state Victoria"
The results from a query are similar to the other clients - but here's the details. It's a hash with
the following keys:

* :matches
* :fields
* :attributes
* :attribute_names
* :words
* :total
* :total_found
* :time
* :status
* :warning (if appropriate)
* :error (if appropriate)

The key <tt>:matches</tt> returns an array of hashes - the actual search results. Each hash has the
document id (<tt>:doc</tt>), the result weighting (<tt>:weight</tt>), and a hash of the attributes for
the document (<tt>:attributes</tt>).

The <tt>:fields</tt> and <tt>:attribute_names</tt> keys return list of fields and attributes for the
documents. The key <tt>:attributes</tt> will return a hash of attribute name and type pairs, and
<tt>:words</tt> returns a hash of hashes representing the words from the search, with the number of
documents and hits for each, along the lines of:

  results[:words]["Pat"] #=> {:docs => 12, :hits => 15}
<tt>:total</tt>, <tt>:total_found</tt> and <tt>:time</tt> return the number of matches available, the
total number of matches (which may be greater than the maximum available), and the time in milliseconds
that the query took to run.

<tt>:status</tt> is the error code for the query - and if there was a related warning, it will be under
the <tt>:warning</tt> key. Fatal errors will be described under <tt>:error</tt>.

If you've installed the gem and wondering why there's no tests - check out the svn version. I've kept the specs out of the gem as I have a decent amount of test data in there, which really isn't needed unless you want to submit patches.
Something went wrong with that request. Please try again.