oedipus 0.0.1.pre4 → 0.0.1

data/README.md

@@ -13,20 +13,6 @@ search may be implemented, while remaining light and simple.
 Data structures are managed using core ruby data type (Array and Hash), ensuring
 simplicity and flexibilty.
 
-## Current Status
-
-This gem is in development.  It is not ready for production use.  I work for
-a company called Flippa.com, which currently implements faceted search in a PHP
-part of the website, using a slightly older version of Sphinx with lesser
-support for SphinxQL.  We want to move this search across to the ruby codebase
-of the website, but are held back by ruby's lack of support for Sphinx 2.
-
-Once a month the developers at Flippa are given three days to work on a project of
-their own choice.  This is my 'Triple Time' project.
-
-I anticipate another week or so of development before I can consider this project
-production-ready.
-
 ## Dependencies
 
   * ruby (>= 1.9)
@@ -35,13 +21,12 @@ production-ready.
 
 The gem builds a small (tiny) native extension for interfacing with mysql, as
 existing gems either did not support multi-queries, or were too flaky
-(i.e. ruby-mysql). I was also concerned about potential conflicts with any
-specific ORMs users may be using.  I will add a pure-ruby option in due course
-(it requires implementing a relatively small subset of the mysql 4.1/5.0 protocol).
+(i.e. ruby-mysql).  I will add a pure-ruby option in due course (it requires
+implementing a relatively small subset of the mysql 4.1 protocol).
 
 ## Usage
 
-The following features are all currently implemented, but more are coming.
+The following features are all currently implemented.
 
 ### Connecting to Sphinx
 
