search_flip 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cda3eb59fdf7fabf986510c923cbded7f6a1219d734be60a406265d7ec685893
-  data.tar.gz: a30be3c6195e1864b4a37899e079e096129692ec0bb5ac0f78a0cceaf15468a2
+  metadata.gz: b506132a3198cb96d7afad2e2a6b7b3eb3af73bdb18452459045379d4dde41bc
+  data.tar.gz: 31354cd6f2f715529351fb74e1577382f7c245e381d95f411bbbb1c0a0aeef1d
 SHA512:
-  metadata.gz: df70d9f06aecbd84e7a5cb1ec16ffdd408a53da7a08f15fac4761a2e70b38b667ee4688abe7d81195eb6389e6decf2b591689a7002b75ca28cae16f8fa5bb88b
-  data.tar.gz: f903399ac8baa4b4a41ebcf3d378b64fbae236a553dc975b90b3c13a9b50e39bdbc6508a6098884510205ae42a55bf057a94f2fa73a4906a5d053d4f86ac7ba8
+  metadata.gz: 6da9d91a867a2e50cd9ca3abb4784e41019a9980e3c78a6e55c1297190666a2e9bf6b7d0d43aa5431b1252eba5eb3de68d40491377788db4c09dc40579318ed2
+  data.tar.gz: e9be5d2dd82077f093eb07550cdf469d2aba1dfc8f205c26d96ae95e4cbe0be7d0e36b1bc44f9667a3151212cfb949761ef8fe8f8c5fd2a11cc7b10a8d29948e

data/README.md

@@ -1,5 +1,5 @@
 
-# SearchFlip
+# search_flip
 
 **Full-Featured ElasticSearch Ruby Client with a Chainable DSL**
 
@@ -235,11 +235,17 @@ CommentIndex.where(username: "mrkamel").total_entries
 CommentIndex.aggregate(:username).aggregations(:username)
 # => {1=>#<SearchFlip::Result doc_count=37 ...>, 2=>... }
 ...
+```
+
+Please note that you can check the request that will be send to Elasticsearch
+by simply calling `#request` on the query:
 
+```ruby
 CommentIndex.search("hello world").sort(id: "desc").aggregate(:username).request
 # => {:query=>{:bool=>{:must=>[{:query_string=>{:query=>"hello world", :default_operator=>:AND}}]}}, ...}
 ```
 
+
 delete records:
 
 ```ruby
@@ -292,7 +298,7 @@ within `update_aliases`.
 Please note that `with_settings(index_name: '...')` returns an anonymous, i.e.
 temporary, class inherting from UserIndex and overwriting `index_name`.
 
-## Advanced Usage
+## Chainable Methods
 
 SearchFlip supports even more advanced usages, like e.g. post filters, filtered
 aggregations or nested aggregations via simple to use API methods.
@@ -303,8 +309,7 @@ SearchFlip provides powerful methods to query/filter Elasticsearch:
 
 * `where`
 
-Feels like ActiveRecord's `where` and performs a bool filter clause
-to the request:
+Feels like ActiveRecord's `where` and adds a bool filter clause to the request:
 
 ```ruby
 CommentIndex.where(reviewed: true)
@@ -371,13 +376,14 @@ CommentIndex.must_not(term: { state: "approved" })
 
 * `search`
 
-Adds a query string query, with AND as default filter:
+Adds a query string query, with AND as default operator:
 
 ```ruby
-CommentIndex.search("harry potter")
+CommentIndex.search("hello world")
 CommentIndex.search("state:approved")
 CommentIndex.search("username:a*")
 CommentIndex.search("state:approved OR state:rejected")
+CommentIndex.search("hello world", default_operator: "OR")
 ```
 
 * `exists`
@@ -430,9 +436,9 @@ query = OrderIndex.aggregate(:username, order: { revenue: "desc" }) do |aggregat
 end
 ```
 
-Generally, aggregation results returned by ElasticSearch are wrapped in a
-`SearchFlip::Result`, which wraps a `Hashie::Mash`such that you can access them
-via:
+Generally, aggregation results returned by ElasticSearch are returned as a
+`SearchFlip::Result`, which basically is `Hashie::Mash`such that you can access
+them via:
 
 ```ruby
 query.aggregations(:username)["mrkamel"].revenue.value
@@ -488,8 +494,8 @@ query.results[0]._hit.highlight.title # => "<em>hello</em> world"
 
 ### Other Criteria Methods
 
