search_flip 2.2.0 → 2.3.0

data/lib/search_flip/criteria.rb

@@ -3,7 +3,7 @@ module SearchFlip
   # The SearchFlip::Criteria class serves the purpose of chaining various
   # filtering and aggregation methods. Each chainable method creates a new
   # criteria object until a method is called that finally sends the respective
-  # request to ElasticSearch and returns the result.
+  # request to Elasticsearch and returns the result.
   #
   # @example
   #   CommentIndex.where(public: true).sort(id: "desc").limit(1_000).records
@@ -22,7 +22,7 @@ module SearchFlip
     attr_accessor :target, :profile_value, :source_value, :sort_values, :highlight_values, :suggest_values,
       :offset_value, :limit_value, :includes_values, :eager_load_values, :preload_values, :failsafe_value,
       :scroll_args, :custom_value, :terminate_after_value, :timeout_value, :preference_value,
-      :search_type_value, :routing_value, :track_total_hits_value
+      :search_type_value, :routing_value, :track_total_hits_value, :explain_value
 
     # Creates a new criteria while merging the attributes (constraints,
     # settings, etc) of the current criteria with the attributes of another one
@@ -52,6 +52,7 @@ module SearchFlip
         criteria.search_type_value = other.search_type_value if other.search_type_value
         criteria.routing_value = other.routing_value if other.routing_value
         criteria.track_total_hits_value = other.track_total_hits_value unless other.track_total_hits_value.nil?
+        criteria.explain_value = other.explain_value unless other.explain_value.nil?
 
         criteria.sort_values = (criteria.sort_values || []) + other.sort_values if other.sort_values
         criteria.includes_values = (criteria.includes_values || []) + other.includes_values if other.includes_values
@@ -75,6 +76,22 @@ module SearchFlip
       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
+
     # Specifies if or how many hits should be counted/tracked. Check out the
     # elasticsearch docs for futher details.
     #
@@ -185,7 +202,7 @@ module SearchFlip
     # @return [SearchFlip::Criteria] A newly created extended criteria
 
     def unscope(*scopes)
-      warn "[DEPRECATION] unscope is deprecated"
+      warn "[DEPRECATION] unscope is deprecated and will be removed in search_flip 3"
 
       unknown = scopes - [:search, :post_search, :sort, :highlight, :suggest, :custom, :aggregate]
 
@@ -281,6 +298,7 @@ module SearchFlip
       res.update from: offset_value_with_default, size: limit_value_with_default
 
       res[:track_total_hits] = track_total_hits_value unless track_total_hits_value.nil?
+      res[:explain] = explain_value unless explain_value.nil?
       res[:timeout] = timeout_value if timeout_value
       res[:terminate_after] = terminate_after_value if terminate_after_value
       res[:highlight] = highlight_values if highlight_values
@@ -331,9 +349,9 @@ module SearchFlip
     #   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.
+    #   Supports raw Elasticsearch values by passing a Hash.
     #
-    # @param options [Hash] Extra highlighting options. Check out the ElasticSearch
+    # @param options [Hash] Extra highlighting options. Check out the Elasticsearch
     #   docs for further details.
     #
     # @return [SearchFlip::Criteria] A new criteria including the highlighting
@@ -363,7 +381,7 @@ module SearchFlip
     #
     # @param name [String, Symbol] The name of the suggestion section
     #
-    # @param options [Hash] Additional suggestion options. Check out the ElasticSearch
+    # @param options [Hash] Additional suggestion options. Check out the Elasticsearch
     #   docs for further details.
     #
     # @return [SearchFlip::Criteria] A new criteria including the suggestion section
@@ -416,8 +434,8 @@ module SearchFlip
       end
     end
 
-    # Sends a delete by query request to ElasticSearch, such that all documents
-    # matching the query get deleted. Please note, for certain ElasticSearch
+    # Sends a delete by query request to Elasticsearch, such that all documents
+    # matching the query get deleted. Please note, for certain Elasticsearch
     # versions you need to install the delete-by-query plugin to get support
     # for this feature. Refreshes the index if the auto_refresh is enabled.
     # Raises SearchFlip::ResponseError in case any errors occur.
@@ -444,7 +462,7 @@ module SearchFlip
       true
     end
 
