slingshot-rb 0.0.5 → 0.0.6

data/README.markdown

@@ -3,15 +3,15 @@ Slingshot
 
 ![Slingshot](https://github.com/karmi/slingshot/raw/master/slingshot.png)
 
-_Slingshot_ aims to provide a rich Ruby API and DSL for the
+_Slingshot_ aims to provide rich and comfortable Ruby API and DSL for the
 [ElasticSearch](http://www.elasticsearch.org/) search engine/database.
 
 _ElasticSearch_ is a scalable, distributed, highly-available,
 RESTful database communicating by JSON over HTTP, based on [Lucene](http://lucene.apache.org/),
-written in Java. It manages to very simple and very powerful at the same time.
+written in Java. It manages to be very simple and very powerful at the same time.
 You should seriously consider it to power search in your Ruby applications:
 it will deliver all the features you want — and many more you may have not
-imagined yet (native geo search? histogram facets for dates?)
+imagined yet (native geo search? date histogram facets? _percolator_?)
 
 _Slingshot_ currently allows basic operation with the index and searching. More is planned.
 
@@ -44,7 +44,7 @@ Plans for full ActiveModel integration (and other convenience layers) are in pro
 (see the [`activemodel`](https://github.com/karmi/slingshot/compare/activemodel) branch).
 
 To kick the tires, require the gem in an IRB session or a Ruby script
-(note that you can run the full example from [`examples/dsl.rb`](https://github.com/karmi/slingshot/blob/master/examples/dsl.rb)):
+(note that you can just run the full example from [`examples/dsl.rb`](https://github.com/karmi/slingshot/blob/master/examples/dsl.rb)):
 
     require 'rubygems'
     require 'slingshot'
@@ -63,20 +63,36 @@ First, let's create an index named `articles` and store/index some documents:
       refresh
     end
 
-Now, let's query the database:
+You can also create the
+index with specific [mappings](http://www.elasticsearch.org/guide/reference/api/admin-indices-create-index.html), such as:
 
-We are searching for articles tagged _ruby_, sorted by `title` in `descending` order,
-and also retrieving some [_facets_](http://www.lucidimagination.com/Community/Hear-from-the-Experts/Articles/Faceted-Search-Solr)
+    Slingshot.index 'articles' do
+      create :mappings => {
+        :article => {
+          :properties => {
+            :id       => { :type => 'string', :index => 'not_analyzed', :include_in_all => false },
+            :title    => { :type => 'string', :boost => 2.0,            :analyzer => 'snowball'  },
+            :tags     => { :type => 'string', :analyzer => 'keyword'                             },
+            :content  => { :type => 'string', :analyzer => 'snowball'                            }
+          }
+        }
+      }
+    end
+
+Now, let's query the database.
+
+We are searching for articles whose `title` begins with letter “T”, sorted by `title` in `descending` order,
+filtering them for ones tagged “ruby”, and also retrieving some [_facets_](http://www.lucidimagination.com/Community/Hear-from-the-Experts/Articles/Faceted-Search-Solr)
 from the database:
 
     s = Slingshot.search 'articles' do
       query do
-        terms :tags, ['ruby']
+        string 'title:T*'
       end
 
-      sort do
-        title 'desc'
-      end
+      filter :terms, :tags => ['ruby']
+
+      sort { title 'desc' }
 
       facet 'global-tags' do
         terms :tags, :global => true
@@ -90,14 +106,12 @@ from the database:
 Let's display the results:
 
     s.results.each do |document|
-      puts "* #{ document.title }"
+      puts "* #{ document.title } [tags: #{document.tags.join(', ')}]"
     end
 
-    # * Two
-    # * One
-    # * Four
+    # * Two [tags: ruby, python]
 
-Let's display the facets (distribution of tags across the whole database):
+Let's display the global facets (distribution of tags across the whole database):
 
     s.results.facets['global-tags']['terms'].each do |f|
       puts "#{f['term'].ljust(10)} #{f['count']}"
@@ -107,18 +121,28 @@ Let's display the facets (distribution of tags across the whole database):
     # python     1
     # php        1
     # java       1
-    
+
+Now, let's display the facets based on current query (notice that count for articles
+tagged with 'java' is included, even though it's not returned by our query;
+count for articles tagged 'php' is excluded, since they don't match the current query):
+
+    s.results.facets['current-tags']['terms'].each do |f|
+      puts "#{f['term'].ljust(10)} #{f['count']}"
+    end
+
+    # ruby       1
+    # python     1
+    # java       1
+
 We can display the full query JSON:
 
     puts s.to_json
-    # {"facets":{"current-tags":{"terms":{"field":"tags"}},"global-tags":{"global":true,"terms":{"field":"tags"}}},"sort":[{"title":"desc"}],"query":{"terms":{"tags":["ruby"]}}}
-
-See, a Ruby DSL for this thing is kinda handy?
+    # {"facets":{"current-tags":{"terms":{"field":"tags"}},"global-tags":{"global":true,"terms":{"field":"tags"}}},"query":{"query_string":{"query":"title:T*"}},"filter":{"terms":{"tags":["ruby"]}},"sort":[{"title":"desc"}]}
 
-You can display the corresponding `curl` command easily:
+Or, we can display the corresponding `curl` command for easy debugging:
 
     puts s.to_curl
-    # curl -X POST "http://localhost:9200/articles/_search?pretty=true" -d '{"facets":{"current-tags":{"terms":{"field":"tags"}},"global-tags":{"global":true,"terms":{"field":"tags"}}},"sort":[{"title":"desc"}],"query":{"terms":{"tags":["ruby"]}}}'
+    # curl -X POST "http://localhost:9200/articles/_search?pretty=true" -d '{"facets":{"current-tags":{"terms":{"field":"tags"}},"global-tags":{"global":true,"terms":{"field":"tags"}}},"query":{"query_string":{"query":"title:T*"}},"filter":{"terms":{"tags":["ruby"]}},"sort":[{"title":"desc"}]}'
 
 
 Features
@@ -127,9 +151,11 @@ Features
 Currently, _Slingshot_ supports only a limited subset of vast _ElasticSearch_ [Search API](http://www.elasticsearch.org/guide/reference/api/search/request-body.html) and it's [Query DSL](http://www.elasticsearch.org/guide/reference/query-dsl/):
 
 * Creating, deleting and refreshing the index
+* Creating the index with specific [mapping](http://www.elasticsearch.org/guide/reference/api/admin-indices-create-index.html)
 * Storing a document in the index
 * [Querying](https://github.com/karmi/slingshot/blob/master/examples/dsl.rb) the index with the `query_string`, `term` and `terms` types of queries
-* Sorting the results by `fields`
+* [Sorting](http://elasticsearch.org/guide/reference/api/search/sort.html) the results by `fields`
+* [Filtering](http://elasticsearch.org/guide/reference/query-dsl/) the results
 * Retrieving a _terms_ type of [facets](http://www.elasticsearch.org/guide/reference/api/search/facets/index.html) -- other types are high priority
 * Returning just specific `fields` from documents
 * Paging with `from` and `size` query options
@@ -155,9 +181,6 @@ In order of importance:
 * Dual interface: allow to simply pass queries/options for _ElasticSearch_ as a Hash in any method
 * [Histogram](http://www.elasticsearch.org/guide/reference/api/search/facets/histogram-facet.html) facets
 * Seamless support for [auto-updating _river_ index](http://www.elasticsearch.org/guide/reference/river/couchdb.html) for _CouchDB_ `_changes` feed
-* Infrastructure for query filters
-* [Range](http://www.elasticsearch.org/guide/reference/query-dsl/range-filter.html) filters and queries
-* [Geo Filters](http://www.elasticsearch.org/blog/2010/08/16/geo_location_and_search.html) for queries
 * [Statistical](http://www.elasticsearch.org/guide/reference/api/search/facets/statistical-facet.html) facets
 * [Geo Distance](http://www.elasticsearch.org/guide/reference/api/search/facets/geo-distance-facet.html) facets
 * [Index aliases](http://www.elasticsearch.org/guide/reference/api/admin-indices-aliases.html) management

data/examples/dsl.rb

@@ -29,9 +29,11 @@ end
 
 s = search 'articles' do
   query do
-    terms :tags, ['ruby']
+    string 'T*'
   end
 
+  filter :terms, :tags => ['ruby']
+
   sort do
     title 'desc'
   end
@@ -56,15 +58,16 @@ puts s.to_curl
 
 puts "", "Results:", "-"*80
 s.results.each_with_index do |document, i|
-  puts "#{i+1}. #{ document.title.ljust(20) } [id] #{document._id}"
+  puts "#{i+1}. #{ document.title.ljust(10) } [id] #{document._id}"
 end
 
 puts "", "Facets: tags distribution across the whole database:", "-"*80
 s.results.facets['global-tags']['terms'].each do |f|
-  puts "#{f['term'].ljust(10)} #{f['count']}"
+  puts "#{f['term'].ljust(13)} #{f['count']}"
 end
 
-puts "", "Facets: tags distribution for the current query", "-"*80
+puts "", "Facets: tags distribution for the current query ",
+         "(Notice that 'java' is included, because of the filter)", "-"*80
 s.results.facets['current-tags']['terms'].each do |f|
-  puts "#{f['term'].ljust(10)} #{f['count']}"
+  puts "#{f['term'].ljust(13)} #{f['count']}"
 end

data/lib/slingshot.rb

@@ -9,6 +9,7 @@ require 'slingshot/search'
 require 'slingshot/search/query'
 require 'slingshot/search/sort'
 require 'slingshot/search/facet'
+require 'slingshot/search/filter'
 require 'slingshot/results/collection'
 require 'slingshot/results/item'
 require 'slingshot/index'

data/lib/slingshot/search.rb

@@ -3,7 +3,7 @@ module Slingshot
   
     class Search
 
-      attr_reader :indices, :url, :results, :response, :query, :facets
+      attr_reader :indices, :url, :results, :response, :query, :facets, :filters
 
       def initialize(*indices, &block)
         @options = indices.pop if indices.last.is_a?(Hash)
@@ -31,6 +31,12 @@ module Slingshot
         self
       end
 
+      def filter(type, *options)
+        @filters ||= []
+        @filters << Filter.new(type, *options).to_hash
+        self
+      end
+
       def from(value)
         @from = value
         self
@@ -51,6 +57,9 @@ module Slingshot
         @response = JSON.parse( Configuration.client.post(@url, self.to_json) )
         @results = Results::Collection.new(@response)
         self
+      rescue Exception
+        STDERR.puts "Request failed: \n#{self.to_curl}"
+        raise
       end
 
       def to_curl
@@ -60,12 +69,13 @@ module Slingshot
       def to_json
         request = {}
         request.update( { :query  => @query } )
-        request.update( { :sort   => @sort } )   if @sort
-        request.update( { :facets => @facets } ) if @facets
-        request.update( { :size => @size } )     if @size
-        request.update( { :from => @from } )     if @from
-        request.update( { :fields => @fields } ) if @fields
-        request.to_json
+        request.update( { :sort   => @sort } )     if @sort
+        request.update( { :facets => @facets } )   if @facets
+        @filters.each { |filter| request.update( { :filter => filter } ) } if @filters
+        request.update( { :size => @size } )       if @size
+        request.update( { :from => @from } )       if @from
+        request.update( { :fields => @fields } )   if @fields
+        Yajl::Encoder.encode(request)
       end
 
     end

data/lib/slingshot/search/filter.rb

@@ -0,0 +1,29 @@
+module Slingshot
+  module Search
+
+    # http://www.elasticsearch.org/guide/reference/api/search/filter.html
+    # http://www.elasticsearch.org/guide/reference/query-dsl/
+    #
+    class Filter
+
+      def initialize(type, *options)
+        @type    = type
+        @options = options || []
+      end
+
+      def to_json
+        to_hash.to_json
+      end
+
+      def to_hash
+        initial = @options.size > 1 ? { @type => [] } : { @type => {} }
+        method  = initial[@type].is_a?(Hash) ? :update : :push
+        @options.inject(initial) do |hash, option|
+          hash[@type].send(method, option)
+          hash
+        end
+      end
+    end
+
+  end
+end

data/lib/slingshot/version.rb

@@ -1,3 +1,3 @@
 module Slingshot
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

data/test/integration/filters_test.rb

@@ -0,0 +1,46 @@
+require 'test_helper'
+
+module Slingshot
+
+  class FiltersIntegrationTest < Test::Unit::TestCase
+    include Test::Integration
+
+    context "Filters" do
+
+      should "filter the results" do
+        s = Slingshot.search('articles-test') do
+          query { string 'title:T*' }
+          filter :terms, :tags => ['ruby']
+        end
+
+        assert_equal 1, s.results.count
+        assert_equal 'Two', s.results.first.title
+      end
+
+      should "filter the results with multiple filters" do
+        s = Slingshot.search('articles-test') do
+          query { string 'title:F*' }
+          filter :or, {:terms => {:tags => ['ruby']}},
+                      {:terms => {:tags => ['erlang']}}
+        end
+
+        assert_equal 1, s.results.count
+        assert_equal 'Four', s.results.first.title
+      end
+
+      should "not influence facets" do
+        s = Slingshot.search('articles-test') do
+          query { string 'title:T*' }
+          filter :terms, :tags => ['ruby']
+          facet('tags') { terms :tags }
+        end
+
+        assert_equal 1, s.results.count
+        assert_equal 3, s.results.facets['tags'].size
+      end
+
+    end
+
+  end
+
+end

data/test/unit/search_facet_test.rb

@@ -7,7 +7,7 @@ module Slingshot::Search
     context "Facet" do
 
       should "be serialized to JSON" do
-        assert_respond_to Sort.new, :to_json
+        assert_respond_to Facet.new('foo'), :to_json
       end
 
       context "generally" do

data/test/unit/search_filter_test.rb

@@ -0,0 +1,33 @@
+require 'test_helper'
+
+module Slingshot::Search
+
+  class FilterTest < Test::Unit::TestCase
+
+    context "Filter" do
+
+      should "be serialized to JSON" do
+        assert_respond_to Filter.new(:terms, {}), :to_json
+      end
+
+      should "encode simple filter declarations as JSON" do
+        assert_equal( { :terms => { :tags => ['foo'] } }.to_json,
+                      Filter.new('terms', :tags => ['foo']).to_json )
+
+        assert_equal( { :range => { :age => { :from => 10, :to => 20 } } }.to_json,
+                      Filter.new('range', { :age => { :from => 10, :to => 20 } }).to_json )
+
+        assert_equal( { :geo_distance => { :distance => '12km', :location => [40, -70] } }.to_json,
+                      Filter.new('geo_distance', { :distance => '12km', :location => [40, -70] }).to_json )
+      end
+
+      should "encode 'or' filter declarations as JSON" do
+        # See http://www.elasticsearch.org/guide/reference/query-dsl/or-filter.html
+        assert_equal( { :or => [ {:terms => {:tags => ['foo']}}, {:terms => {:tags => ['bar']}} ] }.to_json,
+                      Filter.new('or', {:terms => {:tags => ['foo']}}, {:terms => {:tags => ['bar']}}).to_json )
+      end
+
+    end
+
+  end
+end

data/test/unit/search_test.rb

@@ -46,6 +46,14 @@ module Slingshot
         assert_not_nil s.response
       end
 
+      should "print debugging information on exception and re-raise it" do
+        Configuration.client.expects(:post).raises(RestClient::InternalServerError)
+        STDERR.expects(:puts)
+
+        s = Search::Search.new('index')
+        assert_raise(RestClient::InternalServerError) { s.perform }
+      end
+
       context "sort" do
 
         should "allow sorting by multiple fields" do
@@ -77,6 +85,20 @@ module Slingshot
 
       end
 
+      context "filter" do
+
+        should "allow to specify filter" do
+          s = Search::Search.new('index') do
+            filter :terms, :tags => ['foo']
+          end
+
+          assert_equal 1, s.filters.size
+          assert_not_nil s.filters.first
+          assert_not_nil s.filters.first[:terms]
+        end
+
+      end
+
       context "with from/size" do
 
         should "set the values in request" do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: slingshot-rb
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: 
   segments: 
   - 0
   - 0
-  - 5
-  version: 0.0.5
+  - 6
+  version: 0.0.6
 platform: ruby
 authors: 
 - Karel Minarik
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-02 00:00:00 +01:00
+date: 2011-03-13 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -163,6 +163,7 @@ files:
 - lib/slingshot/rubyext/hash.rb
 - lib/slingshot/search.rb
 - lib/slingshot/search/facet.rb
+- lib/slingshot/search/filter.rb
 - lib/slingshot/search/query.rb
 - lib/slingshot/search/sort.rb
 - lib/slingshot/version.rb
@@ -174,6 +175,7 @@ files:
 - test/fixtures/articles/4.json
 - test/fixtures/articles/5.json
 - test/integration/facets_test.rb
+- test/integration/filters_test.rb
 - test/integration/index_mapping_test.rb
 - test/integration/index_store_test.rb
 - test/integration/query_string_test.rb
@@ -187,6 +189,7 @@ files:
 - test/unit/results_collection_test.rb
 - test/unit/results_item_test.rb
 - test/unit/search_facet_test.rb
+- test/unit/search_filter_test.rb
 - test/unit/search_query_test.rb
 - test/unit/search_sort_test.rb
 - test/unit/search_test.rb
@@ -234,6 +237,7 @@ test_files:
 - test/fixtures/articles/4.json
 - test/fixtures/articles/5.json
 - test/integration/facets_test.rb
+- test/integration/filters_test.rb
 - test/integration/index_mapping_test.rb
 - test/integration/index_store_test.rb
 - test/integration/query_string_test.rb
@@ -247,6 +251,7 @@ test_files:
 - test/unit/results_collection_test.rb
 - test/unit/results_item_test.rb
 - test/unit/search_facet_test.rb
+- test/unit/search_filter_test.rb
 - test/unit/search_query_test.rb
 - test/unit/search_sort_test.rb
 - test/unit/search_test.rb