oedipus 0.0.1.pre1 → 0.0.1.pre2

data/lib/oedipus/index.rb

@@ -11,7 +11,6 @@ module Oedipus
   # Representation of a search index for querying.
   class Index
     attr_reader :name
-    attr_reader :attributes
 
     # Initialize the index named +name+ on the connection +conn+.
     #
@@ -21,16 +20,15 @@ module Oedipus
     # @param [Connection] conn
     #   an instance of Oedipus::Connection for querying
     def initialize(name, conn)
-      @name       = name.to_sym
-      @conn       = conn
-      @attributes = reflect_attributes
-      @builder    = QueryBuilder.new(name, conn)
+      @name    = name.to_sym
+      @conn    = conn
+      @builder = QueryBuilder.new(name)
     end
 
     # Insert the record with the ID +id+.
     #
     # @example
-    #   index.insert(42, :title => "example", :views => 22)
+    #   index.insert(42, title: "example", views: 22)
     #
     # @param [Integer] id
     #   the unique ID of the document in the index
@@ -38,66 +36,211 @@ module Oedipus
     # @param [Hash] hash
     #   a symbol-keyed hash of data to insert
     #
-    # @return [Hash]
-    #   a copy of the inserted record
+    # @return [Fixnum]
+    #   the number of rows inserted (currently always 1)
     def insert(id, hash)
-      data = Hash[
-        [:id, *hash.keys.map(&:to_sym)].zip \
-        [id,  *hash.values.map { |v| String === v ? @conn.quote(v) : v }]
-      ]
-      @conn.execute("INSERT INTO #{name} (#{data.keys.join(', ')}) VALUES (#{data.values.join(', ')})")
-      attributes.merge(data.select { |k, _| attributes.key?(k) })
+      @conn.execute(@builder.insert(id, hash))
+    end
+
+    # Update the record with the ID +id+.
+    #
+    # @example
+    #   index.update(42, views: 25)
+    #
+    # @param [Integer] id
+    #   the unique ID of the document in the index
+    #
+    # @param [Hash] hash
+    #   a symbol-keyed hash of data to set
+    #
+    # @return [Fixnum]
+    #   the number of rows updated (1 or 0)
+    def update(id, hash)
+      @conn.execute(@builder.update(id, hash))
     end
 
+    # Completely replace the record with the ID +id+.
+    #
+    # @example
+    #   index.replace(42, title: "New title", views: 25)
+    #
+    # @param [Integer] id
+    #   the unique ID of the document in the index
+    #
+    # @param [Hash] hash
+    #   a symbol-keyed hash of data to insert
+    #
+    # @return [Fixnum]
+    #   the number of rows inserted (currentl always 1)
+    def replace(id, hash)
+      @conn.execute(@builder.replace(id, hash))
+    end
+
+    # Fetch a single document by its ID.
+    #
+    # Returns the Hash of attributes if found, otherwise nil.
+    #
+    # @param [Fixnum] id
+    #   the ID of the document
+    #
+    # @return [Hash]
+    #   the attributes of the record
+    def fetch(id)
+      search(id: id)[:records].first
+    end
+
+    # Perform a search on the index.
+    #
+    # Either one or two arguments may be passed, with either one being mutually
+    # optional.
+    #
+    # @example Fulltext search
+    #   index.search("cats AND dogs")
+    #
+    # @example Fulltext search with attribute filters
+    #   index.search("cats AND dogs", author_id: 57)
+    #
+    # @example Attribute search only
+    #   index.search(author_id: 57)
+    #
+    # @param [String] query
+    #   a fulltext query
+    #
+    # @param [Hash] filters
+    #   attribute filters, limits, sorting and other options
+    #
+    # @return [Hash]
+    #   a Hash containing meta data, with the records in :records
     def search(*args)
-      raise ArgumentError, "Wrong number of arguments (#{args.size} for 1..2)" unless (1..2) === args.size
+      multi_search(_main_: args)[:_main_]
+    end
+
+    # Perform a faceted search on the index, using a base query and one or more facets.
+    #
+    # The base query is inherited by each facet, which may override (or refine) the
+    # query.
+    #
+    # The results returned include a :facets key, containing the results for each facet.
+    #
+    # @example
+    #   index.faceted_search(
+    #     "cats | dogs",
+    #     category_id: 7,
+    #     facets: {
+    #       popular: {views:        Oedipus.gt(150)},
+    #       recent:  {published_at: Oedipus.gt(Time.now.to_i - 7 * 86400)}
+    #     }
+    #   )
+    #
+    # @param [String] fulltext_query
+    #   a fulltext query to search on, optional
+    #
+    # @param [Hash] options
+    #   attribute filters and facets in a sub-hash
+    #
+    # @return [Hash]
+    #   a Hash whose top-level result set is for the main query and which
+    #   contains a :facets element with keys mapping 1:1 for all facets
+    def faceted_search(*args)
+      query, options = extract_query_data(args)
+      main_query     = [query, options.reject { |k, _| k == :facets }]
+      facets         = merge_queries(main_query, options.fetch(:facets, {}))
 
