search_flip 3.0.0.beta2 → 3.0.0

data/lib/search_flip/customable.rb

@@ -0,0 +1,34 @@
+module SearchFlip
+  # The SearchFlip::Sortable mixin provides the chainable #custom method to
+  # add arbitrary sections to the elasticsearch request
+
+  module Customable
+    def self.included(base)
+      base.class_eval do
+        attr_accessor :custom_value
+      end
+    end
+
+    # Adds a fully custom field/section to the request, such that upcoming or
+    # minor Elasticsearch features as well as other custom requirements can be
+    # used without having yet specialized criteria methods.
+    #
+    # @note Use with caution, because using #custom will potentiall override
+    #   other sections like +aggregations+, +query+, +sort+, etc if you use the
+    #   the same section names.
+    #
+    # @example
+    #   CommentIndex.custom(section: { argument: "value" }).request
+    #   => {:section=>{:argument=>"value"},...}
+    #
+    # @param hash [Hash] The custom section that is added to the request
+    #
+    # @return [SearchFlip::Criteria] A newly created extended criteria
+
+    def custom(hash)
+      fresh.tap do |criteria|
+        criteria.custom_value = (custom_value || {}).merge(hash)
+      end
+    end
+  end
+end

data/lib/search_flip/explainable.rb

@@ -0,0 +1,28 @@
+module SearchFlip
+  # The SearchFlip::Sortable mixin provides the chainable #explain method to
+  # control elasticsearch query explanations
+
+  module Explainable
+    def self.included(base)
+      base.class_eval do
+        attr_accessor :explain_value
+      end
+    end
+
+    # Specifies whether or not to enable explanation for each hit on how
+    # its score was computed.
+    #
+    # @example
+    #   CommentIndex.explain(true)
+    #
+    # @param value [Boolean] The value for explain
+    #
+    # @return [SearchFlip::Criteria] A newly created extended criteria
+
+    def explain(value)
+      fresh.tap do |criteria|
+        criteria.explain_value = value
+      end
+    end
+  end
+end

data/lib/search_flip/highlightable.rb

@@ -0,0 +1,49 @@
+module SearchFlip
+  # The SearchFlip::Sortable mixin provides the chainable #highlight method to
+  # use elasticsearch highlighting
+
+  module Highlightable
+    def self.included(base)
+      base.class_eval do
+        attr_accessor :highlight_values
+      end
+    end
+
+    # Adds highlighting of the given fields to the request.
+    #
+    # @example
+    #   CommentIndex.highlight([:title, :message])
+    #   CommentIndex.highlight(:title).highlight(:description)
+    #   CommentIndex.highlight(:title, require_field_match: false)
+    #   CommentIndex.highlight(title: { type: "fvh" })
+    #
+    # @example
+    #   query = CommentIndex.highlight(:title).search("hello")
+    #   query.results[0].highlight.title # => "<em>hello</em> world"
+    #
+    # @param fields [Hash, Array, String, Symbol] The fields to highligt.
+    #   Supports raw Elasticsearch values by passing a Hash.
+    #
+    # @param options [Hash] Extra highlighting options. Check out the Elasticsearch
+    #   docs for further details.
+    #
+    # @return [SearchFlip::Criteria] A new criteria including the highlighting
+
+    def highlight(fields, options = {})
+      fresh.tap do |criteria|
+        criteria.highlight_values = (criteria.highlight_values || {}).merge(options)
+
+        hash =
+          if fields.is_a?(Hash)
+            fields
+          elsif fields.is_a?(Array)
+            fields.each_with_object({}) { |field, h| h[field] = {} }
+          else
+            { fields => {} }
+          end
+
+        criteria.highlight_values[:fields] = (criteria.highlight_values[:fields] || {}).merge(hash)
+      end
+    end
+  end
+end

data/lib/search_flip/http_client.rb

@@ -25,17 +25,21 @@ module SearchFlip
           client.request = request.send(method, *args)
         end
       end
+
+      ruby2_keywords method
     end
 
     [:get, :post, :put, :delete, :head].each do |method|
-      define_method method do |*args|
+      define_method(method) do |*args|
         execute(method, *args)
       end
