eson-dsl 0.7.0 → 0.8.0

data/MethodReference.md

@@ -0,0 +1,53 @@
+# Method reference
+
+This is a full reference of all DSL methods with usage examples. The examples
+can be found in `/examples`. As DSL elements can be filters or facets too, this list is alphabetic. If you want a grouped reference, please use the
+elasticsearch reference.
+
+{render:Eson::Search::And#and}
+{render:Eson::Search::Bool#bool}
+{render:Eson::Search::Boosting#boosting}
+{render:Eson::Search::ConstantScore#constant_score}
+{render:Eson::Search::CustomScore#custom_score}
+{render:Eson::Search::DateHistogram#date_histogram}
+{render:Eson::Search::DisMax#dis_max}
+{render:Eson::Search::Exists#exists}
+{render:Eson::Search::Filtered#filtered}
+{render:Eson::Search::FilterFacet#filter}
+{render:Eson::Search::FQuery#fquery}
+{render:Eson::Search::Fuzzy#fuzzy}
+{render:Eson::Search::FuzzyLikeThis#flt}
+{render:Eson::Search::FuzzyLikeThisField#flt_field}
+{render:Eson::Search::GeoBoundingBox#geo_bounding_box}
+{render:Eson::Search::GeoDistance#geo_distance}
+{render:Eson::Search::GeoDistanceRange#geo_distance_range}
+{render:Eson::Search::GeoPolygon#geo_polygon}
+{render:Eson::Search::HasChild#has_child}
+{render:Eson::Search::Histogram#histogram}
+{render:Eson::Search::Ids#ids}
+{render:Eson::Search::MatchAll#match_all}
+{render:Eson::Search::Missing#missing}
+{render:Eson::Search::MoreLikeThis#mlt}
+{render:Eson::Search::MoreLikeThis#mlt_field}
+{render:Eson::Search::Nested#nested}
+{render:Eson::Search::Not#not}
+{render:Eson::Search::NumericRange#numeric_range}
+{render:Eson::Search::Or#or}
+{render:Eson::Search::Prefix#prefix}
+{render:Eson::Search::QueryFacet#query}
+{render:Eson::Search::QuerySting#query_string}
+{render:Eson::Search::Range#range}
+{render:Eson::Search::SpanFirst#span_first}
+{render:Eson::Search::SpanNear#span_near}
+{render:Eson::Search::SpanNot#span_not}
+{render:Eson::Search::SpanOr#span_or}
+{render:Eson::Search::SpanTerm#span_term}
+{render:Eson::Search::Statistical#statistical}
+{render:Eson::Search::SubQuery#sub_query}
+{render:Eson::Search::Term#term}
+{render:Eson::Search::Terms#terms}
+{render:Eson::Search::TermsStats#terms_stats}
+{render:Eson::Search::Text#text}
+{render:Eson::Search::TopChildren#top_children}
+{render:Eson::Search::Type#type}
+{render:Eson::Search::Wildcard#wildcard}

data/README.md

@@ -2,7 +2,7 @@
 
 [![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
+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:
 
@@ -13,31 +13,26 @@ Features:
 
 ## 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)
-```
+    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": {
@@ -53,61 +48,28 @@ This example yields:
             "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"
+      "facets": {
+        "hist1": {
+          "histogram": {
+            "field": "age",
+            "interval": 2
           }
         }
       }
     }
-  }
-}
-```
+
+For a list of all available generation methods along with examples, have a look at {file:eson-dsl/MethodReference.md}.
 
 ## 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
-
-```
+    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
 
@@ -117,63 +79,47 @@ See `examples` for all examples used in the test suite.
 
 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
+    Eson::Search::BaseQuery.new do
+      q = nil
       query do
-        match_all
+        q = nested :path => :obj1, :score_mode => "avg" do
+          query do
+            match_all
+          end
+          filters do
+            range :age, :from => 10, :to => 20
+          end
+        end
       end
-      filters do
-        range :age, :from => 10, :to => 20
+
+      facets do
+        (histogram :hist1, :field => :age, :interval => 2).scope(q, 'my_scope')
       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
-```
+    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
-```
+    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
+    q.filter do |f|
+      range :post_date, {:from => "2010-03-01", :to => "2010-04-01"}
+      prefix "name.second" => "ba"
+    end

data/Rakefile

@@ -1,6 +1,6 @@
 require 'rubygems' unless defined?(Gem)
 require 'rubygems/specification'
-require 'rake/gempackagetask'
+require 'rubygems/package_task'
 require 'rake/testtask'
 
 def gemspec
@@ -15,7 +15,7 @@ task :gemspec do
   gemspec.validate
 end
 
-Rake::GemPackageTask.new(gemspec) do |pkg|
+Gem::PackageTask.new(gemspec) do |pkg|
   pkg.gem_spec = gemspec
 end
 

data/eson-dsl.gemspec

@@ -4,7 +4,8 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "eson-dsl"
-  s.version     = "0.7.0"
+  s.version     = "0.8.0"
+
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Florian Gilcher"]
   s.email       = ["florian.gilcher@asquera.de"]

data/examples/queries/custom_boost_factor.rb

@@ -0,0 +1,9 @@
+Eson::Search::BaseQuery.new do
+  query do
+    custom_boost_factor :boost_factor => 5 do
+      query do
+        term "tag" => "wow"
+      end
+    end
+  end
+end

data/examples/queries/custom_filters_score.rb

@@ -0,0 +1,15 @@
+Eson::Search::BaseQuery.new do
+  query do
+    custom_filters_score :score_mode => :first do
+      query { match_all }
+      filters do
+        filter(:boost => 3) do
+          range :age, :from => 0 , :to => 10
+        end
+        filter(:boost => 2) do
+          range :age, :from => 10, :to => 20
+        end
+      end
+    end
+  end
+end

data/examples/queries/custom_filters_score_with_script.rb

@@ -0,0 +1,15 @@
+Eson::Search::BaseQuery.new do
+  query do
+    custom_filters_score :score_mode => :first, :script => "3" do
+      query { match_all }
+      filters do
+        filter do
+          range :age, :from => 0 , :to => 10
+        end
+        filter do
+          range :age, :from => 10, :to => 20
+        end
+      end
+    end
+  end
+end

data/examples/queries/filtered.rb

@@ -0,0 +1,8 @@
+Eson::Search::BaseQuery.new do
+  query do
+    filtered do
+      query { match_all }
+      filter { prefix "name.second" => "ba" }
+    end
+  end
+end

data/examples/queries/indices.rb

@@ -0,0 +1,12 @@
+Eson::Search::BaseQuery.new do
+  query do
+    indices :index1, :index2 do
+      query do
+        term "tag" => "wow"
+      end
+      no_match_query do
+        term "tag" => "kow"
+      end
+    end
+  end
+end

data/examples/queries/match.rb

@@ -0,0 +1,7 @@
+# Since 0.19.9, #match replaces the #text query. Prefer #match over #text in 
+# any case.
+Eson::Search::BaseQuery.new do
+  query do
+    match "message", :type => :phrase_prefix, :query => "this is a text"
+  end
+end

data/examples/queries/multi_match.rb

@@ -0,0 +1,5 @@
+Eson::Search::BaseQuery.new do
+  query do
+    multi_match "this is a test", :fields => ["subject", "message"]
+  end
+end

data/examples/queries/text.rb

@@ -1,3 +1,5 @@
+# Since 0.19.9, #match replaces the #text query. Prefer #match over #text in 
+# any case.
 Eson::Search::BaseQuery.new do
   query do
     text :type => :phrase_prefix, :message => "this is a text"

data/lib/compat.rb

@@ -0,0 +1,15 @@
+# Since elasticsearch 0.19.9, `text` is called `match`
+#
+# For backwards compatibility reasons, `text` will be generated until
+# all versions of ES below 0.19.9 are not supported anymore.
+#
+# `match` can be used in the DSL, though.
+module Eson
+  module Search
+    module Queries
+      module QueryMethods
+        #alias :match :text
+      end
+    end
+  end
+end

data/lib/eson-dsl.rb

@@ -43,6 +43,7 @@ require 'eson/search/or'
 require 'eson/search/not'
 require 'eson/search/numeric_range'
 require 'eson/search/missing'
+require 'eson/search/match'
 require 'eson/search/exists'
 require 'eson/search/type'
 require 'eson/search/fquery'
@@ -62,3 +63,37 @@ require 'eson/search/geo_bounding_box'
 require 'eson/search/geo_distance'
 require 'eson/search/geo_distance_range'
 require 'eson/search/geo_polygon'
+require 'eson/search/multi_match'
+require 'eson/search/indices'
+require 'eson/search/custom_boost_factor'
+require 'eson/search/custom_filters_score'
+require 'eson/search/filtered'
+
+#require 'compat'
+
+##
+# @!macro [new] eson.filter
+#   @method $1
+#   @overload $1
+#     @yield the block containing further options and subfilters
+#     @return [self] the generated facet
+#     Generates a `$1` filter in a filter context.
+#     {include:file:eson-dsl/examples/filters/$1.rb}
+
+##
+# @!macro [new] eson.query
+#   @method $1
+#   @overload $1
+#     @yield the block containing further options and subqueries
+#     @return [self] the generated facet
+#     Generates a `$1` query in a query context.
+#     {include:file:eson-dsl/examples/queries/$1.rb}
+
+##
+# @!macro [new] eson.facet
+#   @method $1
+#   @overload $1
+#     @yield the block describing further options
+#     @return [self] the generated facet
+#     Generates a `$1` facet in a facets context.
+#     {include:file:eson-dsl/examples/facets/$1.rb}