searchkick 5.0.1 → 5.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab19b7696cc775bda54eef31aaf9fea04a13a3027335440023f58f0c3b761fa0
-  data.tar.gz: 461f230a62f440e84684e9eb42cc85d307b726830eba80999c5648aef13de92e
+  metadata.gz: 89c6a97d4c898be7f1f494cc4bfafc8aed5acc202a855588e81f73d86ea7b123
+  data.tar.gz: c362bb2916ec0b1fa83d72efd2314e747077b5cd696ed2ece089204be9452010
 SHA512:
-  metadata.gz: 5382e2de584271fc9f80802f858329c613f3b9aff7877c9bb9653dab550deb6ed1ac6971cbb2bc306f4d6e67056f16ee98eea04d69f2fd9ff15fd899e37f8962
-  data.tar.gz: dd8121e4991c9aaad5cd331cdc3adef3c703ee47abf8238ea3cc6feb1b1e5dcd85cb59c9f7ce91c086644d5946c5ccba936f48d0bc27988a59cca81adf161bb3
+  metadata.gz: bf1a9191ee97a19afde4c44b84c02b34b7f6b8b3ac464cdd34671dd60cb8a191ec338a028db8221c2a502fadf0059987f957c918221175631e8aa70344371ee7
+  data.tar.gz: 32e7b4b9f0899088e709a77389d8fa845ef68a3fd819d3823229eb1ffd99a6121647d5ab82d209e6254e4c242530d7698441d3b97f65a1e2436acbced6b6086f

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 5.0.4 (2022-06-16)
+
+- Added `max_result_window` option
+- Improved error message for unsupported versions of Elasticsearch
+
+## 5.0.3 (2022-03-13)
+
+- Fixed context for index name for inherited models
+
+## 5.0.2 (2022-03-03)
+
+- Fixed index name for inherited models
+
 ## 5.0.1 (2022-02-27)
 
 - Prefer `mode: :async` over `async: true` for full reindex

data/README.md