+
+      ruby2_keywords method
     end
 
     private
 
-    def execute(method, *args)
+    ruby2_keywords def execute(method, *args)
       response = request.send(method, *args)
 
       raise SearchFlip::ResponseError.new(code: response.code, body: response.body.to_s) unless response.status.success?

data/lib/search_flip/index.rb

@@ -498,7 +498,7 @@ module SearchFlip
       #
       # @see #index See #index for more details
 
-      def import(*args)
+      ruby2_keywords def import(*args)
         index(*args)
       end
 

data/lib/search_flip/null_instrumenter.rb

@@ -0,0 +1,21 @@
+module SearchFlip
+  class NullInstrumenter
+    def instrument(name, payload = {})
+      start(name, payload)
+
+      begin
+        yield(payload) if block_given?
+      ensure
+        finish(name, payload)
+      end
+    end
+
+    def start(_name, _payload)
+      true
+    end
+
+    def finish(_name, _payload)
+      true
+    end
+  end
+end

data/lib/search_flip/paginatable.rb

@@ -0,0 +1,93 @@
+module SearchFlip
+  # The SearchFlip::Paginatable mixin provides chainable methods to allow
+  # paginating the search results
+
+  module Paginatable
+    def self.included(base)
+      base.class_eval do
+        attr_accessor :offset_value, :limit_value
+      end
+    end
+
+    # Sets the request offset, ie SearchFlip's from parameter that is used
+    # to skip results in the result set from being returned.
+    #
+    # @example
+    #   CommentIndex.offset(100)
+    #
+    # @param value [Fixnum] The offset value, ie the number of results that are
+    #   skipped in the result set
+    #
+    # @return [SearchFlip::Criteria] A newly created extended criteria
+
+    def offset(value)
+      fresh.tap do |criteria|
+        criteria.offset_value = value.to_i
+      end
+    end
+
+    # @api private
+    #
+    # Returns the offset value or, if not yet set,  the default limit value (0).
+    #
+    # @return [Fixnum] The offset value
+
+    def offset_value_with_default
+      (offset_value || 0).to_i
+    end
+
+    # Sets the request limit, ie Elasticsearch's size parameter that is used
+    # to restrict the results that get returned.
+    #
+    # @example
+    #   CommentIndex.limit(100)
+    #
+    # @param value [Fixnum] The limit value, ie the max number of results that
+    #   should be returned
+    #
+    # @return [SearchFlip::Criteria] A newly created extended criteria
+
+    def limit(value)
+      fresh.tap do |criteria|
+        criteria.limit_value = value.to_i
+      end
+    end
+
+    # @api private
+    #
+    # Returns the limit value or, if not yet set, the default limit value (30).
+    #
+    # @return [Fixnum] The limit value
+
+    def limit_value_with_default
+      (limit_value || 30).to_i
+    end
+
+    # Sets pagination parameters for the criteria by using offset and limit,
+    # ie Elasticsearch's from and size parameters.
+    #
+    # @example
+    #   CommentIndex.paginate(page: 3)
+    #   CommentIndex.paginate(page: 5, per_page: 60)
+    #
+    # @param page [#to_i] The current page
+    # @param per_page [#to_i] The number of results per page
+    #
+    # @return [SearchFlip::Criteria] A newly created extended criteria
+
+    def paginate(page: 1, per_page: 30)
+      page = [page.to_i, 1].max
+      per_page = per_page.to_i
+
+      offset((page - 1) * per_page).limit(per_page)
+    end
+
+    def page(value)
+      paginate(page: value, per_page: limit_value_with_default)
+    end
+
+    def per(value)
+      paginate(page: 1 + (offset_value_with_default / limit_value_with_default), per_page: value)
+    end
+  end
+end

data/lib/search_flip/response.rb

@@ -222,7 +222,7 @@ module SearchFlip
     #
     # @return [Array] An array of database records
 
-    def records(options = {})
+    def records
       @records ||= begin
         sort_map = ids.each_with_index.each_with_object({}) { |(id, index), hash| hash[id.to_s] = index }
 

data/lib/search_flip/sortable.rb