-    # Use to specify which fields of the source document you want ElasticSearch
+    # Use to specify which fields of the source document you want Elasticsearch
     # to return for each matching result.
     #
     # @example
@@ -519,10 +537,10 @@ module SearchFlip
       end
     end
 
-    # Specify the sort order you want ElasticSearch to use for sorting the
+    # 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
+    # Elasticsearch without modifications, such that you can use sort by
     # script, etc here as well.
     #
     # @example Default usage
@@ -542,7 +560,7 @@ module SearchFlip
     # @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
+    # @param args The sort values that get passed to Elasticsearch
     #
     # @return [SearchFlip::Criteria] A newly created extended criteria
 
@@ -554,7 +572,7 @@ module SearchFlip
 
     alias_method :order, :sort
 
-    # Specify the sort order you want ElasticSearch to use for sorting the
+    # Specify the sort order you want Elasticsearch to use for sorting the
     # results with already existing sort orders being removed.
     #
     # @example
@@ -577,7 +595,7 @@ module SearchFlip
     alias_method :reorder, :resort
 
     # Adds a fully custom field/section to the request, such that upcoming or
-    # minor ElasticSearch features as well as other custom requirements can be
+    # 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
@@ -623,7 +641,7 @@ module SearchFlip
       (offset_value || 0).to_i
     end
 
-    # Sets the request limit, ie ElasticSearch's size parameter that is used
+    # Sets the request limit, ie Elasticsearch's size parameter that is used
     # to restrict the results that get returned.
     #
     # @example
@@ -649,7 +667,7 @@ module SearchFlip
     end
 
     # Sets pagination parameters for the criteria by using offset and limit,
-    # ie ElasticSearch's from and size parameters.
+    # ie Elasticsearch's from and size parameters.
     #
     # @example
     #   CommentIndex.paginate(page: 3)
@@ -677,7 +695,7 @@ module SearchFlip
 
     # Fetches the records specified by the criteria in batches using the
     # ElasicSearch scroll API and yields each batch. The batch size and scroll
-    # API timeout can be specified. Check out the ElasticSearch docs for
+    # API timeout can be specified. Check out the Elasticsearch docs for
     # further details.
     #
     # @example
@@ -689,7 +707,7 @@ module SearchFlip
     # @option options batch_size [Fixnum] The number of records to fetch per
     #   batch. Uses #limit to control the batch size.
     # @option options timeout [String] The timeout per scroll request, ie how
-    #   long ElasticSearch will keep the request handle open.
+    #   long Elasticsearch will keep the request handle open.
 
     def find_in_batches(options = {})
       return enum_for(:find_in_batches, options) unless block_given?
@@ -700,8 +718,8 @@ module SearchFlip
     end
 
     # Fetches the results specified by the criteria in batches using the
-    # ElasticSearch scroll API and yields each batch. The batch size and scroll
-    # API timeout can be specified. Checkout out the ElasticSearch docs for
+    # Elasticsearch scroll API and yields each batch. The batch size and scroll
+    # API timeout can be specified. Checkout out the Elasticsearch docs for
     # further details.
     #
     # @example
@@ -713,7 +731,7 @@ module SearchFlip
     # @option options batch_size [Fixnum] The number of records to fetch per
     #   batch. Uses #limit to control the batch size.
     # @option options timeout [String] The timeout per scroll request, ie how
-    #   long ElasticSearch will keep the request handle open.
+    #   long Elasticsearch will keep the request handle open.
 
     def find_results_in_batches(options = {})
       return enum_for(:find_results_in_batches, options) unless block_given?
@@ -724,8 +742,8 @@ module SearchFlip
     end
 
     # Fetches the records specified by the relatin in batches using the
-    # ElasticSearch scroll API and yields each record. The batch size and
-    # scroll API timeout can be specified. Check out the ElasticSearch docs for
+    # Elasticsearch scroll API and yields each record. The batch size and
+    # scroll API timeout can be specified. Check out the Elasticsearch docs for
     # further details.
     #
     # @example
@@ -737,7 +755,7 @@ module SearchFlip
     # @option options batch_size [Fixnum] The number of records to fetch per
     #   batch. Uses #limit to control the batch size.
     # @option options timeout [String] The timeout per scroll request, ie how
