Added upgrading guide [skip ci]

Andrew
1 parent 10265429
Showing 4 changed files with 70 additions and 80 deletions Show diff stats
CHANGELOG.md
README.md
docs/Searchkick-3-Upgrade.md
lib/searchkick/query.rb
 ## 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]
@@ -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[&quot;TEST_ENV_NUMBER&quot;]
 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).
@@ -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`.
@@ -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
	@@ -39,6 +39,8 @@ Plus:		@@ -39,6 +39,8 @@ Plus:
39	- [Elasticsearch DSL](#advanced)	39	- [Elasticsearch DSL](#advanced)
40	- [Reference](#reference)	40	- [Reference](#reference)
41		41
		42	+Searchkick 3.0 was recently released! See [how to upgrade](docs/Searchkick-3-Upgrade.md)
		43	+
42	Thinking of upgrading from Elasticsearch 5 to 6? [Read this first](#elasticsearch-5-to-6-upgrade)	44	Thinking of upgrading from Elasticsearch 5 to 6? [Read this first](#elasticsearch-5-to-6-upgrade)
43		45
44	## Getting Started	46	## Getting Started
	@@ -1799,73 +1801,6 @@ Searchkick.index_suffix = ENV["TEST_ENV_NUMBER"]		@@ -1799,73 +1801,6 @@ Searchkick.index_suffix = ENV["TEST_ENV_NUMBER"]
1799		1801
1800	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.	1802	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.
1801		1803
1802	-## Upgrading
1803	-
1804	-View the [changelog](https://github.com/ankane/searchkick/blob/master/CHANGELOG.md).
1805	-
1806	-Important notes are listed below.
1807	-
1808	-### 3.0.0
1809	-
1810	-#### Breaking Changes
1811	-
1812	-- Removed support for Elasticsearch 2
1813	-- Removed support for ActiveRecord < 4.2 and Mongoid < 5
1814	-- Removed `reindex_async` method. `reindex` now defaults to mode specified by model. Use `reindex(mode: :async)` to force async reindex.
1815	-- 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.
1816	-- Bumped default `limit` to 10,000
1817	-- The `_all` field is disabled by default in Elasticsearch 5. Use `searchkick _all: true` if you need it.
1818	-- An `ArgumentError` is raised instead of a warning when options are incompatible with the `body` option
1819	-
1820	-### 2.0.0
1821	-
1822	-- Added support for `reindex` on associations
1823	-
1824	-#### Breaking Changes
1825	-
1826	-- Removed support for Elasticsearch 1 as it reaches [end of life](https://www.elastic.co/support/eol)
1827	-- Removed facets, legacy options, and legacy methods
1828	-- Invalid options now throw an `ArgumentError`
1829	-- The `query` and `json` options have been removed in favor of `body`
1830	-- The `include` option has been removed in favor of `includes`
1831	-- The `personalize` option has been removed in favor of `boost_where`
1832	-- The `partial` option has been removed in favor of `operator`
1833	-- Renamed `select_v2` to `select` (legacy `select` no longer available)
1834	-- The `_all` field is disabled if `searchable` option is used (for performance)
1835	-- The `partial_reindex(:method_name)` method has been replaced with `reindex(:method_name)`
1836	-- The `unsearchable` and `only_analyzed` options have been removed in favor of `searchable` and `filterable`
1837	-- `load: false` no longer returns an array in Elasticsearch 2
1838	-
1839	-### 1.0.0
1840	-
1841	-- Added support for Elasticsearch 2.0
1842	-- Facets are deprecated in favor of [aggregations](#aggregations) - see [how to upgrade](#moving-from-facets)
1843	-
1844	-#### Breaking Changes
1845	-
1846	-- 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.
1847	-
1848	- ```ruby
1849	- Product.where(color: "brandy").reindex # error!
1850	- ```
1851	-
1852	- If this is what you intend to do, use:
1853	-
1854	- ```ruby
1855	- Product.where(color: "brandy").reindex(accept_danger: true)
1856	- ```
1857	-
1858	-- Misspellings are enabled by default for [partial matches](#partial-matches). Use `misspellings: false` to disable.
1859	-- [Transpositions](https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance) are enabled by default for misspellings. Use `misspellings: {transpositions: false}` to disable.
1860	-
1861	-### 0.6.0 and 0.7.0
1862	-
1863	-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.
1864	-
1865	-### 0.3.0
1866	-
1867	-Before `0.3.0`, locations were indexed incorrectly. When upgrading, be sure to reindex immediately.
1868	-
1869	## Elasticsearch 5 to 6 Upgrade	1804	## Elasticsearch 5 to 6 Upgrade
1870		1805
1871	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.	1806	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		@@ -1911,6 +1846,10 @@ end
1911		1846
1912	For convenience, this is set by default in the test environment.	1847	For convenience, this is set by default in the test environment.
1913		1848
		1849	+## History
		1850	+
		1851	+View the [changelog](https://github.com/ankane/searchkick/blob/master/CHANGELOG.md).
		1852	+
1914	## Thanks	1853	## Thanks
1915		1854
1916	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).	1855	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).
@@ -0,0 +1,55 @@		@@ -0,0 +1,55 @@
	1	+# Searchkick 3 Upgrade
	2	+
	3	+## Before You Upgrade
	4	+
	5	+Searchkick 3 not longer supports types, since they are deprecated in Elasticsearch 6.
	6	+
	7	+If you use inheritance, add to your parent model:
	8	+
	9	+```ruby
	10	+class Animal < ApplicationRecord
	11	+ searchkick inheritance: true
	12	+end
	13	+```
	14	+
	15	+And do a full reindex.
	16	+
	17	+## Upgrading
	18	+
	19	+Update your Gemfile:
	20	+
	21	+```ruby
	22	+gem 'searchkick', '~> 3'
	23	+```
	24	+
	25	+And run:
	26	+
	27	+```sh
	28	+bundle update searchkick
	29	+```
	30	+
	31	+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:
	32	+
	33	+```ruby
	34	+Searchkick.model_options = {
	35	+ stem_conversions: true
	36	+}
	37	+```
	38	+
	39	+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:
	40	+
	41	+```ruby
	42	+class Product < ApplicationRecord
	43	+ searchkick _all: true
	44	+end
	45	+```
	46	+
	47	+If you use `record.reindex_async` or `record.reindex(async: true)`, replace it with:
	48	+
	49	+```ruby
	50	+record.reindex(mode: :async)
	51	+```
	52	+
	53	+If you use `log: true` with `boost_by`, replace it with `modifier: "ln2p"`.
	54	+
	55	+If you use the `body` option and have warnings about incompatible options, remove them, as they now throw an `ArgumentError`.
	@@ -226,7 +226,7 @@ module Searchkick		@@ -226,7 +226,7 @@ module Searchkick
226	ignored_options = options.keys & [:aggs, :boost,	226	ignored_options = options.keys & [:aggs, :boost,
227	:boost_by, :boost_by_distance, :boost_where, :conversions, :conversions_term, :exclude, :explain,	227	:boost_by, :boost_by_distance, :boost_where, :conversions, :conversions_term, :exclude, :explain,
228	:fields, :highlight, :indices_boost, :limit, :match, :misspellings, :offset, :operator, :order,	228	:fields, :highlight, :indices_boost, :limit, :match, :misspellings, :offset, :operator, :order,
229	- :padding, :page, :per_page, :select, :smart_aggs, :suggest, :where]	229	+ :padding, :page, :per_page, :profile, :select, :smart_aggs, :suggest, :where]
230	raise ArgumentError, "Options incompatible with body option: #{ignored_options.join(", ")}" if ignored_options.any?	230	raise ArgumentError, "Options incompatible with body option: #{ignored_options.join(", ")}" if ignored_options.any?
231	payload = @json	231	payload = @json
232	else	232	else