-There are so many chainable criteria methods to make your life easier.
-For a full list, checkout the reference docs.
+There are even more chainable criteria methods to make your life easier. For a
+full list, checkout the reference docs.
 
 * `source`
 
@@ -512,21 +518,6 @@ CommentIndex.paginate(page: 3, per_page: 50)
 CommentIndex.page(3).per(50)
 ```
 
-* `scroll`
-
-You can as well use the underlying scroll API directly, ie. without using higher
-level pagination:
-
-```ruby
-query = CommentIndex.scroll(timeout: "5m")
-
-until query.records.empty?
-  # ...
-
-  query = query.scroll(id: query.scroll_id, timeout: "5m")
-end
-```
-
 * `profile`
 
 Use `#profile` to enable query profiling:
@@ -577,8 +568,8 @@ end
 
 * `find_results_in_batches`
 
-Used like `find_in_batches`, but yielding the raw results instead of database
-records. Again, the batch size and scroll API timeout can be specified.
+Used like `find_in_batches`, but yielding the raw results (as
+`SearchFlip::Result` objects) instead of database records.
 
 ```ruby
 CommentIndex.search("hello world").find_results_in_batches(batch_size: 100) do |batch|
@@ -588,8 +579,7 @@ end
 
 * `find_each`
 
-Like `#find_in_batches`, use `#find_each` to fetch records in batches, but yields
-one record at a time.
+Like `#find_in_batches` but yielding one record at a time.
 
 ```ruby
 CommentIndex.search("hello world").find_each(batch_size: 100) do |record|
@@ -597,6 +587,31 @@ CommentIndex.search("hello world").find_each(batch_size: 100) do |record|
 end
 ```
 
+* `find_each_result`
+
+Like `#find_results_in_batches`, but yielding one record at a time.
+
+```ruby
+CommentIndex.search("hello world").find_each_result(batch_size: 100) do |batch|
+  # ...
+end
+```
+
+* `scroll`
+
+You can as well use the underlying scroll API directly, ie. without using higher
+level scrolling:
+
+```ruby
+query = CommentIndex.scroll(timeout: "5m")
+
+until query.records.empty?
+  # ...
+
+  query = query.scroll(id: query.scroll_id, timeout: "5m")
+end
+```
+
 * `failsafe`
 
 Use `#failsafe` to prevent any exceptions from being raised for query string
@@ -622,14 +637,6 @@ CommentIndex.where(approved: true).merge(CommentIndex.search("hello"))
 # equivalent to: CommentIndex.where(approved: true).search("hello")
 ```
 
-* `unscope`
-
-You can even remove certain already added scopes via `#unscope`:
-
-```ruby
-CommentIndex.aggregate(:username).search("hello world").unscope(:search, :aggregate)
-```
-
 * `timeout`
 
 Specify a timeout to limit query processing time:
@@ -649,6 +656,33 @@ CommentIndex.terminate_after(10).execute
 
 For further details and a full list of methods, check out the reference docs.
 
+* `custom`
+
+You can add a custom clause to the request via `custom`
+
+```ruby
+CommentIndex.custom(custom_clause: '...')
+```
+
+This can be useful for Elasticsearch features not yet supported via criteria
+methods by SearchFlip, custom plugin clauses, etc.
+
+### Custom Criteria Methods
+
+To add custom criteria methods, you can add class methods to your index class.
+
+```ruby
+class HotelIndex
+  # ...
+
+  def self.where_geo(lat:, lon:, distance:)
+    filter(geo_distance: { distance: distance, location: { lat: lat, lon: lon } })
+  end
+end
+
+HotelIndex.search("bed and breakfast").where_geo(lat: 53.57532, lon: 10.01534, distance: '50km').aggregate(:rating)
+```
+
 ## Using multiple Elasticsearch clusters
 
 To use multiple Elasticsearch clusters, specify a connection within your
@@ -669,6 +703,26 @@ end
 This allows to use different clusters per index e.g. when migrating indices to
 new versions of Elasticsearch.
 
+You can specify basic auth, additional headers, etc via:
+
+```ruby
+http_client = SearchFlip::HTTPClient.new
+
+# Basic Auth
+http_client = http_client.basic_auth(user: "username", pass: "password")
+
+# Raw Auth Header
+http_client = http_client.auth("Bearer VGhlIEhUVFAgR2VtLCBST0NLUw")
+
+# Proxy Settings
+http_client = http_client.via("proxy.host", 8080)
+
+# Custom headers
+http_client = http_client.headers(key: "value")
+
+SearchFlip::Connection.new(base_url: "...", http_client: http_client)
+```
+
 ## Routing and other index-time options
 
 Override `index_options` in case you want to use routing or pass other