@@ -0,0 +1,69 @@
+module SearchFlip
+  # The SearchFlip::Sortable mixin provides the chainable methods #sort as
+  # well as #resort
+
+  module Sortable
+    def self.included(base)
+      base.class_eval do
+        attr_accessor :sort_values
+
+        alias_method :order, :sort
+      end
+    end
+
+    # Specify the sort order you want Elasticsearch to use for sorting the
+    # results. When you call this multiple times, the sort orders are appended
+    # to the already existing ones. The sort arguments get passed to
+    # Elasticsearch without modifications, such that you can use sort by
+    # script, etc here as well.
+    #
+    # @example Default usage
+    #   CommentIndex.sort(:user_id, :id)
+    #
+    #   # Same as
+    #
+    #   CommentIndex.sort(:user_id).sort(:id)
+    #
+    # @example Default hash usage
+    #   CommentIndex.sort(user_id: "asc").sort(id: "desc")
+    #
+    #   # Same as
+    #
+    #   CommentIndex.sort({ user_id: "asc" }, { id: "desc" })
+    #
+    # @example Sort by native script
+    #   CommentIndex.sort("_script" => "sort_script", lang: "native", order: "asc", type: "number")
+    #
+    # @param args The sort values that get passed to Elasticsearch
+    #
+    # @return [SearchFlip::Criteria] A newly created extended criteria
+
+    def sort(*args)
+      fresh.tap do |criteria|
+        criteria.sort_values = (sort_values || []) + args
+      end
+    end
+
+    # Specify the sort order you want Elasticsearch to use for sorting the
+    # results with already existing sort orders being removed.
+    #
+    # @example
+    #   CommentIndex.sort(user_id: "asc").resort(id: "desc")
+    #
+    #   # Same as
+    #
+    #   CommentIndex.sort(id: "desc")
+    #
+    # @return [SearchFlip::Criteria] A newly created extended criteria
+    #
+    # @see #sort See #sort for more details
+
+    def resort(*args)
+      fresh.tap do |criteria|
+        criteria.sort_values = args
+      end
+    end
+
+    alias_method :reorder, :resort
+  end
+end

data/lib/search_flip/sourceable.rb

@@ -0,0 +1,30 @@
+module SearchFlip
+  # The SearchFlip::Sortable mixin provides the chainable #source method to
+  # use elasticsearch source filtering
+
+  module Sourceable
+    def self.included(base)
+      base.class_eval do
+        attr_accessor :source_value
+      end
+    end
+
+    # Use to specify which fields of the source document you want Elasticsearch
+    # to return for each matching result.
+    #
+    # @example
+    #   CommentIndex.source([:id, :message]).search("hello world")
+    #   CommentIndex.source(exclude: "description")
+    #   CommentIndex.source(false)
+    #
+    # @param value Pass any allowed value to restrict the returned source
+    #
+    # @return [SearchFlip::Criteria] A newly created extended criteria
+
+    def source(value)
+      fresh.tap do |criteria|
+        criteria.source_value = value
+      end
+    end
+  end
+end

data/lib/search_flip/version.rb

@@ -1,3 +1,3 @@
 module SearchFlip
-  VERSION = "3.0.0.beta2"
+  VERSION = "3.0.0"
 end

data/search_flip.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.post_install_message = <<~MESSAGE
     Thanks for using search_flip!
-    When upgrading from 1.x to 2.x, please check out
+    When upgrading to 3.x, please check out
     https://github.com/mrkamel/search_flip/blob/master/UPDATING.md
   MESSAGE
 
@@ -37,4 +37,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency "hashie"
   spec.add_dependency "http"
   spec.add_dependency "oj"
+  spec.add_dependency "ruby2_keywords"
 end

data/spec/search_flip/aggregation_spec.rb

@@ -271,8 +271,8 @@ RSpec.describe SearchFlip::Aggregation do
 
       ProductIndex.import [product1, product2, product3, product4]
 
