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
1	1	## 3.0.0 [unreleased]
2	2
3		-- Better performance
	3	+- Better reindexing performance
4	4	- Added support for Chinese
5	5
6	6	Breaking changes
7	7
8	8	- Removed support for Elasticsearch 2
9	9	- Removed support for ActiveRecord < 4.2 and Mongoid < 5
10		-- Removed `reindex_async` method. `reindex` now defaults to mode specified by model. Use `reindex(mode: :async)` to force async reindex.
11		-- 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.
12		-- Bumped default `limit` to 10,000
13		-- The `_all` field is disabled by default in Elasticsearch 5. Use `searchkick _all: true` if you need it.
	10	+- Types are no longer supported
	11	+- The `_all` field is disabled by default in Elasticsearch 5
	12	+- Conversions are not stemmed by default
14	13	- An `ArgumentError` is raised instead of a warning when options are incompatible with the `body` option
15		-- Removed `log` option from `boost_by`. Use `modifier: "ln2p"` instead.
	14	+- Removed `log` option from `boost_by`
16	15	- Removed `unscoped_reindex_job` option (always `true` now)
17	16	- Removed `Model.enable_search_callbacks`, `Model.disable_search_callbacks`, and `Model.search_callbacks?`
18		-- Removed `async` option from `record.reindex` - use `mode: :async` instead
19		-- Conversions are not stemmed by default - use `stem_conversion: true` to enable this
20		-
21		-```ruby
22		-Searchkick.model_options = {stem_conversions: true}
23		-```
	17	+- Removed `reindex_async` method, as `reindex` now defaults to callbacks mode specified on the model
	18	+- Removed `async` option from `record.reindex`
	19	+- Bumped default `limit` to 10,000
24	20
25	21	## 2.5.1 [unreleased]
26	22
...	...
...	...	@@ -39,6 +39,8 @@ Plus:
39	39	- [Elasticsearch DSL](#advanced)
40	40	- [Reference](#reference)
41	41
	42	+Searchkick 3.0 was recently released! See [how to upgrade](docs/Searchkick-3-Upgrade.md)
	43	+
42	44	Thinking of upgrading from Elasticsearch 5 to 6? [Read this first](#elasticsearch-5-to-6-upgrade)
43	45
44	46	## Getting Started
...	...	@@ -1799,73 +1801,6 @@ Searchkick.index_suffix = ENV["TEST_ENV_NUMBER"]
1799	1801
1800	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	1804	## Elasticsearch 5 to 6 Upgrade
1870	1805
1871	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	1846
1912	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	1853	## Thanks
1915	1854
1916	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 @@
	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	226	ignored_options = options.keys & [:aggs, :boost,
227	227	:boost_by, :boost_by_distance, :boost_where, :conversions, :conversions_term, :exclude, :explain,
228	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	230	raise ArgumentError, "Options incompatible with body option: #{ignored_options.join(", ")}" if ignored_options.any?
231	231	payload = @json
232	232	else
...	...