Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



A Ruby wrapper for pure C searchd client API library. This is *highly experimental* library so use it at your own risk.

Installing the rlibsphinxclient gem

This gem can be more difficult to install than the typical Ruby extension. First you have to install Sphinx and Sphinx pure C searchd client API library.

Step 1: Install pure C Sphinx client API

Go to and download the latest stable release. Then go to api/libsphinxclient directory and install client API to your preferred folder (I like /opt/sphinx):

cd api/libsphinxclient
./configure --prefix=/opt/sphinx
sudo make install

On Max OS X you may get the following error:

configure: error: C++ preprocessor "/lib/cpp" fails sanity check

In this case you should specify environment variable for ./configure script:

CXXCPP="gcc -E" ./configure --prefix=/opt/sphinx

Step 2: Install rlibsphinxclient gem

If you have installed the Sphinx to /opt/sphinx, just run:

sudo gem install kpumuk-rlibsphinxclient --no-ri --no-rdoc

Otherwise, specify where sphinx has been installed to:

sudo gem install kpumuk-rlibsphinxclient --no-ri --no-rdoc -- --with-libsphinxclient-dir=/opt/sphinx-0.9.9

On Mac OS X with MacPorts you should specify ARCHFLAGS environment variable:

sudo env ARCHFLAGS="-arch i386" gem install kpumuk-rlibsphinxclient --no-rdoc --no-ri -- --with-libsphinxclient-dir=/opt/sphinx-0.9.9

If you are working on Ruby on Rails application, you can add gem dependency to your config/environment.rb:

config.gem 'kpumuk-rlibsphinxclient', :lib => 'sphinx'

Also don't forget to remove the sphinx plugin, because it's functionality is completely covered by this gem.

Using the rlibsphinxclient gem

The gem includes two versions of the client API: pure Ruby and wrapper for pure C client API. They are 100% equivalent in use, so you can switch to any of them. To use pure Ruby client, instantiate the Sphinx::Client, for pure C wrapper use Sphinx::FastClient.

Important note: you should call destroy method when you do not need client API any more. The reason for that is the C wrapper saves all query results in memory, and frees them in the destroy method call. You can omit this call in pure Ruby library, but I'd like to do call in any case just for consistence (to be able to switch to another client).

Important note #2: to ensure that destroy method will be called, use ensure block:

  @sphinx =

Examples of usage

Ok, let's take a look at the examples. First, here is the search example with all possible filters and options set:

require 'sphinx'
@sphinx =
@sphinx.SetServer('localhost', 3312)
@sphinx.SetLimits(1, 100, 20, 30)
@sphinx.SetFieldWeights('group_id' => 10, 'rating' => 20)
@sphinx.SetIndexWeights('test1' => 20, 'test2' => 30)
@sphinx.SetIDRange(1, 100)
@sphinx.SetFilter('group_id', [1], true)
@sphinx.SetFilterRange('group_id', 1, 2, true)
@sphinx.SetFilterFloatRange('rating', 1, 3, true)
@sphinx.SetGroupBy('created_at', Sphinx::Client::SPH_GROUPBY_DAY)
@sphinx.SetRetries(5, 10)
results = @sphinx.Query('test')

BuildKeywords example:

require 'sphinx'
@sphinx =
results = @sphinx.BuildKeywords('wifi gprs', 'test1', true)

BuildExcerpts example:

require 'sphinx'
@sphinx =
results = @sphinx.BuildExcerpts(['what the world', 'London is the capital of Great Britain'], 'test1', 'the')

UpdateAttributes example:

require 'sphinx'
@sphinx =
results = @sphinx.UpdateAttributes('test1', ['group_id'], { 2 => [1] })


The reason to write this gem was to investigate why we keep getting timeout errors when using Sphinx (occur rarely, but they are annoying me.) But the side effect of this library was the slight search performance improvement: Ruby library is slower when generating Sphinx request and parsing its results.

require 'sphinx'
require 'benchmark'

def run_test(klass)
  sphinx =
  sphinx.Query('test hello')
end do |x|'pure ruby') { 1000.times { run_test(Sphinx::Client) } }'c wrapper') { 1000.times { run_test(Sphinx::FastClient) } }

On my MBP I got the following results:

           user       system     total    real
pure ruby  0.420000   0.230000   0.650000 ( 14.721659)
c wrapper  0.060000   0.090000   0.150000 (  2.248645)

Who are the authors?

This plugin has been created in for our internal use and then the sources were opened for other people to use. All the code in this package has been developed by Dmytro Shteflyuk for and is released under the MIT license. For more details, see MIT-LICENSE file.


A Ruby wrapper for pure C searchd client API library (HIGHLY EXPERIMENTAL).




No packages published
You can’t perform that action at this time.