-      query = ProductIndex.aggregate(categories: {}) do |agg|
-        agg.merge(ProductIndex.where(price: 100..200)).aggregate(:category)
+      query = ProductIndex.aggregate(categories: {}) do |aggregation|
+        aggregation.merge(ProductIndex.where(price: 100..200)).aggregate(:category)
       end
 
       result = query.aggregations(:categories).category.buckets.each_with_object({}) do |bucket, hash|
@@ -282,33 +282,24 @@ RSpec.describe SearchFlip::Aggregation do
       expect(result).to eq("category1" => 2, "category2" => 1)
     end
 
-    describe "unsupported methods" do
-      unsupported_methods = [
-        :profile_value, :failsafe_value, :terminate_after_value, :timeout_value, :offset_value, :limit_value,
-        :scroll_args, :highlight_values, :suggest_values, :custom_value, :source_value, :sort_values,
-        :includes_values, :preload_values, :eager_load_values, :post_must_values,
-        :post_must_not_values, :post_filter_values, :preference_value,
-        :search_type_value, :routing_value
-      ]
+    describe "assignments" do
+      methods = [:offset_value, :limit_value, :source_value, :explain_value]
 
-      unsupported_methods.each do |unsupported_method|
-        it "raises a NotSupportedError #{unsupported_method}" do
-          block = lambda do
-            TestIndex.aggregate(field: {}) do |agg|
-              criteria = SearchFlip::Criteria.new(target: TestIndex)
-              criteria.send("#{unsupported_method}=", "value")
+      methods.each do |method|
+        it "replaces the values" do
+          aggregation = SearchFlip::Aggregation.new(target: TestIndex)
+          aggregation.send("#{method}=", "value1")
 
-              agg.merge(criteria)
-            end
-          end
+          criteria = SearchFlip::Criteria.new(target: TestIndex)
+          criteria.send("#{method}=", "value2")
 
-          expect(&block).to raise_error(SearchFlip::NotSupportedError)
+          expect(aggregation.merge(criteria).send(method)).to eq("value2")
         end
       end
     end
 
     describe "array concatenations" do
-      methods = [:must_values, :must_not_values, :filter_values]
+      methods = [:sort_values, :must_values, :must_not_values, :filter_values]
 
       methods.each do |method|
         it "concatenates the values for #{method}" do
@@ -326,7 +317,7 @@ RSpec.describe SearchFlip::Aggregation do
     end
 
     describe "hash merges" do
-      methods = [:aggregation_values]
+      methods = [:highlight_values, :custom_value, :aggregation_values]
 
       methods.each do |method|
         it "merges the values for #{method}" do
@@ -342,6 +333,29 @@ RSpec.describe SearchFlip::Aggregation do
         end
       end
     end
+
+    describe "unsupported methods" do
+      unsupported_methods = [
+        :profile_value, :failsafe_value, :terminate_after_value, :timeout_value, :scroll_args,
+        :suggest_values, :includes_values, :preload_values, :eager_load_values, :post_must_values,
+        :post_must_not_values, :post_filter_values, :preference_value, :search_type_value, :routing_value
+      ]
+
+      unsupported_methods.each do |unsupported_method|
+        it "raises a NotSupportedError #{unsupported_method}" do
+          block = lambda do
+            aggregation = SearchFlip::Aggregation.new(target: TestIndex)
+
+            criteria = SearchFlip::Criteria.new(target: TestIndex)
+            criteria.send("#{unsupported_method}=", "value")
+
+            aggregation.merge(criteria)
+          end
+
+          expect(&block).to raise_error(SearchFlip::NotSupportedError)
+        end
+      end
+    end
   end
 
   describe "#respond_to?" do
@@ -369,8 +383,8 @@ RSpec.describe SearchFlip::Aggregation do
 
       temp_index.import [product1, product2, product3, product4]
 
-      query = temp_index.aggregate(categories: {}) do |agg|
-        agg.merge(temp_index.with_price_range(100..200)).aggregate(:category)
+      query = temp_index.aggregate(categories: {}) do |aggregation|
+        aggregation.merge(temp_index.with_price_range(100..200)).aggregate(:category)
       end
 
       result = query.aggregations(:categories).category.buckets.each_with_object({}) do |bucket, hash|