-    #   long ElasticSearch will keep the request handle open.
+    #   long Elasticsearch will keep the request handle open.
 
     def find_each(options = {})
       return enum_for(:find_each, options) unless block_given?
@@ -752,8 +770,8 @@ module SearchFlip
     alias_method :each, :find_each
 
     # Fetches the results specified by the criteria in batches using the
-    # ElasticSearch scroll API and yields each result. The batch size and scroll
-    # API timeout can be specified. Checkout out the ElasticSearch docs for
+    # Elasticsearch scroll API and yields each result. The batch size and scroll
+    # API timeout can be specified. Checkout out the Elasticsearch docs for
     # further details.
     #
     # @example
@@ -765,7 +783,7 @@ module SearchFlip
     # @option options batch_size [Fixnum] The number of records to fetch per
     #   batch. Uses #limit to control the batch size.
     # @option options timeout [String] The timeout per scroll request, ie how
-    #   long ElasticSearch will keep the request handle open.
+    #   long Elasticsearch will keep the request handle open.
 
     def find_each_result(options = {})
       return enum_for(:find_each_result, options) unless block_given?
@@ -778,7 +796,7 @@ module SearchFlip
     end
 
     # Executes the search request for the current criteria, ie sends the
-    # request to ElasticSearch and returns the response. Connection and
+    # request to Elasticsearch and returns the response. Connection and
     # response errors will be rescued if you specify the criteria to be
     # #failsafe, such that an empty response is returned instead.
     #
@@ -825,7 +843,7 @@ module SearchFlip
     alias_method :response, :execute
 
     # Marks the criteria to be failsafe, ie certain exceptions raised due to
-    # invalid queries, inavailability of ElasticSearch, etc get rescued and an
+    # invalid queries, inavailability of Elasticsearch, etc get rescued and an
     # empty criteria is returned instead.
     #
     # @see #execute See #execute for further details

data/lib/search_flip/filterable.rb

@@ -16,7 +16,7 @@ module SearchFlip
     end
 
     # Adds a query string query to the criteria while using AND as the default
-    # operator unless otherwise specified. Check out the ElasticSearch docs
+    # operator unless otherwise specified. Check out the Elasticsearch docs
     # for further details.
     #
     # @example
@@ -158,6 +158,8 @@ module SearchFlip
     # @return [SearchFlip::Criteria] A newly created extended criteria
 
     def should(*args)
+      warn "[DEPRECATION] should will change in search_flip 3. Please use .must(bool: { should: ... }) until release."
+
       fresh.tap do |criteria|
         criteria.should_values = (should_values || []) + args
       end
@@ -166,7 +168,7 @@ module SearchFlip
     # Adds a range filter to the criteria without being forced to specify the
     # left and right end of the range, such that you can eg simply specify lt,
     # lte, gt and gte. For fully specified ranges, you can as well use #where,
-    # etc. Check out the ElasticSearch docs for further details regarding the
+    # etc. Check out the Elasticsearch docs for further details regarding the
     # range filter.
     #
     # @example
@@ -184,7 +186,7 @@ module SearchFlip
 
     # Adds a match all filter/query to the criteria, which simply matches all
     # documents. This can be eg be used within filter aggregations or for
-    # filter chaining. Check out the ElasticSearch docs for further details.
+    # filter chaining. Check out the Elasticsearch docs for further details.
     #
     # @example Basic usage
     #   CommentIndex.match_all

data/lib/search_flip/http_client.rb

@@ -4,7 +4,7 @@ module SearchFlip
   #
   # The SearchFlip::HTTPClient class wraps the http gem, is for internal use
   # and responsible for the http request/response handling, ie communicating
-  # with ElasticSearch.
+  # with Elasticsearch.
 
   class HTTPClient
     attr_accessor :request

data/lib/search_flip/index.rb

@@ -1,10 +1,10 @@
 
 module SearchFlip
   # The SearchFlip::Index mixin makes your class correspond to an
-  # ElasticSearch index. Your class can then create or delete the index, modify
+  # Elasticsearch index. Your class can then create or delete the index, modify
   # the mapping, import records, delete records and query the index. This gem
