Sphinx Client API for Ruby

Posted by Dmytro Shteflyuk on

The Sphinx Client API is used to communicate with searchd daemon and get search results from Sphinx. It is used in large applications with a lot of data to provide fast, reliable search engine. Ruby API is a port of PHP API, which could be found inside your Sphinx distributive. Below you could find information on how to install and use it.

Warning: If you used this plugin before version 0.3.0 released, check the documentation, because I have fixed any differences between PHP and this API implementation, and all functions has been renamed.

Installation

Sphinx Client API for Ruby has been implemented as plugin for Ruby on Rails (but you able to use it in standalone Ruby application as well, there are no dependencies on other libraries). All you need is to download plugin sources and unpack them to the vendor/plugins/sphinx directory.

Documentation

You can find documentation here. Also you can build the documentation by running following command inside the vendor/plugins/sphinx directory:

1
rake rdoc

Here is short example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@sphinx = Sphinx::Client.new
@sphinx.SetSortMode(Sphinx::Client::SPH_SORT_ATTR_ASC, 'created_at')
results = @sphinx.Query('test')

puts "Searched for:"
results['words'].each do |word, info|
  puts "    #{word} found #{info['hits']} times in #{info['docs']} documents"
end
print "\nResults #{results['total']} of #{results['total_found']}; "
puts "Total time: #{results['time']}"
results['matches'].each do |doc|
  puts "Document ##{doc['id']} (weight #{doc['weight']}):"
  doc['attrs'].each do |attr, value|
    puts "    #{attr}: #{value}"
  end
end

Download

The latest version of “Sphinx Client API” is 0.3.1, and it can be downloaded here:

version0.3.1DownloadSphinx Client API

Also you can download client library for current Sphinx 0.9.8 r1112 development snapshot here: Sphinx Client API v0.4.0-r1112. WARNING, this is a current development snapshot rather than tested and approved release. Even though it is already used in production at some sites, it still has some known issues, and might have showstopper ones, too. Please use with care and do report any issues you might run into.

If you have any proposals, want to send feedback or found bugs, please post comments. It’s very important for me!

Changelog

  • v0.3.1 (Dec 9, 2007)
    • Fixed bug with search results sorting order.
  • v0.3.0 (Apr 3, 2007)
    • Fixed bug with processing attributes in query response (thanks to shawn).
    • Fixed bug query processing time round-up (thanks to michael).
    • API updated in compliance with PHP API for Sphinx 0.9.7.
    • RSpec tests added
  • v0.2.0 (Dec 20, 2006)
    • Imporved exceptions handling.
    • API updated in compliance with PHP API for Sphinx 0.9.7 RC2.
  • v0.1.0 (Nov 26, 2006)
    • Initial plugin implementation.

Other plugins

Full list of plugins I have implemented is available here.

12 Responses to this entry

Subscribe to comments with RSS or TrackBack to 'Sphinx Client API for Ruby'.

Quang
said on June 18th, 2007 at 07:08 · Permalink · Reply

Hi, I have a huge data in MySQl. Before I found Sphinx, I intend to build my old indexes and then build a tag cloud base on those indexes.
Now I wonder, can Sphinx and Client API help me in building tag cloud base on Sphinx indexes ?

Quang
said on June 18th, 2007 at 07:10 · Permalink · Reply

Sorry, in the previous comment. I mean “my own indexes”, not “my old indexes”.
My English is not good :D !

said on December 9th, 2007 at 21:33 · Permalink · Reply

[…] I have a good news: Sphinx Client API has been updated and now it supports all brand new features of the unstable Sphinx 0.9.8 development snapshot. What does it mean for you as a developer? What features you will get if you would decide to switch to the new version? I will describe most valuable improvements of the Sphinx in this article, and will show how to use them with new Sphinx Client API 0.4.0 r909. […]

said on May 20th, 2008 at 05:33 · Permalink · Reply

Wanted to let you know I used your API with some refactoring in my project. Pls see my post for more information at http://www.weebadde.com/?p=8. I am happy contribute the refactored code.

Leonid S. Pavlov
said on June 7th, 2008 at 13:52 · Permalink · Reply

Hi!

This is my port of BuildKeywords Sphinx function from sphinxapi.php. Maybe you find it interesting and include it in future versions of your plugin.

—-

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# = sphinx_ex.rb - extend Sphinx Client API by Dmytro Shteflyuk
#
# Author::    Leonid S. Pavlov <mailto:leonid.pavlov at gmail dot com>.
# Copyright:: Copyright (c) 2008 Leonid S. Pavlov
# License::   Distributes under the same terms as Ruby


module Sphinx
  class Client

    SEARCHD_COMMAND_KEYWORDS = 3
    VER_COMMAND_KEYWORDS = 0x100
   
    # Keywords generation
    #
    # Connect to searchd server, and generate keyword list for a given query.
    #
    # * <tt>query</tt> is query string
    # * <tt>index</tt> is index name (or names) to query
    # * <tt>hits</tt> is the bool flag for counting words hits in indexed documents
    #
    # Returns an array of words on success.
    # Returns false on failure.
    #
    # Usage example:
    #    sphinx.BuildKeywords('test1', '*', true)
    #
    def BuildKeywords(query, index, hits)
      assert { query.instance_of? String }
      assert { index.instance_of? String }
      assert { hits.instance_of?(TrueClass) || hits.instance_of?(FalseClass) }

      sock = self.Connect

      # build request
      request = Request.new         # v.1.0 req  
      request.put_string query      # req query
      request.put_string index      # req index
      request.put_int hits ? 1 : 0  # req hits

      # send query, get response
      len = request.to_s.length
      request = [SEARCHD_COMMAND_KEYWORDS, VER_COMMAND_KEYWORDS, len].pack('nnN') + request.to_s     # add header
      sock.send(request, 0)    
      response = GetResponse(sock, VER_COMMAND_KEYWORDS)

      # parse response
      pos = 0
      res = []
      rlen = response.length
      nwords = response[pos, 4].unpack('N*').first
      pos += 4

      for i in 0...nwords do
        len = response[pos, 4].unpack('N*').first; pos += 4
        tokenized = response[pos, len]
        pos += len;

        len = response[pos, 4].unpack('N*').first; pos += 4
        normalized = response[pos, len]
        pos += len;

        res << { 'tokenized' => tokenized, 'normalized' => normalized }

        if (hits)
          ndocs, nhits = response[pos, 8].unpack('N*N*')
          pos += 8
          res[i].merge!('docs' => ndocs, 'hits' => nhits)
        end

        if pos > rlen
          @error = 'incomplete reply'
          raise SphinxResponseError, @error
        end
      end

      return res
    end

  end
end
said on June 9th, 2008 at 14:36 · Permalink · Reply

забавый баг на стыке CodeColorer’а и Google Reader’а:

текст внутри колореровского контейнера “тянется” под следующие посты в ридере… с чего бы это?

said on November 5th, 2009 at 21:24 · Permalink · Reply

[…] ruby/rails plugin rather than trying to reinvent the wheel. I found two plugins; acts_as_sphinx and Sphinx Client API for Ruby (SCAFR). They are both very similar except acts_as_sphinx has act methods to load models from the […]

Post a comment

You can use simple HTML-formatting tags (like <a>, <strong>, <em>, <ul>, <blockquote>, and other). To format your code sample use [cc lang="php"]$a = "hello";[/cc] (allowed languages are ruby, php, yaml, html, csharp, javascript). Also you can use [cc][/cc] block and its syntax would not be highlighted.

Submit Comment