@@ -712,8 +766,9 @@ class MyIndex
 end
 ```
 
-Thus, simply add your custom implementation of those methods that work with
-whatever ORM you use.
+Thus, if your ORM supports `.find_each`, `#id` and `#where` you are already
+good to go. Otherwise, simply add your custom implementation of those methods
+that work with whatever ORM you use.
 
 ## Date and Timestamps in JSON
 
@@ -764,10 +819,11 @@ require "search_flip/to_json"
 
 ## Feature Support
 
-* `#post_search` and `#profile` are only supported from up to ElasticSearch
+* `#post_search` and `#profile` are only supported from up to Elasticsearch
   version >= 2.
-* for ElasticSearch 2.x, the delete-by-query plugin is required to delete
+* for Elasticsearch 2.x, the delete-by-query plugin is required to delete
   records via queries
+* `#track_total_hits` is only available with Elasticsearch >= 7
 
 ## Keeping your Models and Indices in Sync
 

data/UPDATING.md

@@ -3,7 +3,7 @@
 
 ## Update 1.x to 2.x
 
-* **[BREAKING]** No longer include the mapping in `SearchFlip::Index.mapping`
+* **[BREAKING]** No longer include the `type_name` in `SearchFlip::Index.mapping`
 
 1.x:
 

data/lib/search_flip/criteria.rb

@@ -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
+      :search_type_value, :routing_value, :track_total_hits_value
 
     # Creates a new criteria while merging the attributes (constraints,
     # settings, etc) of the current criteria with the attributes of another one
@@ -51,6 +51,7 @@ module SearchFlip
         criteria.preference_value = other.preference_value if other.preference_value
         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.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
@@ -74,6 +75,23 @@ module SearchFlip
       end
     end
 
+    # Specifies if or how many hits should be counted/tracked. Check out the
+    # elasticsearch docs for futher details.
+    #
+    # @example
+    #   CommentIndex.track_total_hits(true)
+    #   CommentIndex.track_total_hits(10_000)
+    #
+    # @param value The value for track_total_hits
+    #
+    # @return [SearchFlip::Criteria] A newly created extended criteria
+
+    def track_total_hits(value)
+      fresh.tap do |criteria|
+        criteria.track_total_hits_value = value
+      end
+    end
+
     # Specifies a preference value for the request. Check out the elasticsearch
     # docs for further details.
     #
@@ -167,6 +185,8 @@ module SearchFlip
     # @return [SearchFlip::Criteria] A newly created extended criteria
 
     def unscope(*scopes)
+      warn "[DEPRECATION] unscope is deprecated"
+
       unknown = scopes - [:search, :post_search, :sort, :highlight, :suggest, :custom, :aggregate]
 
       raise(ArgumentError, "Can't unscope #{unknown.join(", ")}") if unknown.size > 0
@@ -260,6 +280,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[:timeout] = timeout_value if timeout_value
       res[:terminate_after] = terminate_after_value if terminate_after_value
       res[:highlight] = highlight_values if highlight_values

data/lib/search_flip/index.rb

@@ -254,7 +254,8 @@ module SearchFlip
         :includes, :eager_load, :preload, :sort, :resort, :order, :reorder, :offset, :limit, :paginate,
         :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
+        :records, :results, :should, :should_not, :must, :must_not, :preference, :search_type, :routing,
+        :track_total_hits
 
       # Override to specify the type name used within ElasticSearch. Recap,
       # this gem uses an individual index for each index class, because

data/lib/search_flip/version.rb

@@ -1,5 +1,5 @@
 
 module SearchFlip
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 end
 

data/logo.svg