@@ -51,7 +36,7 @@ require "oedipus"
 sphinx = Oedipus.connect('localhost:9306') # sphinxql host
 ```
 
-### Inserting
+### Inserting (real-time indexes)
 
 ``` ruby
 sphinx[:articles].insert(
@@ -63,7 +48,7 @@ sphinx[:articles].insert(
 )
 ```
 
-### Replacing
+### Replacing (real-time indexes)
 
 ``` ruby
 sphinx[:articles].replace(
@@ -75,13 +60,13 @@ sphinx[:articles].replace(
 )
 ```
 
-### Updating
+### Updating (real-time indexes)
 
 ``` ruby
 sphinx[:articles].update(7, views: 103)
 ```
 
-### Deleting
+### Deleting (real-time indexes)
 
 ``` ruby
 sphinx[:articles].delete(7)
@@ -124,6 +109,26 @@ results = sphinx[:articles].search("badgers", limit: 2)
 # }
 ```
 
+### Fetching only specific attributes
+
+``` ruby
+sphinx[:articles].search(
+  "example",
+  attrs: [:id, :views]
+)
+```
+
+### Fetching additional attributes (including expressions)
+
+Any valid field expression may be fetched.  Be sure to alias it if you want to order by it.
+
+``` ruby
+sphinx[:articles].search(
+  "example",
+  attrs: [:*, "WEIGHT() AS wgt"]
+)
+```
+
 ### Attribute filters
 
 Result formatting is the same as for a fulltext search.  You can add as many
@@ -199,6 +204,35 @@ sphinx[:articles].search(
 )
 ```
 
+### Ordering
+
+``` ruby
+sphinx[:articles].search("badgers", order: { views: :asc })
+```
+
+Special handling is done for ordering by relevance.
+
+``` ruby
+sphinx[:articles].search("badgers", order: { relevance: :desc })
+```
+
+In the above case, Oedipus explicity adds `WEIGHT() AS relevance` to the `:attrs`
+option.  You can manually set up the relevance sort if you wish to name the weighting
+attribute differently.
+
+### Limits and offsets
+
+Note that Sphinx applies a limit of 20 by default, so you probably want to specify
+a limit yourself.  You are bound by your `max_matches` setting in sphinx.conf.
+
+Note that the meta data will still indicate the actual number of results that matched;
+you simply get a smaller collection of materialized records.
+
+``` ruby
+sphinx[:articles].search("bobcats", limit: 50)
+sphinx[:articles].search("bobcats", limit: 50, offset: 150)
+```
+
 ### Faceted searching
 
 A faceted search takes a base query and a set of additional queries that are
@@ -274,30 +308,11 @@ results = sphinx[:articles].multi_search(
 # }
 ```
 
-### Limits and offsets
-
-Note that Sphinx applies a limit of 20 by default, so you probably want to specify
-a limit yourself.  You are bound by your `max_matches` setting in sphinx.conf.
-
-Note that the meta data will still indicate the actual number of results that matched;
-you simply get a smaller collection of materialized records.
-
-``` ruby
-sphinx[:articles].search("bobcats", limit: 50)
-sphinx[:articles].search("bobcats", limit: 50, offset: 150)
-```
-
-### Ordering
-
-``` ruby
-sphinx[:articles].search("badgers", order: { views: :asc })
-```
-
 ## Running the specs
 
 There are both unit tests and integration tests in the specs/ directory.  By default they
 will both run, but in order for the integration specs to work, you need a locally
-installed copy of Sphinx [1].  You then execute the specs as follows:
+installed copy of [Sphinx] [1].  You then execute the specs as follows:
 
     SEARCHD=/path/to/bin/searchd bundle exec rake spec
 
@@ -318,7 +333,7 @@ You may also compile the C extension and run the specs separately, if you prefer
 
 ### Footnotes
 
-  [1] You can build a local copy of sphinx without installing it on the system:
+  [1]: You can build a local copy of sphinx without installing it on the system:
 
     cd sphinx-2.0.4/
     ./configure

data/lib/oedipus/query_builder.rb

@@ -30,7 +30,7 @@ module Oedipus
     #   a SphinxQL query
     def select(query, filters)
       [
-        from,
+        from(filters),
         conditions(query, filters),
         order_by(filters),
         limits(filters)
@@ -85,8 +85,23 @@ module Oedipus
 
     private
 
-    def from
-      "SELECT * FROM #{@index_name}"
+    private
+
+    def fields(filters)
+      filters.fetch(:attrs, [:*]).dup.tap do |fields|
+        if fields.none? { |a| /\brelevance\n/ === a } && normalize_order(filters).key?(:relevance)
+          fields << "WEIGHT() AS relevance"
+        end
+      end
+    end
+
+    def from(filters)
+      [
+        "SELECT",
+        fields(filters).join(", "),
+        "FROM",
+        @index_name
+      ].join(" ")
     end
 
     def into(type, id, attributes)
@@ -108,7 +123,7 @@ module Oedipus
 
     def attribute_conditions(filters)
       filters \
-        .reject { |k, v| [:limit, :offset, :order].include?(k.to_sym) } \
+        .reject { |k, v| [:attrs, :limit, :offset, :order].include?(k.to_sym) } \
         .map    { |k, v| "#{k} #{Comparison.of(v)}" }
     end
 
@@ -119,14 +134,18 @@ module Oedipus
     end
 
     def order_by(filters)
-      return unless filters.key?(:order)
+      return unless (order = normalize_order(filters)).any?
 
       [
         "ORDER BY",
-        Array(filters[:order]).map { |k, dir| "#{k} #{dir ? dir.to_s.upcase : 'ASC'}" }.join(", ")
+        order.map { |k, dir| "#{k} #{dir.to_s.upcase}" }.join(", ")
       ].join(" ")
     end
 
+    def normalize_order(filters)
+      Hash[Array(filters[:order]).map { |k, v| [k.to_sym, v || :asc] }]
+    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.pre4"
+  VERSION = "0.0.1"
 end

data/spec/integration/index_spec.rb

@@ -138,10 +138,10 @@ describe Oedipus::Index do
 
   describe "#search" do
     before(:each) do
-      index.insert(1, title: "Badgers and foxes",   views: 150)
-      index.insert(2, title: "Rabbits and hares",   views: 87)
-      index.insert(3, title: "Badgers in the wild", views: 41)
-      index.insert(4, title: "Badgers for all!",    views: 3003)
+      index.insert(1, title: "Badgers and foxes",         views: 150)
+      index.insert(2, title: "Rabbits and hares",         views: 87)
+      index.insert(3, title: "Badgers in the wild",       views: 41)
+      index.insert(4, title: "Badgers for all, badgers!", views: 3003)
     end
 
     context "by fulltext matching" do
@@ -211,6 +211,33 @@ describe Oedipus::Index do
           { id: 3, views: 41,   user_id: 0, status: "" },
         ]
       end
+
+      context "by relevance" do
+        it "returns the results ordered by most relevant" do
+          records = index.search("badgers", order: {relevance: :desc})[:records]
+          records.first[:relevance].should > records.last[:relevance]
+        end
+      end
+    end
+
+    context "with attribute additions" do
+      it "fetches the additional attributes" do
+        index.search("badgers", attrs: [:*, "7 AS x"])[:records].should == [
+          { id: 1, views: 150,  user_id: 0, status: "", x: 7 },
+          { id: 3, views: 41,   user_id: 0, status: "", x: 7 },
+          { id: 4, views: 3003, user_id: 0, status: "", x: 7 },
+        ]
+      end
+    end
+
+    context "with attribute restrictions" do
+      it "fetches the restricted attributes" do
+        index.search("badgers", attrs: [:id, :views])[:records].should == [
+          { id: 1, views: 150  },
+          { id: 3, views: 41   },
+          { id: 4, views: 3003 },
+        ]
+      end
     end
   end
 

data/spec/unit/query_builder_spec.rb

@@ -91,6 +91,12 @@ describe Oedipus::QueryBuilder do
       end
     end
 
+    context "with explicit attributes" do
+      it "puts the attributes in the select clause" do
+        builder.select("cats", attrs: [:*, "FOO() AS f"]).should =~ /SELECT \*, FOO\(\) AS f FROM posts/
+      end
+    end
+
     context "with a limit" do
       it "applies a LIMIT with an offset of 0" do
         builder.select("dogs", limit: 50).should =~ /SELECT .* FROM posts WHERE .* LIMIT 0, 50/
@@ -123,6 +129,12 @@ describe Oedipus::QueryBuilder do
       it "supports multiple orders" do
         builder.select("cats", order: {views: :asc, author_id: :desc}).should =~ /SELECT .* FROM posts WHERE .* ORDER BY views ASC, author_id DESC/
       end
+
+      context "by relevance" do
+        it "injects a weight() attribute" do
+          builder.select("cats", order: {relevance: :desc}).should =~ /SELECT \*, WEIGHT\(\) AS relevance FROM posts WHERE .* ORDER BY relevance DESC/
+        end
+      end
     end
   end
 

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: oedipus
 version: !ruby/object:Gem::Version
-  version: 0.0.1.pre4
-  prerelease: 6
+  version: 0.0.1
+  prerelease: 
 platform: ruby
 authors:
 - d11wtq
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-01 00:00:00.000000000 Z
+date: 2012-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &9990060 !ruby/object:Gem::Requirement
+  requirement: &10768160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *9990060
+  version_requirements: *10768160
 - !ruby/object:Gem::Dependency
   name: rake-compiler
-  requirement: &9989640 !ruby/object:Gem::Requirement
+  requirement: &10775820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *9989640
+  version_requirements: *10775820
 description: ! "== Sphinx 2 Comes to Ruby\n\nOedipus brings full support for Sphinx
   2 to Ruby:\n\n  - real-time indexes (insert, replace, update, delete)\n  - faceted
   search (variations on a base query)\n  - multi-queries (multiple queries executed
@@ -106,12 +106,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -3724018096309534563
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
+      segments:
+      - 0
+      hash: -3724018096309534563
 requirements: []
 rubyforge_project: oedipus
 rubygems_version: 1.8.11