-      query, attrs = case args.first
-        when String then [args[0], args[1] || {}]
-        when Hash   then ["", args[0]]
-        else raise ArgumentError, "Invalid argument type #{args.first.class} for argument 0"
+      { facets: {} }.tap do |results|
+        multi_search({ _main_: main_query }.merge(facets)).each do |k, v|
+          k == :_main_ ? results.merge!(v) : results[:facets].merge!(k => v)
+        end
       end
+    end
 
-      results = @conn.execute(@builder.sql(query, attrs))
-      meta    = @conn.execute("SHOW META")
+    # Perform a a batch search on the index.
+    #
+    # A Hash of queries is passed, whose keys are used to collate the results in
+    # the return value.
+    #
+    # Each query may either by a string (fulltext search), a Hash (attribute search)
+    # or an array containing both.  In other words, the same arguments accepted by
+    # the #search method.
+    #
+    # @example
+    #   index.multi_search(
+    #     cat_results: ["cats", { author_id: 57 }],
+    #     dog_results: ["dogs", { author_id: 57 }]
+    #   )
+    #
+    # @param [Hash] queries
+    #   a hash whose keys map to queries
+    #
+    # @return [Hash]
+    #   a Hash whose keys map 1:1 with the input Hash, each element containing the
+    #   same results as those returned by the #search method.
+    def multi_search(queries)
+      unless queries.kind_of?(Hash)
+        raise ArgumentError, "Argument must be a Hash of named queries (#{queries.class} given)"
+      end
 
-      # FIXME: This needs optimizing
-      {}.tap do |r|
-        meta.each do |k, v|
-          r[k.to_sym] = case k
-            when 'total', 'total_found' then Integer(v)
-            when 'time'                 then Float(v)
-            else v
+      rs = @conn.multi_query(
+        queries.map { |key, args|
+          [@builder.select(*extract_query_data(args)), "SHOW META"]
+        }.flatten.join(";\n")
+      )
+
+      Hash[].tap do |result|
+        queries.keys.each do |key|
+          records, meta = rs.shift, rs.shift
+          result[key] = meta_to_hash(meta).tap do |r|
+            r[:records] = records.map { |hash|
+              hash.inject({}) { |o, (k, v)| o.merge!(k.to_sym => v) }
+            }
           end
         end
+      end
+    end
 
-        r[:records] = []
+    private
 
-        results.each_hash do |hash|
-          r[:records] << Hash[hash.keys.map(&:to_sym).zip(hash.map { |k, v| cast(k, v) })]
+    def meta_to_hash(meta)
+      Hash[].tap do |hash|
+        meta.each do |m|
+          n, v = m.values
+          case n
+          when "total_found", "total" then hash[n.to_sym] = v.to_i
+          when "time"                 then hash[:time] = v.to_f
+          when /\Adocs\[\d+\]\Z/      then (hash[:docs] ||= []).tap { |a| a << v.to_i }
+          when /\Ahits\[\d+\]\Z/      then (hash[:hits] ||= []).tap { |a| a << v.to_i }
+          when /\Akeyword\[\d+\]\Z/   then (hash[:keywords] ||= []).tap { |a| a << v }
+          else hash[n.to_sym] = v
+          end
+        end
+
+        if hash.key?(:docs) && hash.key?(:hits) && hash.key?(:keywords)
+          hash[:docs] = Hash[(hash[:keywords]).zip(hash[:docs])]
+          hash[:hits] = Hash[(hash[:keywords]).zip(hash[:hits])]
         end
       end
     end
 
-    private
+    def extract_query_data(args, default_query = "")
+      args = [args] unless Array === args
 
-    def cast(key, value)
-      case attributes[key.to_sym]
-      when Fixnum then Integer(value)
-      else value
+      unless (1..2) === args.size
+        raise ArgumentError, "Wrong number of query arguments (#{args.size} for 1..2)"
       end
-    end
 