@@ -50,8 +50,8 @@ Searchkick 5.0 was recently released! See [how to upgrade](#upgrading)
 Install [Elasticsearch](https://www.elastic.co/downloads/elasticsearch) or [OpenSearch](https://opensearch.org/downloads.html). For Homebrew, use:
 
 ```sh
-brew install elasticsearch
-brew services start elasticsearch
+brew install elastic/tap/elasticsearch-full
+brew services start elasticsearch-full
 # or
 brew install opensearch
 brew services start opensearch
@@ -66,7 +66,7 @@ gem "elasticsearch"   # select one
 gem "opensearch-ruby" # select one
 ```
 
-The latest version works with Elasticsearch 7 and 8 and OpenSearch 1. For Elasticsearch 6, use version 4.6.3 and [this readme](https://github.com/ankane/searchkick/blob/v4.6.3/README.md).
+The latest version works with Elasticsearch 7 and 8 and OpenSearch 1 and 2. For Elasticsearch 6, use version 4.6.3 and [this readme](https://github.com/ankane/searchkick/blob/v4.6.3/README.md).
 
 Add searchkick to models you want to search.
 
@@ -98,7 +98,7 @@ Searchkick supports the complete [Elasticsearch Search API](https://www.elastic.
 Query like SQL
 
 ```ruby
-Product.search "apples", where: {in_stock: true}, limit: 10, offset: 50
+Product.search("apples", where: {in_stock: true}, limit: 10, offset: 50)
 ```
 
 Search specific fields
@@ -226,7 +226,7 @@ You can also boost by:
 Use a `*` for the query.
 
 ```ruby
-Product.search "*"
+Product.search("*")
 ```
 
 ### Pagination
@@ -235,7 +235,7 @@ Plays nicely with kaminari and will_paginate.
 
 ```ruby
 # controller
-@products = Product.search "milk", page: params[:page], per_page: 20
+@products = Product.search("milk", page: params[:page], per_page: 20)
 ```
 
 View with kaminari
@@ -255,13 +255,13 @@ View with will_paginate
 By default, results must match all words in the query.
 
 ```ruby
-Product.search "fresh honey" # fresh AND honey
+Product.search("fresh honey") # fresh AND honey
 ```
 
 To change this, use:
 
 ```ruby
-Product.search "fresh honey", operator: "or" # fresh OR honey
+Product.search("fresh honey", operator: "or") # fresh OR honey
 ```
 
 By default, results must match the entire word - `back` will not match `backpack`. You can change this behavior with:
@@ -275,7 +275,7 @@ end
 And to search (after you reindex):
 
 ```ruby
-Product.search "back", fields: [:name], match: :word_start
+Product.search("back", fields: [:name], match: :word_start)
 ```
 
 Available options are:
@@ -297,7 +297,7 @@ The default is `:word`. The most matches will happen with `:word_middle`.
 To match a field exactly (case-sensitive), use:
 
 ```ruby
-User.search query, fields: [{email: :exact}, :name]
+Product.search(query, fields: [{email: :exact}, :name])
 ```
 
 ### Phrase Matches
@@ -305,7 +305,7 @@ User.search query, fields: [{email: :exact}, :name]
 To only match the exact order, use:
 
 ```ruby
-User.search "fresh honey", match: :phrase
+Product.search("fresh honey", match: :phrase)
 ```
 
 ### Stemming and Language
@@ -426,7 +426,7 @@ end
 Search with:
 
 ```ruby
-Product.search query, fields: [:name_tagged]
+Product.search(query, fields: [:name_tagged])
 ```
 
 ### Misspellings
@@ -436,13 +436,13 @@ By default, Searchkick handles misspelled queries by returning results with an [
 You can change this with:
 
 ```ruby
-Product.search "zucini", misspellings: {edit_distance: 2} # zucchini
+Product.search("zucini", misspellings: {edit_distance: 2}) # zucchini
 ```
 
 To prevent poor precision and improve performance for correctly spelled queries (which should be a majority for most applications), Searchkick can first perform a search without misspellings, and if there are too few results, perform another with them.
 
 ```ruby
-Product.search "zuchini", misspellings: {below: 5}
+Product.search("zuchini", misspellings: {below: 5})
 ```
 
 If there are fewer than 5 results, a 2nd search is performed with misspellings enabled. The result of this query is returned.
@@ -450,13 +450,13 @@ If there are fewer than 5 results, a 2nd search is performed with misspellings e
 Turn off misspellings with:
 
 ```ruby
-Product.search "zuchini", misspellings: false # no zucchini
+Product.search("zuchini", misspellings: false) # no zucchini
 ```
 
 Specify which fields can include misspellings with:
 
 ```ruby
-Product.search "zucini", fields: [:name, :color], misspellings: {fields: [:name]}
+Product.search("zucini", fields: [:name, :color], misspellings: {fields: [:name]})
 ```
 
 > When doing this, you must also specify fields to search
@@ -466,7 +466,7 @@ Product.search "zucini", fields: [:name, :color], misspellings: {fields: [:name]
 If a user searches `butter`, they may also get results for `peanut butter`. To prevent this, use:
 
 ```ruby
-Product.search "butter", exclude: ["peanut butter"]
+Product.search("butter", exclude: ["peanut butter"])
 ```
 
 You can map queries and terms to exclude with:
@@ -477,7 +477,7 @@ exclude_queries = {
   "cream" => ["ice cream", "whipped cream"]
 }
 
-Product.search query, exclude: exclude_queries[query]
+Product.search(query, exclude: exclude_queries[query])
 ```
 
 You can demote results by boosting by a factor less than one:
@@ -499,7 +499,7 @@ gem "gemoji-parser"
 And use:
 
 ```ruby
-Product.search "🍨🍰", emoji: true
+Product.search("🍨🍰", emoji: true)
 ```
 
 ## Indexing
@@ -592,6 +592,14 @@ There are four strategies for keeping the index synced with your database.
   end
   ```
 
+  And reindex a record or relation manually.
+
+  ```ruby
+  product.reindex
+  # or
+  store.products.reindex(mode: :async)
+  ```
+
 You can also do bulk updates.
 
 ```ruby
@@ -608,6 +616,12 @@ Searchkick.callbacks(false) do
 end
 ```
 
+Or override the model’s strategy.
+
+```ruby
+product.reindex(mode: :async) # :inline or :queue
+```
+
 ### Associations
 
 Data is **not** automatically synced when an association is updated. If this is desired, add a callback to reindex:
@@ -651,23 +665,19 @@ end
 The best starting point to improve your search **by far** is to track searches and conversions. [Searchjoy](https://github.com/ankane/searchjoy) makes it easy.
 
 ```ruby
-Product.search "apple", track: {user_id: current_user.id}
+Product.search("apple", track: {user_id: current_user.id})
 ```
 
-[See the docs](https://github.com/ankane/searchjoy) for how to install and use.
-
-Focus on:
-
-- top searches with low conversions
-- top searches with no results
+[See the docs](https://github.com/ankane/searchjoy) for how to install and use. Focus on top searches with a low conversion rate.
 
-Searchkick can then use the conversion data to learn what users are looking for. If a user searches for “ice cream” and adds Ben & Jerry’s Chunky Monkey to the cart (our conversion metric at Instacart), that item gets a little more weight for similar searches.
+Searchkick can then use the conversion data to learn what users are looking for. If a user searches for “ice cream” and adds Ben & Jerry’s Chunky Monkey to the cart (our conversion metric at Instacart), that item gets a little more weight for similar searches. This can make a huge difference on the quality of your search.
 
 Add conversion data with:
 
 ```ruby
 class Product < ApplicationRecord
-  has_many :searches, class_name: "Searchjoy::Search", as: :convertable
+  has_many :conversions, class_name: "Searchjoy::Conversion", as: :convertable
+  has_many :searches, class_name: "Searchjoy::Search", through: :conversions
 
   searchkick conversions: [:conversions] # name of field
 
@@ -681,15 +691,100 @@ class Product < ApplicationRecord
 end
 ```
 
-Reindex and set up a cron job to add new conversions daily.
+Reindex and set up a cron job to add new conversions daily. For zero downtime deployment, temporarily set `conversions: false` in your search calls until the data is reindexed.
+
+### Performant Conversions
+
+A performant way to do conversions is to cache them to prevent N+1 queries. For Postgres, create a migration with:
+
+```ruby
+add_column :products, :search_conversions, :jsonb
+```
+
+For MySQL, use `:json`, and for others, use `:text` with a [JSON serializer](https://api.rubyonrails.org/classes/ActiveRecord/AttributeMethods/Serialization/ClassMethods.html).
+
+Next, update your model. Create a separate method for conversion data so you can use [partial reindexing](#partial-reindexing).
+
+```ruby
+class Product < ApplicationRecord
+  searchkick conversions: [:conversions]
+
+  def search_data
+    {
+      name: name,
+      category: category
+    }.merge(conversions_data)
+  end
+
+  def conversions_data
+    {
+      conversions: search_conversions || {}
+    }
+  end
+end
+```
+
+Deploy and reindex your data. For zero downtime deployment, temporarily set `conversions: false` in your search calls until the data is reindexed.
+
+```ruby
+Product.reindex
+```
+
+Then, create a job to update the conversions column and reindex records with new conversions. Here’s one you can use for Searchjoy:
+
+```ruby
+class UpdateConversionsJob < ApplicationJob
+  def perform(class_name, since: nil, update: true, reindex: true)
+    model = Searchkick.load_model(class_name)
+
+    # get records that have a recent conversion
+    recently_converted_ids =
+      Searchjoy::Conversion.where(convertable_type: class_name).where(created_at: since..)
+      .order(:convertable_id).distinct.pluck(:convertable_id)
+
+    # split into batches
+    recently_converted_ids.in_groups_of(1000, false) do |ids|
+      if update
+        # fetch conversions
+        conversions =
+          Searchjoy::Conversion.where(convertable_id: ids, convertable_type: class_name)
+          .joins(:search).where.not(searchjoy_searches: {user_id: nil})
+          .group(:convertable_id, :query).distinct.count(:user_id)
+
+        # group by record
+        conversions_by_record = {}
+        conversions.each do |(id, query), count|
+          (conversions_by_record[id] ||= {})[query] = count
+        end
+
+        # update conversions column
+        model.transaction do
+          conversions_by_record.each do |id, conversions|
+            model.where(id: id).update_all(search_conversions: conversions)
+          end
+        end
+      end
+
+      if reindex
+        # reindex conversions data
+        model.where(id: ids).reindex(:conversions_data)
+      end
+    end
+  end
+end
+```
+
+Run the job:
 
 ```ruby
-rake searchkick:reindex CLASS=Product
+UpdateConversionsJob.perform_now("Product")
 ```
 
-This can make a huge difference on the quality of your search.
+And set it up to run daily.
 
-For a more performant way to reindex conversion data, check out [performant conversions](#performant-conversions).
+```ruby
+UpdateConversionsJob.perform_later("Product", since: 1.day.ago)
+```
 
 ## Personalized Results
 
@@ -709,7 +804,7 @@ end
 Reindex and search with:
 
 ```ruby
-Product.search "milk", boost_where: {orderer_ids: current_user.id}
+Product.search("milk", boost_where: {orderer_ids: current_user.id})
 ```
 
 ## Instant Search / Autocomplete
@@ -733,7 +828,7 @@ end
 Reindex and search with:
 
 ```ruby
-Movie.search "jurassic pa", fields: [:title], match: :word_start
+Movie.search("jurassic pa", fields: [:title], match: :word_start)
 ```
 
 Typically, you want to use a JavaScript library like [typeahead.js](https://twitter.github.io/typeahead.js/) or [jQuery UI](https://jqueryui.com/autocomplete/).
@@ -793,7 +888,7 @@ end
 Reindex and search with:
 
 ```ruby
-products = Product.search "peantu butta", suggest: true
+products = Product.search("peantu butta", suggest: true)
 products.suggestions # ["peanut butter"]
 ```
 
@@ -804,40 +899,40 @@ products.suggestions # ["peanut butter"]
 ![Aggregations](https://gist.github.com/ankane/b6988db2802aca68a589b31e41b44195/raw/40febe948427e5bc53ec4e5dc248822855fef76f/facets.png)
 
 ```ruby
-products = Product.search "chuck taylor", aggs: [:product_type, :gender, :brand]
+products = Product.search("chuck taylor", aggs: [:product_type, :gender, :brand])
 products.aggs
 ```
 
 By default, `where` conditions apply to aggregations.
 
 ```ruby
-Product.search "wingtips", where: {color: "brandy"}, aggs: [:size]
+Product.search("wingtips", where: {color: "brandy"}, aggs: [:size])
 # aggregations for brandy wingtips are returned
 ```
 
 Change this with:
 
 ```ruby
-Product.search "wingtips", where: {color: "brandy"}, aggs: [:size], smart_aggs: false
+Product.search("wingtips", where: {color: "brandy"}, aggs: [:size], smart_aggs: false)
 # aggregations for all wingtips are returned
 ```
 
 Set `where` conditions for each aggregation separately with:
 
 ```ruby
-Product.search "wingtips", aggs: {size: {where: {color: "brandy"}}}
+Product.search("wingtips", aggs: {size: {where: {color: "brandy"}}})
 ```
 
 Limit
 
 ```ruby
-Product.search "apples", aggs: {store_id: {limit: 10}}
+Product.search("apples", aggs: {store_id: {limit: 10}})
 ```
 
 Order
 
 ```ruby
-Product.search "wingtips", aggs: {color: {order: {"_key" => "asc"}}} # alphabetically
+Product.search("wingtips", aggs: {color: {order: {"_key" => "asc"}}}) # alphabetically
 ```
 
 [All of these options are supported](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html#search-aggregations-bucket-terms-aggregation-order)
@@ -846,31 +941,31 @@ Ranges
 
 ```ruby
 price_ranges = [{to: 20}, {from: 20, to: 50}, {from: 50}]
-Product.search "*", aggs: {price: {ranges: price_ranges}}
+Product.search("*", aggs: {price: {ranges: price_ranges}})
 ```
 
 Minimum document count
 
 ```ruby
-Product.search "apples", aggs: {store_id: {min_doc_count: 2}}
+Product.search("apples", aggs: {store_id: {min_doc_count: 2}})
 ```
 
 Script support
 
 ```ruby
-Product.search "*", aggs: {color: {script: {source: "'Color: ' + _value"}}}
+Product.search("*", aggs: {color: {script: {source: "'Color: ' + _value"}}})
 ```
 
 Date histogram
 
 ```ruby
-Product.search "pear", aggs: {products_per_year: {date_histogram: {field: :created_at, interval: :year}}}
+Product.search("pear", aggs: {products_per_year: {date_histogram: {field: :created_at, interval: :year}}})
 ```
 
 For other aggregation types, including sub-aggregations, use `body_options`:
 
 ```ruby
-Product.search "orange", body_options: {aggs: {price: {histogram: {field: :price, interval: 10}}}}
+Product.search("orange", body_options: {aggs: {price: {histogram: {field: :price, interval: 10}}}})
 ```
 
 ## Highlight
@@ -878,7 +973,7 @@ Product.search "orange", body_options: {aggs: {price: {histogram: {field: :price
 Specify which fields to index with highlighting.
 
 ```ruby
-class Product < ApplicationRecord
+class Band < ApplicationRecord
   searchkick highlight: [:name]
 end
 ```
@@ -886,7 +981,7 @@ end
 Highlight the search query in the results.
 
 ```ruby
-bands = Band.search "cinema", highlight: true
+bands = Band.search("cinema", highlight: true)
 ```
 
 View the highlighted fields with:
@@ -900,19 +995,19 @@ end
 To change the tag, use:
 
 ```ruby
-Band.search "cinema", highlight: {tag: "<strong>"}
+Band.search("cinema", highlight: {tag: "<strong>"})
 ```
 
 To highlight and search different fields, use:
 
 ```ruby
-Band.search "cinema", fields: [:name], highlight: {fields: [:description]}
+Band.search("cinema", fields: [:name], highlight: {fields: [:description]})
 ```
 
 By default, the entire field is highlighted. To get small snippets instead, use:
 
 ```ruby
-bands = Band.search "cinema", highlight: {fragment_size: 20}
+bands = Band.search("cinema", highlight: {fragment_size: 20})
 bands.with_highlights(multiple: true).each do |band, highlights|
   highlights[:name].join(" and ")
 end
@@ -921,7 +1016,7 @@ end
 Additional options can be specified for each field:
 
 ```ruby
-Band.search "cinema", fields: [:name], highlight: {fields: {name: {fragment_size: 200}}}
+Band.search("cinema", fields: [:name], highlight: {fields: {name: {fragment_size: 200}}})
 ```
 
 You can find available highlight options in the [Elasticsearch reference](https://www.elastic.co/guide/en/elasticsearch/reference/current/highlighting.html).
@@ -950,13 +1045,13 @@ end
 Reindex and search with:
 
 ```ruby
-Restaurant.search "pizza", where: {location: {near: {lat: 37, lon: -114}, within: "100mi"}} # or 160km
+Restaurant.search("pizza", where: {location: {near: {lat: 37, lon: -114}, within: "100mi"}}) # or 160km
 ```
 
 Bounded by a box
 
 ```ruby
-Restaurant.search "sushi", where: {location: {top_left: {lat: 38, lon: -123}, bottom_right: {lat: 37, lon: -122}}}
+Restaurant.search("sushi", where: {location: {top_left: {lat: 38, lon: -123}, bottom_right: {lat: 37, lon: -122}}})
 ```
 
 **Note:** `top_right` and `bottom_left` also work
@@ -964,7 +1059,7 @@ Restaurant.search "sushi", where: {location: {top_left: {lat: 38, lon: -123}, bo
 Bounded by a polygon
 
 ```ruby
-Restaurant.search "dessert", where: {location: {geo_polygon: {points: [{lat: 38, lon: -123}, {lat: 39, lon: -123}, {lat: 37, lon: 122}]}}}
+Restaurant.search("dessert", where: {location: {geo_polygon: {points: [{lat: 38, lon: -123}, {lat: 39, lon: -123}, {lat: 37, lon: 122}]}}})
 ```
 
 ### Boost By Distance
@@ -972,13 +1067,13 @@ Restaurant.search "dessert", where: {location: {geo_polygon: {points: [{lat: 38,
 Boost results by distance - closer results are boosted more
 
 ```ruby
-Restaurant.search "noodles", boost_by_distance: {location: {origin: {lat: 37, lon: -122}}}
+Restaurant.search("noodles", boost_by_distance: {location: {origin: {lat: 37, lon: -122}}})
 ```
 
 Also supports [additional options](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-function-score-query.html#function-decay)
 
 ```ruby
-Restaurant.search "wings", boost_by_distance: {location: {origin: {lat: 37, lon: -122}, function: "linear", scale: "30mi", decay: 0.5}}
+Restaurant.search("wings", boost_by_distance: {location: {origin: {lat: 37, lon: -122}, function: "linear", scale: "30mi", decay: 0.5}})
 ```
 
 ### Geo Shapes
@@ -1005,19 +1100,19 @@ See the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsea
 Find shapes intersecting with the query shape
 
 ```ruby
-Restaurant.search "soup", where: {bounds: {geo_shape: {type: "polygon", coordinates: [[{lat: 38, lon: -123}, ...]]}}}
+Restaurant.search("soup", where: {bounds: {geo_shape: {type: "polygon", coordinates: [[{lat: 38, lon: -123}, ...]]}}})
 ```
 
 Falling entirely within the query shape
 
 ```ruby
-Restaurant.search "salad", where: {bounds: {geo_shape: {type: "circle", relation: "within", coordinates: [{lat: 38, lon: -123}], radius: "1km"}}}
+Restaurant.search("salad", where: {bounds: {geo_shape: {type: "circle", relation: "within", coordinates: [{lat: 38, lon: -123}], radius: "1km"}}})
 ```
 
 Not touching the query shape
 
 ```ruby
-Restaurant.search "burger", where: {bounds: {geo_shape: {type: "envelope", relation: "disjoint", coordinates: [{lat: 38, lon: -123}, {lat: 37, lon: -122}]}}}
+Restaurant.search("burger", where: {bounds: {geo_shape: {type: "envelope", relation: "disjoint", coordinates: [{lat: 38, lon: -123}, {lat: 37, lon: -122}]}}})
 ```
 
 ## Inheritance
@@ -1047,9 +1142,9 @@ Dog.reindex # equivalent, all animals reindexed
 And to search, use:
 
 ```ruby
-Animal.search "*"                   # all animals
-Dog.search "*"                      # just dogs
-Animal.search "*", type: [Dog, Cat] # just cats and dogs
+Animal.search("*")                   # all animals
+Dog.search("*")                      # just dogs
+Animal.search("*", type: [Dog, Cat]) # just cats and dogs
 ```
 
 **Notes:**
@@ -1057,7 +1152,7 @@ Animal.search "*", type: [Dog, Cat] # just cats and dogs
 1. The `suggest` option retrieves suggestions from the parent at the moment.
 
     ```ruby
-    Dog.search "airbudd", suggest: true # suggestions for all animals
+    Dog.search("airbudd", suggest: true) # suggestions for all animals
     ```
 2. This relies on a `type` field that is automatically added to the indexed document. Be wary of defining your own `type` field in `search_data`, as it will take precedence.
 
@@ -1380,6 +1475,8 @@ Create an initializer with multiple hosts:
 
 ```ruby
 ENV["ELASTICSEARCH_URL"] = "https://user:password@host1,https://user:password@host2"
+# or
+ENV["OPENSEARCH_URL"] = "https://user:password@host1,https://user:password@host2"
 ```
 
 See [elastic-transport](https://github.com/elastic/elastic-transport-ruby) or [opensearch-transport](https://github.com/opensearch-project/opensearch-ruby/tree/main/opensearch-transport) for a complete list of options.
@@ -1562,7 +1659,7 @@ end
 Reindex and search with:
 
 ```ruby
-Business.search "ice cream", routing: params[:city_id]
+Business.search("ice cream", routing: params[:city_id])
 ```
 
 ### Partial Reindexing
@@ -1573,11 +1670,12 @@ Reindex a subset of attributes to reduce time spent generating search data and c
 class Product < ApplicationRecord
   def search_data
     {
-      name: name
-    }.merge(search_prices)
+      name: name,
+      category: category
+    }.merge(prices_data)
   end
 
-  def search_prices
+  def prices_data
     {
       price: price,
       sale_price: sale_price
@@ -1589,68 +1687,7 @@ end
 And use:
 
 ```ruby
-Product.reindex(:search_prices)
-```
-
-### Performant Conversions
-
-Split out conversions into a separate method so you can use partial reindexing, and cache conversions to prevent N+1 queries. Be sure to use a centralized cache store like Memcached or Redis.
-
-```ruby
-class Product < ApplicationRecord
-  def search_data
-    {
-      name: name
-    }.merge(search_conversions)
-  end
-
-  def search_conversions
-    {
-      conversions: Rails.cache.read("search_conversions:#{self.class.name}:#{id}") || {}
-    }
-  end
-end
-```
-
-Create a job to update the cache and reindex records with new conversions.
-
-```ruby
-class ReindexConversionsJob < ApplicationJob
-  def perform(class_name)
-    # get records that have a recent conversion
-    recently_converted_ids =
-      Searchjoy::Search.where("convertable_type = ? AND converted_at > ?", class_name, 1.day.ago)
-      .order(:convertable_id).distinct.pluck(:convertable_id)
-
-    # split into groups
-    recently_converted_ids.in_groups_of(1000, false) do |ids|
-      # fetch conversions
-      conversions =
-        Searchjoy::Search.where(convertable_id: ids, convertable_type: class_name)
-        .group(:convertable_id, :query).distinct.count(:user_id)
-
-      # group conversions by record
-      conversions_by_record = {}
-      conversions.each do |(id, query), count|
-        (conversions_by_record[id] ||= {})[query] = count
-      end
-
-      # write to cache
-      conversions_by_record.each do |id, conversions|
-        Rails.cache.write("search_conversions:#{class_name}:#{id}", conversions)
-      end
-
-      # partial reindex
-      class_name.constantize.where(id: ids).reindex(:search_conversions)
-    end
-  end
-end
-```
-
-Run the job with:
-
-```ruby
-ReindexConversionsJob.perform_later("Product")
+Product.reindex(:prices_data)
 ```
 
 ## Advanced
@@ -1685,7 +1722,7 @@ end
 And use the `body` option to search:
 
 ```ruby
-products = Product.search body: {query: {match: {name: "milk"}}}
+products = Product.search(body: {query: {match: {name: "milk"}}})
 ```
 
 View the response with:
@@ -1697,14 +1734,14 @@ products.response
 To modify the query generated by Searchkick, use:
 
 ```ruby
-products = Product.search "milk", body_options: {min_score: 1}
+products = Product.search("milk", body_options: {min_score: 1})
 ```
 
 or
 
 ```ruby
 products =
-  Product.search "apples" do |body|
+  Product.search("apples") do |body|
     body[:min_score] = 1
   end
 ```
@@ -1736,7 +1773,7 @@ Then use `products` and `coupons` as typical results.
 Search across multiple models with:
 
 ```ruby
-Searchkick.search "milk", models: [Product, Category]
+Searchkick.search("milk", models: [Product, Category])
 ```
 
 Boost specific models with:
@@ -1762,7 +1799,7 @@ end
 You can also scroll batches manually.
 
 ```ruby
-products = Product.search "*", scroll: "1m"
+products = Product.search("*", scroll: "1m")
 while products.any?
   # process batch ...
 
@@ -1793,7 +1830,7 @@ Product.search("pears", body_options: {track_total_hits: true})
 To query nested data, use dot notation.
 
 ```ruby
-User.search "san", fields: ["address.city"], where: {"address.zip_code" => 12345}
+Product.search("san", fields: ["store.city"], where: {"store.zip_code" => 12345})
 ```
 
 ## Reference
@@ -1923,7 +1960,7 @@ Searchkick.queue_name = :search_reindex
 Eager load associations
 
 ```ruby
-Product.search "milk", includes: [:brand, :stores]
+Product.search("milk", includes: [:brand, :stores])
 ```
 
 Eager load different associations by model
@@ -1935,7 +1972,7 @@ Searchkick.search("*",  models: [Product, Store], model_includes: {Product => [:
 Run additional scopes on results
 
 ```ruby
-Product.search "milk", scope_results: ->(r) { r.with_attached_images }
+Product.search("milk", scope_results: ->(r) { r.with_attached_images })
 ```
 
 Specify default fields to search
@@ -2031,13 +2068,25 @@ rake searchkick:reindex:all
 Turn on misspellings after a certain number of characters
 
 ```ruby
-Product.search "api", misspellings: {prefix_length: 2} # api, apt, no ahi
+Product.search("api", misspellings: {prefix_length: 2}) # api, apt, no ahi
+```
+
+**Note:** With this option, if the query length is the same as `prefix_length`, misspellings are turned off with Elasticsearch 7 and OpenSearch 1
+
+```ruby
+Product.search("ah", misspellings: {prefix_length: 2}) # ah, no aha
 ```
 
-**Note:** With this option, if the query length is the same as `prefix_length`, misspellings are turned off with Elasticsearch 7 and OpenSearch
+BigDecimal values are indexed as floats by default so they can be used for boosting. Convert them to strings to keep full precision.
 
 ```ruby
-Product.search "ah", misspellings: {prefix_length: 2} # ah, no aha
+class Product < ApplicationRecord
+  def search_data
+    {
+      units: units.to_s("F")
+    }
+  end
+end
 ```
 
 ## Gotchas

data/lib/searchkick/index.rb

@@ -418,7 +418,7 @@ module Searchkick
         true
       end
     rescue => e
-      if Searchkick.transport_error?(e) && e.message.include?("No handler for type [text]")
+      if Searchkick.transport_error?(e) && (e.message.include?("No handler for type [text]") || e.message.include?("class java.util.ArrayList cannot be cast to class java.util.Map"))
         raise UnsupportedVersionError
       end
 

data/lib/searchkick/index_options.rb

@@ -19,7 +19,7 @@ module Searchkick
         mappings = generate_mappings.deep_symbolize_keys.deep_merge(custom_mappings)
       end
 
-      set_deep_paging(settings) if options[:deep_paging]
+      set_deep_paging(settings) if options[:deep_paging] || options[:max_result_window]
 
       {
         settings: settings,
@@ -525,7 +525,7 @@ module Searchkick
     def set_deep_paging(settings)
       if !settings.dig(:index, :max_result_window) && !settings[:"index.max_result_window"]
         settings[:index] ||= {}
-        settings[:index][:max_result_window] = 1_000_000_000
+        settings[:index][:max_result_window] = options[:max_result_window] || 1_000_000_000
       end
     end
 

data/lib/searchkick/model.rb

@@ -5,7 +5,7 @@ module Searchkick
 
       unknown_keywords = options.keys - [:_all, :_type, :batch_size, :callbacks, :case_sensitive, :conversions, :deep_paging, :default_fields,
         :filterable, :geo_shape, :highlight, :ignore_above, :index_name, :index_prefix, :inheritance, :language,
-        :locations, :mappings, :match, :merge_mappings, :routing, :searchable, :search_synonyms, :settings, :similarity,
+        :locations, :mappings, :match, :max_result_window, :merge_mappings, :routing, :searchable, :search_synonyms, :settings, :similarity,
         :special_characters, :stem, :stemmer, :stem_conversions, :stem_exclusion, :stemmer_override, :suggest, :synonyms, :text_end,
         :text_middle, :text_start, :unscope, :word, :word_end, :word_middle, :word_start]
       raise ArgumentError, "unknown keywords: #{unknown_keywords.join(", ")}" if unknown_keywords.any?
@@ -66,7 +66,7 @@ module Searchkick
           alias_method Searchkick.search_method_name, :searchkick_search if Searchkick.search_method_name
 
           def searchkick_index(name: nil)
-            index_name = name || searchkick_index_name
+            index_name = name || searchkick_klass.searchkick_index_name
             index_name = index_name.call if index_name.respond_to?(:call)
             index_cache = class_variable_get(:@@searchkick_index_cache)
             index_cache.fetch(index_name) { Searchkick::Index.new(index_name, searchkick_options) }

data/lib/searchkick/query.rb

@@ -254,6 +254,12 @@ module Searchkick
       offset = options[:offset] || (page - 1) * per_page + padding
       scroll = options[:scroll]
 
+      max_result_window = searchkick_options[:max_result_window]
+      if max_result_window
+        offset = max_result_window if offset > max_result_window
+        per_page = max_result_window - offset if offset + per_page > max_result_window
+      end
+
       # model and eager loading
       load = options[:load].nil? ? true : options[:load]
 

data/lib/searchkick/relation.rb

@@ -1,13 +1,20 @@
 module Searchkick
   class Relation
+    NO_DEFAULT_VALUE = Object.new
+
     # note: modifying body directly is not supported
     # and has no impact on query after being executed
     # TODO freeze body object?
-    delegate :body, :params, to: :@query
+    delegate :body, :params, to: :query
     delegate_missing_to :private_execute
 
     def initialize(model, term = "*", **options)
-      @query = Query.new(model, term, **options)
+      @model = model
+      @term = term
+      @options = options
+
+      # generate query to validate options
+      query
     end
 
     # same as Active Record
@@ -23,14 +30,196 @@ module Searchkick
       self
     end
 
+    # experimental
+    def limit(value)
+      clone.limit!(value)
+    end
+
+    # experimental
+    def limit!(value)
+      check_loaded
+      @options[:limit] = value
+      self
+    end
+
+    # experimental
+    def offset(value = NO_DEFAULT_VALUE)
+      # TODO remove in Searchkick 6
+      if value == NO_DEFAULT_VALUE
+        private_execute.offset
+      else
+        clone.offset!(value)
+      end
+    end
+
+    # experimental
+    def offset!(value)
+      check_loaded
+      @options[:offset] = value
+      self
+    end
+
+    # experimental
+    def page(value)
+      clone.page!(value)
+    end
+
+    # experimental
+    def page!(value)
+      check_loaded
+      @options[:page] = value
+      self
+    end
+
+    # experimental
+    def per_page(value = NO_DEFAULT_VALUE)
+      # TODO remove in Searchkick 6
+      if value == NO_DEFAULT_VALUE
+        private_execute.per_page
+      else
+        clone.per_page!(value)
+      end
+    end
+
+    # experimental
+    def per_page!(value)
+      check_loaded
+      @options[:per_page] = value
+      self
+    end
+
+    # experimental
+    def where(value = NO_DEFAULT_VALUE)
+      if value == NO_DEFAULT_VALUE
+        Where.new(self)
+      else
+        clone.where!(value)
+      end
+    end
+
+    # experimental
+    def where!(value)
+      check_loaded
+      if @options[:where]
+        @options[:where] = {_and: [@options[:where], ensure_permitted(value)]}
+      else
+        @options[:where] = ensure_permitted(value)
+      end
+      self
+    end
+
+    # experimental
+    def rewhere(value)
+      clone.rewhere!(value)
+    end
+
+    # experimental
+    def rewhere!(value)
+      check_loaded
+      @options[:where] = ensure_permitted(value)
+      self
+    end
+
+    # experimental
+    def order(*values)
+      clone.order!(*values)
+    end
+
+    # experimental
+    def order!(*values)
+      values = values.first if values.size == 1 && values.first.is_a?(Array)
+      check_loaded
+      (@options[:order] ||= []).concat(values)
+      self
+    end
+
+    # experimental
+    def reorder(*values)
+      clone.reorder!(*values)
+    end
+
+    # experimental
+    def reorder!(*values)
+      check_loaded
+      @options[:order] = values
+      self
+    end
+
+    # experimental
+    def select(*values, &block)
+      if block_given?
+        private_execute.select(*values, &block)
+      else
+        clone.select!(*values)
+      end
+    end
+
+    # experimental
+    def select!(*values)
+      check_loaded
+      (@options[:select] ||= []).concat(values)
+      self
+    end
+
+    # experimental
+    def reselect(*values)
+      clone.reselect!(*values)
+    end
+
+    # experimental
+    def reselect!(*values)
+      check_loaded
+      @options[:select] = values
+      self
+    end
+
+    # experimental
+    def includes(*values)
+      clone.includes!(*values)
+    end
+
+    # experimental
+    def includes!(*values)
+      check_loaded
+      (@options[:includes] ||= []).concat(values)
+      self
+    end
+
+    # experimental
+    def only(*keys)
+      Relation.new(@model, @term, **@options.slice(*keys))
+    end
+
+    # experimental
+    def except(*keys)
+      Relation.new(@model, @term, **@options.except(*keys))
+    end
+
+    def loaded?
+      !@execute.nil?
+    end
+
     private
 
     def private_execute
-      @execute ||= @query.execute
+      @execute ||= query.execute
     end
 
     def query
-      @query
+      @query ||= Query.new(@model, @term, **@options)
+    end
+
+    def check_loaded
+      raise Error, "Relation loaded" if loaded?
+
+      # reset query since options will change
+      @query = nil
+    end
+
+    # provides *very* basic protection from unfiltered parameters
+    # this is not meant to be comprehensive and may be expanded in the future
+    def ensure_permitted(obj)
+      obj.to_h
     end
   end
 end

data/lib/searchkick/version.rb

@@ -1,3 +1,3 @@
 module Searchkick
-  VERSION = "5.0.1"
+  VERSION = "5.0.4"
 end

data/lib/searchkick/where.rb

@@ -0,0 +1,11 @@
+module Searchkick
+  class Where
+    def initialize(relation)
+      @relation = relation
+    end
+
+    def not(value)
+      @relation.where(_not: value)
+    end
+  end
+end

data/lib/searchkick.rb

@@ -27,6 +27,7 @@ require "searchkick/relation"
 require "searchkick/relation_indexer"
 require "searchkick/results"
 require "searchkick/version"
+require "searchkick/where"
 
 # integrations
 require "searchkick/railtie" if defined?(Rails)
@@ -134,8 +135,9 @@ module Searchkick
     @opensearch
   end
 
-  def self.server_below?(version)
-    server_version = opensearch? ? "7.10.2" : self.server_version
+  # TODO always check true version in Searchkick 6
+  def self.server_below?(version, true_version = false)
+    server_version = !true_version && opensearch? ? "7.10.2" : self.server_version
     Gem::Version.new(server_version.split("-")[0]) < Gem::Version.new(version.split("-")[0])
   end
 
@@ -283,7 +285,7 @@ module Searchkick
     relation
   end
 
-  # private
+  # public (for reindexing conversions)
   def self.load_model(class_name, allow_child: false)
     model = class_name.safe_constantize
     raise Error, "Could not find class: #{class_name}" unless model

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: searchkick
 version: !ruby/object:Gem::Version
-  version: 5.0.1
+  version: 5.0.4
 platform: ruby
 authors:
 - Andrew Kane
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-27 00:00:00.000000000 Z
+date: 2022-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -71,6 +71,7 @@ files:
 - lib/searchkick/relation_indexer.rb
 - lib/searchkick/results.rb
 - lib/searchkick/version.rb
+- lib/searchkick/where.rb
 - lib/tasks/searchkick.rake
 homepage: https://github.com/ankane/searchkick
 licenses:
@@ -91,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Intelligent search made easy with Rails and Elasticsearch or OpenSearch