@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Generated by IcoMoon.io -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   version="1.1"
+   width="300"
+   height="50"
+   viewBox="0 0 299.99998 50"
+   id="svg4869"
+   sodipodi:docname="logo.svg"
+   inkscape:export-filename="/home/hkf/projects/search_flip/logo.png"
+   inkscape:export-xdpi="299.34824"
+   inkscape:export-ydpi="299.34824"
+   inkscape:version="0.92.1 r15371">
+  <metadata
+     id="metadata4875">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title>arrow-long-up</dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs4873" />
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1920"
+     inkscape:window-height="971"
+     id="namedview4871"
+     showgrid="false"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0"
+     inkscape:zoom="2.085965"
+     inkscape:cx="91.987216"
+     inkscape:cy="-41.606043"
+     inkscape:window-x="0"
+     inkscape:window-y="31"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg4869" />
+  <title
+     id="title4865">arrow-long-up</title>
+  <path
+     d="M 39.922489,4.151999 36.230955,18.361869 32.37339,14.504302 10.209748,36.667943 7.4576271,33.915823 29.621268,11.75218 25.712619,7.843531 Z"
+     id="path4867"
+     inkscape:connector-curvature="0"
+     style="stroke-width:1.80568123"
+     inkscape:export-xdpi="325.4834"
+     inkscape:export-ydpi="325.4834"
+     sodipodi:nodetypes="cccccccc"
+     inkscape:export-filename="/home/hkf/projects/search_flip/text4908.png" />
+  <path
+     d="M 17.625202,45.376517 31.473864,41.323778 27.948317,37.696072 50.111962,15.532428 47.418207,12.940838 25.254566,35.10448 21.677941,31.527854 Z"
+     id="path4867-7"
+     inkscape:connector-curvature="0"
+     style="stroke-width:1.74257004"
+     inkscape:export-xdpi="325.4834"
+     inkscape:export-ydpi="325.4834"
+     sodipodi:nodetypes="cccccccc"
+     inkscape:export-filename="/home/hkf/projects/search_flip/text4908.png" />
+  <text
+     xml:space="preserve"
+     style="font-style:normal;font-weight:normal;font-size:96.44345093px;line-height:1.25;font-family:sans-serif;letter-spacing:-0.65099335px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:2.41108632"
+     x="59.037937"
+     y="37.501484"
+     id="text4908"
+     inkscape:export-filename="/home/hkf/projects/search_flip/text4908.png"
+     inkscape:export-xdpi="325.4834"
+     inkscape:export-ydpi="325.4834"
+     inkscape:transform-center-x="-2.0432889"
+     inkscape:transform-center-y="-9.8078108"><tspan
+       sodipodi:role="line"
+       id="tspan4906"
+       x="59.037937"
+       y="37.501484"
+       style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:51.43650818px;line-height:6;font-family:'times new roman';-inkscape-font-specification:'times new roman, ';letter-spacing:0px;word-spacing:-19.48158455px;stroke-width:2.41108632">search_flip</tspan></text>
+</svg>

data/spec/search_flip/criteria_spec.rb

@@ -36,7 +36,7 @@ RSpec.describe SearchFlip::Criteria do
       methods = [
         :profile_value, :failsafe_value, :terminate_after_value, :timeout_value,
         :offset_value, :limit_value, :scroll_args, :source_value, :preference_value,
-        :search_type_value, :routing_value
+        :search_type_value, :routing_value, :track_total_hits_value
       ]
 
       methods.each do |method|
@@ -1025,6 +1025,16 @@ RSpec.describe SearchFlip::Criteria do
     end
   end
 
+  describe "#track_total_hits" do
+    it "is added to the request" do
+      if ProductIndex.connection.version.to_i >= 7
+        query = ProductIndex.track_total_hits(false)
+        expect(query.request[:track_total_hits]).to eq(false)
+        expect { query.execute }.not_to raise_error
+      end
+    end
+  end
+
   describe "#custom" do
     it "adds a custom entry to the request" do
       request = ProductIndex.custom(custom_key: "custom_value").request

data/spec/search_flip/index_spec.rb

@@ -14,7 +14,8 @@ RSpec.describe SearchFlip::Index do
       :find_in_batches, :highlight, :suggest, :custom, :find_each, :failsafe,
       :total_entries, :total_count, :terminate_after, :timeout, :records, :results,
       :should, :should_not, :must, :must_not, :find_each_result,
-      :find_results_in_batches, :preference, :search_type, :routing
+      :find_results_in_batches, :preference, :search_type, :routing,
+      :track_total_hits
     ]
 
     methods.each do |method|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: search_flip
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Benjamin Vetter
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-10 00:00:00.000000000 Z
+date: 2019-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -199,6 +199,7 @@ files:
 - lib/search_flip/result.rb
 - lib/search_flip/to_json.rb
 - lib/search_flip/version.rb
+- logo.svg
 - search_flip.gemspec
 - spec/delegate_matcher.rb
 - spec/search_flip/aggregation_spec.rb