@@ -380,4 +394,144 @@ RSpec.describe SearchFlip::Aggregation do
       expect(result).to eq("category1" => 2, "category2" => 1)
     end
   end
+
+  describe "#explain" do
+    it "returns the explaination" do
+      ProductIndex.import create(:product)
+
+      query = ProductIndex.aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.explain(true)
+      end
+
+      expect(query.aggregations("top_hits").hits.hits.first.key?("_explanation")).to eq(true)
+    end
+  end
+
+  describe "#custom" do
+    it "adds a custom entry to the request" do
+      query = ProductIndex.aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.custom(custom_key: "custom_value")
+      end
+
+      expect(query.request[:aggregations][:top_hits][:top_hits][:custom_key]).to eq("custom_value")
+    end
+  end
+
+  describe "#highlight" do
+    it "adds a custom entry to the request" do
+      ProductIndex.import create(:product, title: "Title highlight")
+
+      query = ProductIndex.search("title:highlight").aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.highlight([:title])
+      end
+
+      expect(query.aggregations("top_hits").hits.hits.first.highlight.title).to be_present
+    end
+  end
+
+  describe "#page" do
+    it "returns the respective result window" do
+      product1, product2 = create_list(:product, 2)
+
+      ProductIndex.import [product1, product2]
+
+      query = ProductIndex.aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.sort(:id).per(1).page(2)
+      end
+
+      expect(query.aggregations("top_hits").hits.hits.first._id).to eq(product2.id.to_s)
+    end
+  end
+
+  describe "#per" do
+    it "returns the respective result window" do
+      ProductIndex.import create_list(:product, 2)
+
+      query = ProductIndex.aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.per(1)
+      end
+
+      expect(query.aggregations("top_hits").hits.hits.size).to eq(1)
+    end
+  end
+
+  describe "#paginate" do
+    it "returns the respective result window" do
+      product1, product2 = create_list(:product, 2)
+
+      ProductIndex.import [product1, product2]
+
+      query = ProductIndex.aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.sort(:id).paginate(page: 2, per_page: 1)
+      end
+
+      expect(query.aggregations("top_hits").hits.hits.first._id).to eq(product2.id.to_s)
+    end
+  end
+
+  describe "#limit" do
+    it "returns the respective result window" do
+      ProductIndex.import create_list(:product, 2)
+
+      query = ProductIndex.aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.limit(1)
+      end
+
+      expect(query.aggregations("top_hits").hits.hits.size).to eq(1)
+    end
+  end
+
+  describe "#offset" do
+    it "returns the respective result window" do
+      product1, product2 = create_list(:product, 2)
+
+      ProductIndex.import [product1, product2]
+
+      query = ProductIndex.aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.sort(:id).limit(1).offset(1)
+      end
+
+      expect(query.aggregations("top_hits").hits.hits.first._id).to eq(product2.id.to_s)
+    end
+  end
+
+  describe "#sort" do
+    it "returns the results in the specified order" do
+      product1, product2 = create_list(:product, 2)
+
+      ProductIndex.import [product1, product2]
+
+      query = ProductIndex.aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.sort(id: "desc")
+      end
+
+      expect(query.aggregations("top_hits").hits.hits.map(&:_id)).to eq([product2, product1].map(&:id).map(&:to_s))
+    end
+  end
+
+  describe "#resort" do
+    it "overrides the previous sorting and returns the results in the specified order" do
+      product1, product2 = create_list(:product, 2)
+
+      ProductIndex.import [product1, product2]
+
+      query = ProductIndex.aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.sort(id: "desc").resort(:id)
+      end
+
+      expect(query.aggregations("top_hits").hits.hits.map(&:_id)).to eq([product1, product2].map(&:id).map(&:to_s))
+    end
+  end
+
+  describe "#source" do
+    it "returns the specified fields only" do
+      ProductIndex.import create(:product)
+
+      query = ProductIndex.aggregate(top_hits: { top_hits: {} }) do |aggregation|
+        aggregation.source([:id, :title])
+      end
+
+      expect(query.aggregations("top_hits").hits.hits.first._source.keys).to eq(["id", "title"])
+    end
+  end
 end