From 87a484c94507da129cc55f1c31aa511f87c25ded Mon Sep 17 00:00:00 2001 From: Andrew Date: Fri, 2 Mar 2018 18:38:59 -0800 Subject: [PATCH] Added upgrading guide [skip ci] --- CHANGELOG.md | 20 ++++++++------------ README.md | 73 ++++++------------------------------------------------------------------- docs/Searchkick-3-Upgrade.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ lib/searchkick/query.rb | 2 +- 4 files changed, 70 insertions(+), 80 deletions(-) create mode 100644 docs/Searchkick-3-Upgrade.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 6d9d913..a5018bf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,26 +1,22 @@ ## 3.0.0 [unreleased] -- Better performance +- Better reindexing performance - Added support for Chinese Breaking changes - Removed support for Elasticsearch 2 - Removed support for ActiveRecord < 4.2 and Mongoid < 5 -- Removed `reindex_async` method. `reindex` now defaults to mode specified by model. Use `reindex(mode: :async)` to force async reindex. -- Types are no longer supported. To upgrade models that use inheritance, upgrade your gem to `2.5.0`. Added `inheritance: true` to your `searchkick` method, and do a full reindex before upgrading. -- Bumped default `limit` to 10,000 -- The `_all` field is disabled by default in Elasticsearch 5. Use `searchkick _all: true` if you need it. +- Types are no longer supported +- The `_all` field is disabled by default in Elasticsearch 5 +- Conversions are not stemmed by default - An `ArgumentError` is raised instead of a warning when options are incompatible with the `body` option -- Removed `log` option from `boost_by`. Use `modifier: "ln2p"` instead. +- Removed `log` option from `boost_by` - Removed `unscoped_reindex_job` option (always `true` now) - Removed `Model.enable_search_callbacks`, `Model.disable_search_callbacks`, and `Model.search_callbacks?` -- Removed `async` option from `record.reindex` - use `mode: :async` instead -- Conversions are not stemmed by default - use `stem_conversion: true` to enable this - -```ruby -Searchkick.model_options = {stem_conversions: true} -``` +- Removed `reindex_async` method, as `reindex` now defaults to callbacks mode specified on the model +- Removed `async` option from `record.reindex` +- Bumped default `limit` to 10,000 ## 2.5.1 [unreleased] diff --git a/README.md b/README.md index bcf5910..7e59f56 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,8 @@ Plus: - [Elasticsearch DSL](#advanced) - [Reference](#reference) +**Searchkick 3.0 was recently released!** See [how to upgrade](docs/Searchkick-3-Upgrade.md) + Thinking of upgrading from Elasticsearch 5 to 6? [Read this first](#elasticsearch-5-to-6-upgrade) ## Getting Started @@ -1799,73 +1801,6 @@ Searchkick.index_suffix = ENV["TEST_ENV_NUMBER"] Check out [this great post](https://www.tiagoamaro.com.br/2014/12/11/multi-tenancy-with-searchkick/) on the [Apartment](https://github.com/influitive/apartment) gem. Follow a similar pattern if you use another gem. -## Upgrading - -View the [changelog](https://github.com/ankane/searchkick/blob/master/CHANGELOG.md). - -Important notes are listed below. - -### 3.0.0 - -#### Breaking Changes - -- Removed support for Elasticsearch 2 -- Removed support for ActiveRecord < 4.2 and Mongoid < 5 -- Removed `reindex_async` method. `reindex` now defaults to mode specified by model. Use `reindex(mode: :async)` to force async reindex. -- Types are no longer supported. To upgrade models that use inheritance, upgrade your gem to `2.5.0`. Added `inheritance: true` to your `searchkick` method, and do a full reindex before upgrading. -- Bumped default `limit` to 10,000 -- The `_all` field is disabled by default in Elasticsearch 5. Use `searchkick _all: true` if you need it. -- An `ArgumentError` is raised instead of a warning when options are incompatible with the `body` option - -### 2.0.0 - -- Added support for `reindex` on associations - -#### Breaking Changes - -- Removed support for Elasticsearch 1 as it reaches [end of life](https://www.elastic.co/support/eol) -- Removed facets, legacy options, and legacy methods -- Invalid options now throw an `ArgumentError` -- The `query` and `json` options have been removed in favor of `body` -- The `include` option has been removed in favor of `includes` -- The `personalize` option has been removed in favor of `boost_where` -- The `partial` option has been removed in favor of `operator` -- Renamed `select_v2` to `select` (legacy `select` no longer available) -- The `_all` field is disabled if `searchable` option is used (for performance) -- The `partial_reindex(:method_name)` method has been replaced with `reindex(:method_name)` -- The `unsearchable` and `only_analyzed` options have been removed in favor of `searchable` and `filterable` -- `load: false` no longer returns an array in Elasticsearch 2 - -### 1.0.0 - -- Added support for Elasticsearch 2.0 -- Facets are deprecated in favor of [aggregations](#aggregations) - see [how to upgrade](#moving-from-facets) - -#### Breaking Changes - -- **ActiveRecord 4.1+ and Mongoid 3+:** Attempting to reindex with a scope now throws a `Searchkick::DangerousOperation` error to keep your from accidentally recreating your index with only a few records. - - ```ruby - Product.where(color: "brandy").reindex # error! - ``` - - If this is what you intend to do, use: - - ```ruby - Product.where(color: "brandy").reindex(accept_danger: true) - ``` - -- Misspellings are enabled by default for [partial matches](#partial-matches). Use `misspellings: false` to disable. -- [Transpositions](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) are enabled by default for misspellings. Use `misspellings: {transpositions: false}` to disable. - -### 0.6.0 and 0.7.0 - -If running Searchkick `0.6.0` or `0.7.0` and Elasticsearch `0.90`, we recommend upgrading to Searchkick `0.6.1` or `0.7.1` to fix an issue that causes downtime when reindexing. - -### 0.3.0 - -Before `0.3.0`, locations were indexed incorrectly. When upgrading, be sure to reindex immediately. - ## Elasticsearch 5 to 6 Upgrade Elasticsearch 6 removes the ability to reindex with the `_all` field. Before you upgrade, we recommend disabling this field manually and specifying default fields on your models. @@ -1911,6 +1846,10 @@ end For convenience, this is set by default in the test environment. +## History + +View the [changelog](https://github.com/ankane/searchkick/blob/master/CHANGELOG.md). + ## Thanks Thanks to Karel Minarik for [Elasticsearch Ruby](https://github.com/elasticsearch/elasticsearch-ruby) and [Tire](https://github.com/karmi/retire), Jaroslav Kalistsuk for [zero downtime reindexing](https://gist.github.com/jarosan/3124884), and Alex Leschenko for [Elasticsearch autocomplete](https://github.com/leschenko/elasticsearch_autocomplete). diff --git a/docs/Searchkick-3-Upgrade.md b/docs/Searchkick-3-Upgrade.md new file mode 100644 index 0000000..3dcd667 --- /dev/null +++ b/docs/Searchkick-3-Upgrade.md @@ -0,0 +1,55 @@ +# Searchkick 3 Upgrade + +## Before You Upgrade + +Searchkick 3 not longer supports types, since they are deprecated in Elasticsearch 6. + +If you use inheritance, add to your parent model: + +```ruby +class Animal < ApplicationRecord + searchkick inheritance: true +end +``` + +And do a full reindex. + +## Upgrading + +Update your Gemfile: + +```ruby +gem 'searchkick', '~> 3' +``` + +And run: + +```sh +bundle update searchkick +``` + +We recommend you don’t stem conversions anymore, so conversions for `pepper` don’t affect `peppers`, but if you want to keep the old behavior, use: + +```ruby +Searchkick.model_options = { + stem_conversions: true +} +``` + +Searchkick 3 disables the `_all` field by default, since Elasticsearch 6 removes the ability to reindex with it. If you’re on Elasticsearch 5 and still need it, add to your model: + +```ruby +class Product < ApplicationRecord + searchkick _all: true +end +``` + +If you use `record.reindex_async` or `record.reindex(async: true)`, replace it with: + +```ruby +record.reindex(mode: :async) +``` + +If you use `log: true` with `boost_by`, replace it with `modifier: "ln2p"`. + +If you use the `body` option and have warnings about incompatible options, remove them, as they now throw an `ArgumentError`. diff --git a/lib/searchkick/query.rb b/lib/searchkick/query.rb index cea8cae..716ccd0 100644 --- a/lib/searchkick/query.rb +++ b/lib/searchkick/query.rb @@ -226,7 +226,7 @@ module Searchkick ignored_options = options.keys & [:aggs, :boost, :boost_by, :boost_by_distance, :boost_where, :conversions, :conversions_term, :exclude, :explain, :fields, :highlight, :indices_boost, :limit, :match, :misspellings, :offset, :operator, :order, - :padding, :page, :per_page, :select, :smart_aggs, :suggest, :where] + :padding, :page, :per_page, :profile, :select, :smart_aggs, :suggest, :where] raise ArgumentError, "Options incompatible with body option: #{ignored_options.join(", ")}" if ignored_options.any? payload = @json else -- libgit2 0.21.0