-    def reflect_attributes
-      rs = @conn.execute("DESC #{name}")
-      {}.tap do |attrs|
-        rs.each_hash do |row|
-          case row['Type']
-          when 'uint', 'integer' then attrs[row['Field'].to_sym] = 0
-          when 'string'          then attrs[row['Field'].to_sym] = ""
-          end
-        end
+      case args[0]
+      when String then [args[0],       args.fetch(1, {})]
+      when Hash   then [default_query, args[0]          ]
+      else raise ArgumentError, "Invalid query argument type #{args.first.class}"
       end
     end
+
+    def merge_queries(base, others)
+      base_query, base_filters = base
+
+      Hash[others.map { |k, q|
+        query, filters = extract_query_data(q, base_query)
+        [k, [query.gsub("%{query}", base_query), base_filters.merge(filters)]]
+      }]
+    end
   end
 end

data/lib/oedipus/query_builder.rb

@@ -8,32 +8,125 @@
 ##
 
 module Oedipus
+  # Constructs SphinxQL queries from the internal Hash format.
   class QueryBuilder
-    def initialize(index_name, conn)
+    # Initialize a new QueryBuilder for +index_name+.
+    #
+    # @param [Symbol] index_name
+    #   the name of the index being queried
+    def initialize(index_name)
       @index_name = index_name
-      @conn       = conn
     end
 
-    def sql(query, filters)
+    # Build a SphinxQL query for the fulltext search +query+ and filters in +filters+.
+    #
+    # @param [String] query
+    #   the fulltext query to execute (may be empty)
+    #
+    # @param [Hash] filters
+    #   additional attribute filters and other options
+    #
+    # @return [String]
+    #   a SphinxQL query
+    def select(query, filters)
       [
         from,
         conditions(query, filters),
+        order_by(filters),
         limits(filters)
       ].join(" ")
     end
 
+    # Build a SphinxQL query to insert the record identified by +id+ with the given attributes.
+    #
+    # @param [Fixnum] id
+    #   the unique ID of the document to insert
+    #
+    # @param [Hash] attributes
+    #   a Hash of attributes
+    #
+    # @return [String]
+    #   the SphinxQL to insert the record
+    def insert(id, attributes)
+      into("INSERT", id, attributes)
+    end
+
+    # Build a SphinxQL query to update the record identified by +id+ with the given attributes.
+    #
+    # @param [Fixnum] id
+    #   the unique ID of the document to update
+    #
+    # @param [Hash] attributes
+    #   a Hash of attributes
+    #
+    # @return [String]
+    #   the SphinxQL to update the record
+    def update(id, attributes)
+      [
+        "UPDATE #{@index_name} SET",
+        update_attributes(attributes),
+        "WHERE id = #{Connection.quote(id)}"
+      ].join(" ")
+    end
+
+    # Build a SphinxQL query to replace the record identified by +id+ with the given attributes.
+    #
+    # @param [Fixnum] id
+    #   the unique ID of the document to replace
+    #
+    # @param [Hash] attributes
+    #   a Hash of attributes
+    #
+    # @return [String]
+    #   the SphinxQL to replace the record
+    def replace(id, attributes)
+      into("REPLACE", id, attributes)
+    end
+
     private
 
     def from
       "SELECT * FROM #{@index_name}"
     end
 
+    def into(type, id, attributes)
+      [
+        type,
+        "INTO #{@index_name}",
+        "(#{([:id] + attributes.keys).join(', ')})",
+        "VALUES",
+        "(#{([id] + attributes.values).map { |v| Connection.quote(v) }.join(', ')})"
+      ].join(" ")
+    end
+
     def conditions(query, filters)
       exprs = []
-      exprs << "MATCH(#{@conn.quote(query)})" unless query.empty?
+      exprs << "MATCH(#{Connection.quote(query)})" unless query.empty?
+      exprs += attribute_conditions(filters)
       "WHERE " << exprs.join(" AND ") if exprs.any?
     end
 
+    def attribute_conditions(filters)
+      filters \
+        .reject { |k, v| [:limit, :offset, :order].include?(k.to_sym) } \
+        .map    { |k, v| "#{k} #{Comparison.of(v)}" }
+    end
+
+    def update_attributes(attributes)
+      attributes \
+        .map    { |k, v| "#{k} = #{Connection.quote(v)}" } \
+        .join(", ")
+    end
+
+    def order_by(filters)
+      return unless filters.key?(:order)
+
+      [
+        "ORDER BY",
+        Array(filters[:order]).map { |k, dir| "#{k} #{dir ? dir.to_s.upcase : 'ASC'}" }.join(", ")
+      ].join(" ")
+    end
+
     def limits(filters)
       "LIMIT #{filters[:offset].to_i}, #{filters[:limit].to_i}" if filters.key?(:limit)
     end