-  # uses an individual ElasticSearch index for each index class, because
-  # ElasticSearch requires to have the same mapping for the same field name,
+  # uses an individual Elasticsearch index for each index class, because
+  # Elasticsearch requires to have the same mapping for the same field name,
   # even if the field is living in different types of the same index.
   #
   # @example Simple index class
@@ -255,11 +255,11 @@ module SearchFlip
         :page, :per, :search, :highlight, :suggest, :custom, :find_in_batches, :find_results_in_batches,
         :find_each, :find_each_result, :failsafe, :total_entries, :total_count, :timeout, :terminate_after,
         :records, :results, :should, :should_not, :must, :must_not, :preference, :search_type, :routing,
-        :track_total_hits
+        :track_total_hits, :explain
 
-      # Override to specify the type name used within ElasticSearch. Recap,
+      # Override to specify the type name used within Elasticsearch. Recap,
       # this gem uses an individual index for each index class, because
-      # ElasticSearch requires to have the same mapping for the same field
+      # Elasticsearch requires to have the same mapping for the same field
       # name, even if the field is living in different types of the same index.
       #
       # @return [String] The name used for the type within the index
@@ -268,7 +268,7 @@ module SearchFlip
         "_doc"
       end
 
-      # Returns the base name of the index within ElasticSearch, ie the index
+      # Returns the base name of the index within Elasticsearch, ie the index
       # name without prefix.
       #
       # @return [String] The base name of the index, ie without prefix
@@ -279,7 +279,7 @@ module SearchFlip
 
       # @api private
       #
-      # Returns the full name of the index within ElasticSearch, ie with prefix
+      # Returns the full name of the index within Elasticsearch, ie with prefix
       # specified via SearchFlip::Config[:index_prefix].
       #
       # @return [String] The full index name
@@ -307,7 +307,7 @@ module SearchFlip
         {}
       end
 
-      # Returns whether or not the associated ElasticSearch index already
+      # Returns whether or not the associated Elasticsearch index already
       # exists.
       #
       # @return [Boolean] Whether or not the index exists
@@ -316,7 +316,7 @@ module SearchFlip
         connection.index_exists?(index_name_with_prefix)
       end
 
-      # Fetches the index settings from ElasticSearch. Sends a GET request to
+      # Fetches the index settings from Elasticsearch. Sends a GET request to
       # index_url/_settings. Raises SearchFlip::ResponseError in case any
       # errors occur.
       #
@@ -326,7 +326,7 @@ module SearchFlip
         connection.get_index_settings(index_name_with_prefix)
       end
 
-      # Creates the index within ElasticSearch and applies index settings, if
+      # Creates the index within Elasticsearch and applies index settings, if
       # specified. Raises SearchFlip::ResponseError in case any errors
       # occur.
       #
@@ -336,7 +336,7 @@ module SearchFlip
         connection.create_index(index_name_with_prefix, index_settings)
       end
 
-      # Closes the index within ElasticSearch. Raises SearchFlip::ResponseError
+      # Closes the index within Elasticsearch. Raises SearchFlip::ResponseError
       # in case any errors occur.
       #
       # @return [Boolean] Returns true or raises SearchFlip::ResponseError
@@ -345,7 +345,7 @@ module SearchFlip
         connection.close_index(index_name_with_prefix)
       end
 
-      # Opens the index within ElasticSearch. Raises SearchFlip::ResponseError
+      # Opens the index within Elasticsearch. Raises SearchFlip::ResponseError
       # in case any errors occur.
       #
       # @return [Boolean] Returns true or raises SearchFlip::ResponseError
@@ -354,7 +354,7 @@ module SearchFlip
         connection.open_index(index_name_with_prefix)
       end
 
-      # Updates the index settings within ElasticSearch according to the index
+      # Updates the index settings within Elasticsearch according to the index
       # settings specified. Raises SearchFlip::ResponseError in case any
       # errors occur.
       #
@@ -364,7 +364,7 @@ module SearchFlip
         connection.update_index_settings(index_name_with_prefix, index_settings)
       end
 
-      # Deletes the index from ElasticSearch. Raises SearchFlip::ResponseError
+      # Deletes the index from Elasticsearch. Raises SearchFlip::ResponseError
       # in case any errors occur.
 
       def delete_index
