Skip to content
This repository has been archived by the owner on Jun 18, 2018. It is now read-only.
/ thebes Public archive

DEPRECATED - Thebes is a thin binding layer for Rails and Sphinx with Riddle


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



22 Commits

Repository files navigation


⚠️This project is no longer maintained ⚠️

Thebes is a thin binding layer for Rails and Sphinx via Riddle and Mysql2. Thebes expects you to write Sphinx configuration files by hand and have a rich understanding of Sphinx, but provides configuration files and templates to ease the process.


To use Thebes, just add it to your Gemfile:

gem 'thebes'

# Or pin Thebes to git
# gem 'thebes',
#   :git => ''

Then use bundle install to update your Gemfile.lock. If your project is using Rails, you can take advantage of the generator to create your starting config files:

script/rails g sphinx_config

This will create the three config files that Thebes requires for easy setup:

  • sphinx.yml - Configuration values for your sphinx.conf files.
  • sphinx.conf.erb - The template for your sphinx.conf files.
  • sphinx_servers.yml - Configuration of Rails, which Sphinx servers to connect to.

Flavor to taste, and run rake thebes:build to generate your sphinx configuation.

Querying via Sphinx's custom protocol

Generate a query against Sphinx via Riddle:

result = do |a|
  # a here is an instance of Riddle::Client:

result will be an instance of Riddle::Response. Usually you will want to call .next on it to get your returned values from Sphinx. A more complex usage example:

# sphinx_res is a raw result from Riddle.
sphinx_res = do |q|
  # In Riddle, filters need to be added to a query before the
  # actual query.
  q.filters <<'active', [1])
  # Pull search terms of a query.
  query = params[:search_terms].split(' ').collect {|word|
    "( =#{word} | #{word} | #{word}* )"
  }.join(' ')
  q.append_query query, 'documents' # Search index 'documents'.

  # You can change the match_mode or alter the query in other
  # ways.
  # q.match_mode = :expr2

ids, weights = [], []
sphinx_res[0][:matches].each do |match|
  ids << match[:attributes]['_id']
  weights << match[:weight]

# Fetch documents from the database.
@documents = Document.find(ids)

# Sort documents by weight.
@documents.sort! {|a,b| weights[ids.index(] <=> weights[ids.index(] }

Additionally, you can set procs to be run before the query block or right before the query is run:

# Usually found in config/initializers/thebes.rb

# Before the block.
Thebes::Query.before_query = do |q|
  q.match_mode = :any
  q.max_matches = 10

# Just before the query is run.
Thebes::Query.before_running = do |q|

Querying via Sphinxql

Thebes has minimal support for querying Sphinx via the new Sphinxql syntax. Running a query returns a Mysql2::Result object.

# Do a search with SphinxQL.
@results = "SELECT * FROM items WHERE MATCH('Horwitz')"

@ids = @results.collect {|r| r['_id'] }

Deployment Strategy

Always check config/sphinx.conf.erb into your SCM. The config/sphinx.yml and config/sphinx_servers.yml files probably should not be checked in, and any generated config/sphinx.conf files should likely not be checked in.

Steps in a capistrano-style deployment:

  • Copy server-side config/sphinx_servers.yml and config/sphinx.yml files into place.
  • Run rake thebes:build to generate config/sphinx.conf or any other sphinx configuration files.
  • Restart searchd, run the indexer.

If you want to use a cluster of Sphinx servers, several configuration files can be generated by modifying config/sphinx.conf to generate the proper configurations. Then update config/sphinx_servers.yml to tell your running Rails app where to find any new servers.


Fork, clone, write a test, write some code, commit, push, send a pull request. Github FTW!

This project was open-sourced by Harvest. We're hiring!


DEPRECATED - Thebes is a thin binding layer for Rails and Sphinx with Riddle







No releases published


No packages published