eson-dsl 0.7.0

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Florian Gilcher <florian.gilcher@asquera.de>, Felix Gilcher <felix.gilcher@asquera.de>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,179 @@
+# eson-dsl: The elasticsearch query DSL, in Ruby
+
+[![Build Status](https://secure.travis-ci.org/Asquera/eson-dsl.png?branch=master)](http://travis-ci.org/Asquera/eson-dsl)
+
+This gem provides a full implementation of the ElasticSearch query DSL, independent of a client. At the moment, it encodes the query DSL of ElasticSearch 0.19
+
+Features:
+
+* Safe: it does its best to avoid generating improper queries
+* Close to the original: All queries and filters have the same name an similar parameter order as in the elasticsearch documentation
+* Ease of use: makes handing some of the trickier aspects of the query language easier
+* Complete: Incorporates all of the elasticsearch query language
+
+## Usage
+
+``` ruby
+require 'eson-dsl'
+require 'json'
+
+q = Eson::Search::BaseQuery.new do
+  query do
+    wildcard :user, :value => "kim*y", :boost => 2.0
+  end
+  filters do
+    range :age, :from => 10, :to => 20
+  end
+  facets do
+    histogram :hist1, :field => :age, :interval => 2
+  end
+end
+
+JSON.dump(q.to_query_hash)
+```
+
+This example yields:
+
+```json
+{
+  "query": {
+    "filtered": {
+      "query": {
+        "wildcard": {
+          "user": {
+            "value": "kim*y",
+            "boost": 2.0}
+          }
+        }
+      },
+      "filter": {
+        "range": {
+          "age": {
+            "from": 10,
+            "to": 20
+          }
+        }
+      }
+    }
+  },
+  "facets": {
+    "hist1": {
+      "histogram": {
+        "field": "age",
+        "interval": 2
+      }
+    }
+  }
+}
+```
+
+The query generator does its best to avoid extra work. For example, if filtering is all you want, you can omit the query part - a `filtered` query with a `match_all`-query will be generated automatically:
+
+```ruby
+q.filter do
+  term "foo", :value => 'bar'
+end
+```
+
+will generate:
+
+```ruby
+{
+  "query": {
+    "filtered": {
+      "query": {
+        "match_all": { }
+      },
+      "filter": {
+        "term": {
+          "foo": {
+            "value": "bar"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Parameters
+
+Parameters can be passed to BaseQuery to allow generation of dynamic queries, without playing with variable visibility:
+
+```ruby
+Eson::Search::BaseQuery.new(:search_string => "kim*y", :boost => 2.0) do
+  query do
+    wildcard :user, :value => param(:search_string), :boost => param(:boost)
+  end
+end
+
+```
+
+## Examples
+
+See `examples` for all examples used in the test suite.
+
+## Specialities
+
+Eson supports scoped facets in an object-oriented way. To scope a facet, call `scope` on it and pass the reference to a subquery. In practice, this requires a bit of trickery in Ruby 1.9, as it local variables are not propagated outside of the introducing block:
+
+```ruby
+Eson::Search::BaseQuery.new do
+  q = nil
+  query do
+    q = nested :path => :obj1, :score_mode => "avg" do
+      query do
+        match_all
+      end
+      filters do
+        range :age, :from => 10, :to => 20
+      end
+    end
+  end
+
+  facets do
+    (histogram :hist1, :field => :age, :interval => 2).scope(q, 'my_scope')
+  end
+end
+```
+
+## Caveats
+
+`and`, `not` and `or` are Ruby keywords and can only be used as methods of the receiver is explicit. For that reason, you need to write the following to generate `and`- and `or`-filters:
+
+```ruby
+q.filter do |f|
+  f.or do
+    term "name.first" => "Felix"
+    term "name.first" => "Florian"
+  end
+end
+```
+
+and
+
+```ruby
+q.filter do |f|
+  f.and do #and is a keyword, so it needs a receiver
+    range :post_date, {:from => "2010-03-01", :to => "2010-04-01"}
+    prefix "name.second" => "ba"
+  end
+end
+```
+
+Due to clever defaults, `and` can be omitted altogether:
+
+```ruby
+q.filter do |f|
+  range :post_date, {:from => "2010-03-01", :to => "2010-04-01"}
+  prefix "name.second" => "ba"
+end
+```
+
+
+# TODO
+
+* Indices-Query is missing
+* Custom-Boost-Query is missing)
+* More docs
+* Testing on Ruby 1.8

data/Rakefile

@@ -0,0 +1,30 @@
+require 'rubygems' unless defined?(Gem)
+require 'rubygems/specification'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+def gemspec
+  @gemspec ||= begin
+    file = File.expand_path("eson-dsl.gemspec")
+    ::Gem::Specification.load(file)
+  end
+end
+
+desc "Validates the gemspec"
+task :gemspec do
+  gemspec.validate
+end
+
+Rake::GemPackageTask.new(gemspec) do |pkg|
+  pkg.gem_spec = gemspec
+end
+
+task :package => :gemspec
+
+Rake::TestTask.new(:test) do |test|
+  test.pattern = 'test/**/*_test.rb'
+
+  test.verbose = true
+end
+
+task :default => :test

data/TODO.md

@@ -0,0 +1 @@
+* Add missing examples (run YARD and see)

data/eson-dsl.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+#require "./lib/elsearch"
+
+Gem::Specification.new do |s|
+  s.name        = "eson-dsl"
+  s.version     = "0.7.0"
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Florian Gilcher"]
+  s.email       = ["florian.gilcher@asquera.de"]
+  s.homepage    = ""
+  s.summary     = %q{An ElasticSearch query DSL Generator}
+  s.description = %q{eson-dsl provides an abstraction to create ElasticSearch queries.}
+
+  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.require_paths = ["lib"]
+
+  s.add_development_dependency "elasticsearch-node"
+end

data/examples/facets/date_histogram.rb

@@ -0,0 +1,5 @@
+Eson::Search::BaseQuery.new do
+  facets do
+    date_histogram :hist1, :field => :time, :interval => "day"
+  end
+end

data/examples/facets/filter.rb

@@ -0,0 +1,7 @@
+Eson::Search::BaseQuery.new do
+  facets do
+    filter :wow_facet do
+      term :tag => "wow"
+    end
+  end
+end

data/examples/facets/geo_distance.rb

@@ -0,0 +1,14 @@
+Eson::Search::BaseQuery.new do
+  facets do
+    geo_distance :geo1, :location do
+      lat(40)
+      lon(-70)
+      ranges [
+          { :to => 10 },
+          { :from => 10, :to => 20 },
+          { :from => 20, :to => 100 },
+          { :from => 100 }
+      ]
+    end
+  end
+end

data/examples/facets/histogram.rb

@@ -0,0 +1,5 @@
+Eson::Search::BaseQuery.new do
+  facets do
+    histogram :hist1, :field => :age, :interval => 100
+  end
+end

data/examples/facets/query.rb

@@ -0,0 +1,7 @@
+Eson::Search::BaseQuery.new do
+  facets do
+    query :wow_facet do
+      term :tag => "wow"
+    end
+  end
+end

data/examples/facets/range.rb

@@ -0,0 +1,8 @@
+Eson::Search::BaseQuery.new do
+  facets do
+    range :range1, :age, { :to => 50 },
+                         { :from => 20, :to => 70 },
+                         { :from => 70, :to => 120 },
+                         { :from => 150 }
+  end
+end

data/examples/facets/scoped.rb

@@ -0,0 +1,17 @@
+Eson::Search::BaseQuery.new do
+  q = nil
+  query do
+    q = nested :path => :obj1, :score_mode => "avg" do
+      query do
+        match_all
+      end
+      filters do
+        range :age, :from => 10, :to => 20
+      end
+    end
+  end
+
+  facets do
+    (histogram :hist1, :field => :age, :interval => 2).scope(q, 'my_scope')
+  end
+end

data/examples/facets/statistical.rb

@@ -0,0 +1,5 @@
+Eson::Search::BaseQuery.new do
+  facets do
+    statistical :stat1, {:field => :field1}
+  end
+end

data/examples/facets/term_stats.rb

@@ -0,0 +1,9 @@
+Eson::Search::BaseQuery.new do
+  query do
+    match_all
+  end
+  facets do
+    terms_stats :tag_price_stats, {:key_field => :tag,
+                                   :value_field => :price }
+  end
+end

data/examples/facets/terms.rb

@@ -0,0 +1,8 @@
+Eson::Search::BaseQuery.new do
+  query do
+    match_all
+  end
+  facets do
+    terms :tags, :field => :tags, :size => 10, :order => :term
+  end
+end

data/examples/filters/and.rb

@@ -0,0 +1,11 @@
+Eson::Search::BaseQuery.new do
+  query do
+    term :tag => "something"
+  end
+  filter do |f|
+    f.and do #and is a keyword, so it needs a receiver
+      range :post_date, {:from => "2010-03-01", :to => "2010-04-01"}
+      prefix "name.second" => "ba"
+    end
+  end
+end

data/examples/filters/and_without_keyword.rb

@@ -0,0 +1,9 @@
+Eson::Search::BaseQuery.new do
+  query do
+    term :tag => "something"
+  end
+  filter do |f|
+    range :post_date, {:from => "2010-03-01", :to => "2010-04-01"}
+    prefix "name.second" => "ba"
+  end
+end

data/examples/filters/bool.rb

@@ -0,0 +1,16 @@
+Eson::Search::BaseQuery.new do 
+  filter do
+    bool do
+      must do
+        term "user" => "kimchy"
+      end
+      must_not do
+        range :age, :from => 10, :to => 20
+      end
+      should do
+        term "tag" => "wow"
+        term "tag" => "elasticsearch"
+      end
+    end
+  end
+end

data/examples/filters/exists.rb

@@ -0,0 +1,9 @@
+Eson::Search::BaseQuery.new do
+  query do
+    constant_score do
+      filter do
+        exists :field => "user"
+      end
+    end
+  end
+end

data/examples/filters/fquery.rb

@@ -0,0 +1,11 @@
+Eson::Search::BaseQuery.new do
+  query do
+    constant_score do
+      filter do
+        fquery :_cache => true do
+          query_string "this AND that OR thus"
+        end
+      end
+    end
+  end
+end

data/examples/filters/geo_bounding_box.rb

@@ -0,0 +1,8 @@
+Eson::Search::BaseQuery.new do
+  filter do
+    geo_bounding_box "location" do
+      top_left :lat => 40.73, :lon => -74.1
+      bottom_right :lat => 40.717, :lon => -73.99
+    end
+  end
+end

data/examples/filters/geo_distance.rb

@@ -0,0 +1,8 @@
+Eson::Search::BaseQuery.new do
+  filter do
+    geo_distance "location", :distance => "200km" do
+      lat(40)
+      lon(-70)
+    end
+  end
+end

data/examples/filters/geo_distance_alternate.rb

@@ -0,0 +1,9 @@
+Eson::Search::BaseQuery.new do
+  filter do
+    geo_distance "location" do
+      distance "200km"
+      lat(40)
+      lon(-70)
+    end
+  end
+end

data/examples/filters/geo_distance_range.rb

@@ -0,0 +1,10 @@
+Eson::Search::BaseQuery.new do
+  filter do
+    geo_distance_range "location" do
+      from "200km"
+      to "400km"
+      lat(40)
+      lon(-70)
+    end
+  end
+end

data/examples/filters/geo_polygon.rb

@@ -0,0 +1,10 @@
+Eson::Search::BaseQuery.new do
+  filter do
+    geo_polygon :location do
+      points [{:lat => 40, :lon => -70},
+              {:lat => 30, :lon => -80}]
+
+      point :lat => 20, :lon => -90
+    end
+  end
+end

data/examples/filters/has_child.rb

@@ -0,0 +1,9 @@
+Eson::Search::BaseQuery.new do
+  filter do
+    has_child :blog_tag do
+      query do
+        term :tag => "something"
+      end
+    end
+  end
+end

data/examples/filters/ids.rb

@@ -0,0 +1,8 @@
+Eson::Search::BaseQuery.new do
+  query do
+    match_all
+  end
+  filter do
+    ids "user", [1,2,3,4,5,6,7]
+  end
+end

data/examples/filters/missing.rb

@@ -0,0 +1,9 @@
+Eson::Search::BaseQuery.new do
+  query do
+    constant_score do
+      filter do
+        missing :field => "user"
+      end
+    end
+  end
+end

data/examples/filters/not.rb

@@ -0,0 +1,10 @@
+Eson::Search::BaseQuery.new do
+  query do
+    term :tag => "something"
+  end
+  filter do |f|
+    f.not do
+      term "name.first" => "Florian"
+    end
+  end
+end

data/examples/filters/numeric_range.rb

@@ -0,0 +1,9 @@
+Eson::Search::BaseQuery.new do
+  query do
+    constant_score do
+      filter do
+        numeric_range :age, :from => 10, :to => 20
+      end
+    end
+  end
+end

data/examples/filters/or.rb

@@ -0,0 +1,11 @@
+Eson::Search::BaseQuery.new do
+  query do
+    term :tag => "something"
+  end
+  filter do |f|
+    f.or do
+      term "name.first" => "Felix"
+      term "name.first" => "Florian"
+    end
+  end
+end

data/examples/filters/range.rb

@@ -0,0 +1,5 @@
+Eson::Search::BaseQuery.new do
+  filter do
+    range :age, :from => 10, :to => 20
+  end
+end

data/examples/filters/type.rb

@@ -0,0 +1,5 @@
+Eson::Search::BaseQuery.new do
+  filter do
+    type :my_type
+  end
+end

data/examples/queries/bool.rb

@@ -0,0 +1,16 @@
+Eson::Search::BaseQuery.new do
+  query do
+    bool do
+      must do
+        term "user", :value => "kimchy"
+      end
+      must_not do
+        range :age, :from => 10, :to => 20
+      end
+      should do
+        term "tag", :value => "wow"
+        term "tag", :value => "elasticsearch"
+      end
+    end
+  end
+end

data/examples/queries/boosting.rb

@@ -0,0 +1,12 @@
+Eson::Search::BaseQuery.new do
+  query do
+    boosting(:negative_boost => 0.2) do
+      positive do
+        term :field1 => 1
+      end
+      negative do
+        term :field1 => 2
+      end
+    end
+  end
+end

data/examples/queries/constant_score.rb

@@ -0,0 +1,9 @@
+Eson::Search::BaseQuery.new do
+  query do
+    constant_score :boost => 2.0 do
+      query do
+        term "user", :value => "kimchy"
+      end
+    end
+  end
+end

data/examples/queries/constant_score_with_filter.rb

@@ -0,0 +1,9 @@
+Eson::Search::BaseQuery.new do
+  query do
+    constant_score :boost => 2.0 do
+      filter do
+        term "user", :value => "kimchy"
+      end
+    end
+  end
+end

data/examples/queries/custom_score.rb

@@ -0,0 +1,15 @@
+Eson::Search::BaseQuery.new do
+  query do
+    options = {
+      :script => "_score * doc['my_numeric_field'].value / pow(param1, param2)",
+      :params => {
+        :param1 => 2,
+        :param2 => 3.1
+      }
+    }
+
+    custom_score options do
+      query { match_all }
+    end
+  end
+end

data/examples/queries/dis_max.rb

@@ -0,0 +1,10 @@
+Eson::Search::BaseQuery.new do
+  query do
+    dis_max(:tie_breaker => 0.7) do
+      query do
+        term :age => 34
+        term :age => 35
+      end
+    end
+  end
+end

data/examples/queries/field.rb

@@ -0,0 +1,5 @@
+Eson::Search::BaseQuery.new do
+  query do
+    field "name.first" => "+something -else"
+  end
+end

data/examples/queries/filters_and_facets.rb

@@ -0,0 +1,11 @@
+Eson::Search::BaseQuery.new do
+  query do
+    match_all
+  end
+  filters do
+    range :age, :from => 10, :to => 20
+  end
+  facets do
+    histogram :hist1, :field => :age, :interval => 2
+  end
+end

data/examples/queries/flt.rb

@@ -0,0 +1,7 @@
+Eson::Search::BaseQuery.new do
+  query do
+    flt :fields => ["name.first", "name.last"],
+        :like_text => "text like this one",
+        :max_query_terms => 12
+  end
+end

data/examples/queries/flt_field.rb

@@ -0,0 +1,7 @@
+Eson::Search::BaseQuery.new do
+  query do
+    flt_field "name.first",
+              :like_text => "text like this one",
+              :max_query_terms => 12
+  end
+end