data/lib/oedipus/version.rb

@@ -8,5 +8,5 @@
 ##
 
 module Oedipus
-  VERSION = "0.0.1.pre1"
+  VERSION = "0.0.1.pre2"
 end

data/lib/oedipus.rb

@@ -8,18 +8,39 @@
 ##
 
 require "oedipus/version"
+
+require "oedipus/oedipus"
+
+require "oedipus/comparison"
+require "oedipus/comparison/equal"
+require "oedipus/comparison/not_equal"
+require "oedipus/comparison/between"
+require "oedipus/comparison/outside"
+require "oedipus/comparison/in"
+require "oedipus/comparison/not_in"
+require "oedipus/comparison/gte"
+require "oedipus/comparison/gt"
+require "oedipus/comparison/lte"
+require "oedipus/comparison/lt"
+require "oedipus/comparison/not"
+require "oedipus/comparison/shortcuts"
+
 require "oedipus/query_builder"
+
+require "oedipus/connection_error"
 require "oedipus/connection"
+
 require "oedipus/index"
-require "oedipus/mysql/client"
 
 module Oedipus
+  extend Comparison::Shortcuts
+
   class << self
     # Connect to Sphinx running SphinxQL.
     #
     # @example
     #   c = Oedipus.connect("localhost:9306")
-    #   c = Oedipus.connect(:host => "localhost", :port => 9306)
+    #   c = Oedipus.connect(host: "localhost", port: 9306)
     #
     # @param [String] server
     #   a 'hostname:port' string
@@ -31,11 +52,7 @@ module Oedipus
     #   a client connected to SphinxQL
     def connect(options)
       # TODO: Add pooling
-      Connection.new(
-        options.kind_of?(String) ?
-          Hash[ [:host, :port].zip(options.split(":")) ] :
-          options
-      )
+      Connection.new(options)
     end
   end
 end

data/oedipus.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.email       = ["chris@w3style.co.uk"]
   s.homepage    = "https://github.com/d11wtq/oedipus"
   s.summary     = "Sphinx 2 Search Client for Ruby"
-  s.description = <<-DESC.strip
+  s.description = <<-DESC.gsub(/^ {4}/m, "")
     Oedipus brings full support for Sphinx 2 to Ruby:
 
       * real-time indexes
@@ -25,11 +25,10 @@ Gem::Specification.new do |s|
   s.rubyforge_project = "oedipus"
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.test_files    = `git ls-files -- spec/*`.split("\n")
+  s.extensions    = ["ext/oedipus/extconf.rb"]
   s.require_paths = ["lib"]
 
-  s.add_runtime_dependency "ruby-mysql"
-
   s.add_development_dependency "rspec"
+  s.add_development_dependency "rake-compiler"
 end

data/spec/integration/connection_spec.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+
+##
+# Oedipus Sphinx 2 Search.
+# Copyright © 2012 Chris Corbyn.
+#
+# See LICENSE file for details.
+##
+
+require "spec_helper"
+
+describe Oedipus::Connection do
+  include Oedipus::TestHarness
+
+  let(:conn) { Oedipus::Connection.new(searchd_host) }
+
+  describe "#initialize" do
+    context "with a hosname:port string" do
+      context "on successful connection" do
+        it "returns the connection" do
+          Oedipus::Connection.new(searchd_host.values.join(":")).should be_a_kind_of(Oedipus::Connection)
+        end
+      end
+
+      context "on failed connection" do
+        it "raises an error" do
+          expect {
+            Oedipus::Connection.new("127.0.0.1:45346138")
+          }.to raise_error(Oedipus::ConnectionError)
+        end
+      end
+    end
+
+    context "with an options Hash" do
+      context "on successful connection" do
+        it "returns the connection" do
+          Oedipus::Connection.new(searchd_host).should be_a_kind_of(Oedipus::Connection)
+        end
+      end
+
+      context "on failed connection" do
+        it "raises an error" do
+          expect {
+            Oedipus::Connection.new(:host => "127.0.0.1", :port => 45346138)
+          }.to raise_error(Oedipus::ConnectionError)
+        end
+      end
+    end
+  end
+
+  describe "#[]" do
+    let(:conn) { Oedipus::Connection.new(searchd_host) }
+
+    it "returns an index" do
+      conn[:posts_rt].should be_a_kind_of(Oedipus::Index)
+    end
+  end
+end