@@ -389,7 +389,7 @@ module SearchFlip
         {}
       end
 
-      # Updates the type mapping within ElasticSearch according to the mapping
+      # Updates the type mapping within Elasticsearch according to the mapping
       # currently specified. Raises SearchFlip::ResponseError in case any
       # errors occur.
 
@@ -401,7 +401,7 @@ module SearchFlip
         end
       end
 
-      # Retrieves the current type mapping from ElasticSearch. Raises
+      # Retrieves the current type mapping from Elasticsearch. Raises
       # SearchFlip::ResponseError in case any errors occur.
       #
       # @return [Hash] The current type mapping
@@ -424,7 +424,7 @@ module SearchFlip
         type_name != "_doc" || connection.version.to_i < 7
       end
 
-      # Retrieves the document specified by id from ElasticSearch. Raises
+      # Retrieves the document specified by id from Elasticsearch. Raises
       # SearchFlip::ResponseError specific exceptions in case any errors
       # occur.
       #
@@ -457,7 +457,7 @@ module SearchFlip
         connection.http_client.headers(accept: "application/json").post("#{type_url}/_mget", json: request, params: params).parse
       end
 
-      # Sends an analyze request to ElasticSearch. Raises
+      # Sends an analyze request to Elasticsearch. Raises
       # SearchFlip::ResponseError in case any errors occur.
       #
       # @example
@@ -469,7 +469,7 @@ module SearchFlip
         connection.http_client.headers(accept: "application/json").post("#{index_url}/_analyze", json: request, params: params).parse
       end
 
-      # Sends a index refresh request to ElasticSearch. Raises
+      # Sends a index refresh request to Elasticsearch. Raises
       # SearchFlip::ResponseError in case any errors occur.
 
       def refresh
@@ -487,7 +487,7 @@ module SearchFlip
 
       # Indexes the given record set, array of records or individual record. A
       # record set usually is an ActiveRecord::Relation, but can be any other
-      # ORM as well. Uses the ElasticSearch bulk API no matter what is
+      # ORM as well. Uses the Elasticsearch bulk API no matter what is
       # provided. Refreshes the index if auto_refresh is enabled. Raises
       # SearchFlip::ResponseError in case any errors occur.
       #
@@ -525,9 +525,9 @@ module SearchFlip
       end
 
       # Indexes the given record set, array of records or individual record
-      # using ElasticSearch's create operation via the Bulk API, such that the
+      # using Elasticsearch's create operation via the Bulk API, such that the
       # request will fail if a record with a particular primary key already
-      # exists in ElasticSearch.
+      # exists in Elasticsearch.
       #
       # @see #index See #index for more details regarding available
       #   params and return values
@@ -543,9 +543,9 @@ module SearchFlip
       end
 
       # Indexes the given record set, array of records or individual record
-      # using ElasticSearch's update operation via the Bulk API, such that the
+      # using Elasticsearch's update operation via the Bulk API, such that the
       # request will fail if a record you want to update does not already exist
-      # in ElasticSearch.
+      # in Elasticsearch.
       #
       # @see #index See #index for more details regarding available
       #   params and return values
@@ -561,7 +561,7 @@ module SearchFlip
       end
 
       # Deletes the given record set, array of records or individual record
-      # from ElasticSearch using the Bulk API.
+      # from Elasticsearch using the Bulk API.
       #
       # @see #index See #index for more details regarding available
       #   params and return values
@@ -615,19 +615,19 @@ module SearchFlip
         refresh if SearchFlip::Config[:auto_refresh]
       end
 
-      # Returns the full ElasticSearch type URL, ie base URL, index name with
+      # Returns the full Elasticsearch type URL, ie base URL, index name with
       # prefix and type name.
       #
-      # @return [String] The ElasticSearch type URL
+      # @return [String] The Elasticsearch type URL
 
       def type_url
         connection.type_url(index_name_with_prefix, type_name)
       end
 
-      # Returns the ElasticSearch index URL, ie base URL and index name with
+      # Returns the Elasticsearch index URL, ie base URL and index name with
       # prefix.
       #
-      # @return [String] The ElasticSearch index URL
+      # @return [String] The Elasticsearch index URL
 
       def index_url
         connection.index_url(index_name_with_prefix)