algoliasearch-rails 1.14.1 → 1.15.0

data/README.md

@@ -1,35 +1,43 @@
+<!--NO_HTML-->
+
 Algolia Search for Rails
 ==================
 
-This gem let you easily integrate the Algolia Search API to your favorite ORM. It's based on the [algoliasearch-client-ruby](https://github.com/algolia/algoliasearch-client-ruby) gem. Both Rails 3.x and Rails 4.x are supported.
+<!--/NO_HTML-->
+
+This gem let you easily integrate the Algolia Search API to your favorite ORM. It's based on the [algoliasearch-client-ruby](https://github.com/algolia/algoliasearch-client-ruby) gem. Rails 3.x, 4.x and 5.x are all supported.
 
-You might be interested in the sample Ruby on Rails application providing a ```typeahead.js```-based auto-completion and ```Google```-like instant search: [algoliasearch-rails-example](https://github.com/algolia/algoliasearch-rails-example/).
+You might be interested in the sample Ruby on Rails application providing a ```autocomplete.js```-based auto-completion and ```instantsearch.js```-based instant search results page: [algoliasearch-rails-example](https://github.com/algolia/algoliasearch-rails-example/).
 
-[![Build Status](https://travis-ci.org/algolia/algoliasearch-rails.png?branch=master)](https://travis-ci.org/algolia/algoliasearch-rails) [![Gem Version](https://badge.fury.io/rb/algoliasearch-rails.png)](http://badge.fury.io/rb/algoliasearch-rails) [![Code Climate](https://codeclimate.com/github/algolia/algoliasearch-rails.png)](https://codeclimate.com/github/algolia/algoliasearch-rails) ![ActiveRecord](https://img.shields.io/badge/ActiveRecord-yes-blue.svg?style=flat-square) ![Mongoid](https://img.shields.io/badge/Mongoid-yes-blue.svg?style=flat-square) ![Sequel](https://img.shields.io/badge/Sequel-yes-blue.svg?style=flat-square)
+[![Build Status](https://travis-ci.org/algolia/algoliasearch-rails.svg?branch=master)](https://travis-ci.org/algolia/algoliasearch-rails) [![Gem Version](https://badge.fury.io/rb/algoliasearch-rails.svg)](http://badge.fury.io/rb/algoliasearch-rails) [![Code Climate](https://codeclimate.com/github/algolia/algoliasearch-rails.svg)](https://codeclimate.com/github/algolia/algoliasearch-rails) ![ActiveRecord](https://img.shields.io/badge/ActiveRecord-yes-blue.svg?style=flat-square) ![Mongoid](https://img.shields.io/badge/Mongoid-yes-blue.svg?style=flat-square) ![Sequel](https://img.shields.io/badge/Sequel-yes-blue.svg?style=flat-square)
+
+<!--NO_HTML-->
 
 Table of Content
--------------
-**Get started**
+=============
 
 1. [Install](#install)
 1. [Setup](#setup)
 1. [Quick Start](#quick-start)
-1. [Ranking & Relevance](#ranking--relevance)
 1. [Options](#options)
 1. [Configuration example](#configuration-example)
 1. [Indexing](#indexing)
 1. [Master/Slave](#masterslave)
+1. [Share a single index](#share-a-single-index)
 1. [Target multiple indexes](#target-multiple-indexes)
 1. [Tags](#tags)
 1. [Search](#search)
 1. [Faceting](#faceting)
+1. [Group by](#group-by)
 1. [Geo-search](#geo-search)
-1. [Typeahead UI](#typeahead-ui)
 1. [Caveats](#caveats)
 1. [Note on testing](#note-on-testing)
 
-Install
--------------
+<!--/NO_HTML-->
+
+## Setup
+
+### Install
 
 ```sh
 gem install algoliasearch-rails
@@ -47,8 +55,8 @@ And run:
 bundle install
 ```
 
-Setup
--------------
+### Configuration
+
 Create a new file <code>config/initializers/algoliasearch.rb</code> to setup your <code>APPLICATION_ID</code> and <code>API_KEY</code>.
 
 
@@ -58,14 +66,9 @@ AlgoliaSearch.configuration = { application_id: 'YourApplicationID', api_key: 'Y
 
 The gem is compatible with [ActiveRecord](https://github.com/rails/rails/tree/master/activerecord), [Mongoid](https://github.com/mongoid/mongoid) and [Sequel](https://github.com/jeremyevans/sequel).
 
-We support both [will_paginate](https://github.com/mislav/will_paginate) and [kaminari](https://github.com/amatsuda/kaminari) as pagination backend. For example to use <code>:will_paginate</code>, specify the <code>:pagination_backend</code> as follow:
-
-```ruby
-AlgoliaSearch.configuration = { application_id: 'YourApplicationID', api_key: 'YourAPIKey', pagination_backend: :will_paginate }
-```
+## Quick Start
 
-Quick Start
--------------
+### Schema
 
 The following code will create a <code>Contact</code> index and add search capabilities to your <code>Contact</code> model:
 
@@ -108,7 +111,7 @@ class Product < ActiveRecord::Base
 end
 ```
 
-#### Ranking & Relevance
+### Relevancy
 
 We provide many ways to configure your index allowing you to tune your overall index relevancy. The most important ones are the **searchable attributes** and the attributes reflecting **record popularity**.
 
@@ -134,7 +137,25 @@ class Product < ActiveRecord::Base
 end
 ```
 
-#### Frontend Search (realtime experience)
+### Indexing
+
+To index a model, simple call `reindex` on the class:
+
+```ruby
+Product.reindex
+```
+
+To index all of your models, you can do something like this:
+
+```ruby
+Rails.application.eager_load! # Ensure all models are loaded (required in development).
+
+algolia_models = ActiveRecord::Base.descendants.select{ |model| model.respond_to?(:reindex) }
+
+algolia_models.each(&:reindex)
+```
+
+### Frontend Search (realtime experience)
 
 Traditional search implementations tend to have search logic and functionality on the backend. This made sense when the search experience consisted of a user entering a search query, executing that search, and then being redirected to a search result page.
 
@@ -151,14 +172,18 @@ Then in your JavaScript code you can do:
 ```js
 var client = algoliasearch(ApplicationID, Search-Only-API-Key);
 var index = client.initIndex('YourIndexName');
-index.search('something', function(success, hits) {
-  console.log(success, hits)
-}, { hitsPerPage: 10, page: 0 });
+index.search('something', { hitsPerPage: 10, page: 0 })
+  .then(function searchDone(content) {
+    console.log(content)
+  })
+  .catch(function searchFailure(err) {
+    console.error(err);
+  });
 ```
 
 **We recently (March 2015) released a new version (V3) of our JavaScript client, if you were using our previous version (V2), [read the migration guide](https://github.com/algolia/algoliasearch-client-js/wiki/Migration-guide-from-2.x.x-to-3.x.x)**
 
-#### Backend Search
+### Backend Search
 
 If you want to search from your backend you can use the `raw_search` method. It retrieves the raw JSON answer from the API:
 
@@ -172,7 +197,31 @@ You could also use `search` but it's not recommended. This method will fetch the
 p Contact.search("jon doe") # we recommend to use `raw_search` to avoid the database lookup
 ```
 
-#### Notes
+### Backend Pagination
+
+Even if we **highly recommend to perform all search (and therefore pagination) operations from your frontend using JavaScript**, we support both [will_paginate](https://github.com/mislav/will_paginate) and [kaminari](https://github.com/amatsuda/kaminari) as pagination backend.
+
+To use <code>:will_paginate</code>, specify the <code>:pagination_backend</code> as follow:
+
+```ruby
+AlgoliaSearch.configuration = { application_id: 'YourApplicationID', api_key: 'YourAPIKey', pagination_backend: :will_paginate }
+```
+
+Then, as soon as you use the `search` method, the returning results will be a paginated set:
+
+```ruby
+# in your controller
+@results = MyModel.search('foo', hitsPerPage: 10)
+
+# in your views
+# if using will_paginate
+<%= will_paginate @results %>
+
+# if using kaminari
+<%= paginate @results %>
+```
+
+### Notes
 
 All methods injected by the ```AlgoliaSearch``` include are prefixed by ```algolia_``` and aliased to the associated short names if they aren't already defined.
 
@@ -182,10 +231,9 @@ Contact.algolia_reindex! # <=> Contact.reindex!
 Contact.algolia_search("jon doe") # <=> Contact.search("jon doe")
 ```
 
-Options
-----------
+## Options
 
-#### Auto-indexing & asynchronism
+### Auto-indexing & asynchronism
 
 Each time a record is saved; it will be - asynchronously - indexed. On the other hand, each time a record is destroyed, it will be - asynchronously - removed from the index. That means that a network call with the ADD/DELETE operation is sent **synchronously** to the Algolia API but then the engine will **asynchronously** process the operation (so if you do a search just after, the results may not reflect it yet).
 
@@ -201,7 +249,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-##### Temporary disable auto-indexing
+#### Temporary disable auto-indexing
 
 You can temporary disable auto-indexing using the <code>without_auto_index</code> scope. This is often used for performance reason.
 
@@ -213,7 +261,7 @@ end
 Contact.reindex! # will use batch operations
 ```
 
-##### Queues & background jobs
+#### Queues & background jobs
 
 You can configure the auto-indexing & auto-removal process to use a queue to perform those operations in background. ActiveJob (Rails >=4.2) queues are used by default but you can define your own queuing mechanism:
 
@@ -227,7 +275,31 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-##### With Sidekiq
+#### Things to Consider
+
+If you are performing updates & deletions in the background then a record deletion can be committed to your database prior
+to the job actually executing. Thus if you were to load the record to remove it from the database than your ActiveRecord#find will fail with a RecordNotFound.
+
+In this case you can bypass loading the record from ActiveRecord and just communicate with the index directly:
+
+```ruby
+class MySidekiqWorker
+  def perform(id, remove)
+    if remove
+      # the record has likely already been removed from your database so we cannot
+      # use ActiveRecord#find to load it
+      index = Algolia::Index.new("index_name")
+      index.delete_object(id)
+    else
+      # the record should be present
+      c = Contact.find(id)
+      c.index!
+    end
+  end
+end
+```
+
+#### With Sidekiq
 
 If you're using [Sidekiq](https://github.com/mperham/sidekiq):
 
@@ -252,7 +324,7 @@ class MySidekiqWorker
 end
 ```
 
-##### With DelayedJob
+#### With DelayedJob
 
 If you're using [delayed_job](https://github.com/collectiveidea/delayed_job):
 
@@ -275,7 +347,7 @@ end
 
 ```
 
-##### Synchronism & testing
+#### Synchronism & testing
 
 You can force indexing and removing to be synchronous (in that case the gem will call the `wait_task` method to ensure the operation has been taken into account once the method returns) by setting the following option: (this is **NOT** recommended, except for testing purpose)
 
@@ -289,7 +361,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-#### Exceptions
+### Exceptions
 
 You can disable exceptions that could be raised while trying to reach Algolia's API by using the `raise_on_failure` option:
 
@@ -304,7 +376,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-#### Custom index name
+### Custom index name
 
 By default, the index name will be the class name, e.g. "Contact". You can customize the index name by using the `index_name` option:
 
@@ -318,7 +390,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-#### Per-environment indexes
+### Per-environment indexes
 
 You can suffix the index name with the current Rails environment using the following option:
 
@@ -332,7 +404,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-#### Custom attribute definition
+### Custom attribute definition
 
 You can use a block to specify a complex attribute value
 
@@ -373,7 +445,7 @@ class Contact < ActiveRecord::Base
 end
 ```
 
-#### Nested objects/relations
+### Nested objects/relations
 
 You can easily embed nested objects defining an extra attribute returning any JSON-compliant object (an array or a hash or a combination of both).
 
@@ -400,7 +472,7 @@ class Profile < ActiveRecord::Base
 end
 ```
 
-#### Custom ```objectID```
+### Custom ```objectID```
 
 By default, the `objectID` is based on your record's `id`. You can change this behavior specifying the `:id` option (be sure to use a uniq field).
 
@@ -413,10 +485,12 @@ class UniqUser < ActiveRecord::Base
 end
 ```
 
-#### Restrict indexing to a subset of your data
+### Restrict indexing to a subset of your data
 
 You can add constraints controlling if a record must be indexed by using options the ```:if``` or ```:unless``` options.
 
+It allows you to do conditional indexing on a per document basis.
+
 ```ruby
 class Post < ActiveRecord::Base
   include AlgoliaSearch
@@ -467,7 +541,7 @@ or
 MyModel.index_objects MyModel.limit(5)
 ```
 
-#### Sanitizer
+### Sanitizer
 
 You can sanitize all your attributes using the ```sanitize``` option. It will strip all HTML tags from your attributes.
 
@@ -489,7 +563,7 @@ gem 'rails-html-sanitizer'
 ```
 
 
-#### UTF-8 Encoding
+### UTF-8 Encoding
 
 You can force the UTF-8 encoding of all your attributes using the ```force_utf8_encoding``` option:
 
@@ -507,8 +581,7 @@ end
 ***Notes:*** This option is not compatible with Ruby 1.8
 
 
-Configuration example
----------------------
+### Configuration example
 
 Here is a real-word configuration example (from [HN Search](https://github.com/algolia/hn-search)):
 
@@ -565,10 +638,9 @@ class Item < ActiveRecord::Base
 end
 ```
 
-Indexing
----------
+## Indexing
 
-#### Manual indexing
+### Manual indexing
 
 You can trigger indexing using the <code>index!</code> instance method.
 
@@ -577,7 +649,7 @@ c = Contact.create!(params[:contact])
 c.index!
 ```
 
-#### Manual removal
+### Manual removal
 
 And trigger index removing using the <code>remove_from_index!</code> instance method.
 
@@ -586,21 +658,29 @@ c.remove_from_index!
 c.destroy
 ```
 
-#### Reindexing
+### Reindexing
+
+The gem provides 2 ways to reindex all your objects:
+
+#### Atomical reindexing
 
-To *safely* reindex all your records (index to a temporary index + move the temporary index to the current one atomically), use the <code>reindex</code> class method:
+To reindex all your records (taking into account the deleted objects), the `reindex` class method indexes all your objects to a temporary index called `<INDEX_NAME>.tmp` and moves the temporary index to the final one once everything is indexed (atomically). This is the safest way to reindex all your content.
 
 ```ruby
 Contact.reindex
 ```
 
-To reindex all your records (in place, without deleting out-dated records), use the <code>reindex!</code> class method:
+**Notes**: if you're using an index-specific API key, ensure you're allowing both `<INDEX_NAME>` and `<INDEX_NAME>.tmp`.
+
+#### Regular reindexing
+
+To reindex all your objects in place (without temporary index and therefore without deleting removed objects), use the `reindex!` class method:
 
 ```ruby
 Contact.reindex!
 ```
 
-#### Clearing an index
+### Clearing an index
 
 To clear an index, use the <code>clear_index!</code> class method:
 
@@ -608,7 +688,7 @@ To clear an index, use the <code>clear_index!</code> class method:
 Contact.clear_index!
 ```
 
-#### Using the underlying index
+### Using the underlying index
 
 You can access the underlying `index` object by calling the `index` class method:
 
@@ -617,8 +697,9 @@ index = Contact.index
 # index.get_settings, index.partial_update_object, ...
 ```
 
-Master/slave
----------
+## Indexes
+
+### Master/slave
 
 You can define slave indexes using the <code>add_slave</code> method:
 
@@ -653,8 +734,45 @@ Book.raw_search 'foo bar', slave: 'Book_by_editor'
 Book.search 'foo bar', slave: 'Book_by_editor'
 ```
 
-Target multiple indexes
----------
+### Share a single index
+
+It can make sense to share an index between several models. In order to implement that, you'll need to ensure you don't have any conflict with the `objectID` of the underlying models.
+
+```ruby
+class Student < ActiveRecord::Base
+  attr_protected
+
+  include AlgoliaSearch
+
+  algoliasearch index_name: 'people', id: :algolia_id do
+    # [...]
+  end
+
+  private
+  def algolia_id
+    "student_#{id}" # ensure the teacher & student IDs are not conflicting
+  end
+end
+
+class Teacher < ActiveRecord::Base
+  attr_protected
+
+  include AlgoliaSearch
+
+  algoliasearch index_name: 'people', id: :algolia_id do
+    # [...]
+  end
+
+  private
+  def algolia_id
+    "teacher_#{id}" # ensure the teacher & student IDs are not conflicting
+  end
+end
+```
+
+***Notes:*** If you target a single index from several models, you must never use `MyModel.reindex` and only use `MyModel.reindex!`. The `reindex` method uses a temporary index to perform an atomic reindexing: if you use it, the resulting index will only contain records for the current model because it will not reindex the others.
+
+### Target multiple indexes
 
 You can index a record in several indexes using the <code>add_index</code> method:
 
@@ -667,7 +785,7 @@ class Book < ActiveRecord::Base
   PUBLIC_INDEX_NAME  = "Book_#{Rails.env}"
   SECURED_INDEX_NAME = "SecuredBook_#{Rails.env}"
 
-  # store all books in index 'SECURED_INDEX_NAME' 
+  # store all books in index 'SECURED_INDEX_NAME'
   algoliasearch index_name: SECURED_INDEX_NAME do
     attributesToIndex [:name, :author]
     # convert security to tags
@@ -697,8 +815,9 @@ Book.raw_search 'foo bar', index: 'Book_by_editor'
 Book.search 'foo bar', index: 'Book_by_editor'
 ```
 
-Tags
------
+## Features
+
+### Tags
 
 Use the <code>tags</code> method to add tags to your record:
 
@@ -728,8 +847,7 @@ end
 
 At query time, specify <code>{ tagFilters: 'tagvalue' }</code> or <code>{ tagFilters: ['tagvalue1', 'tagvalue2'] }</code> as search parameters to restrict the result set to specific tags.
 
-Search
-----------
+### Search
 
 ***Notes:*** We recommend the usage of our [JavaScript API Client](https://github.com/algolia/algoliasearch-client-js) to perform queries directly from the end-user browser without going through your server.
 
@@ -765,7 +883,7 @@ class Contact < ActiveRecord::Base
 
   algoliasearch do
     attribute :first_name, :last_name, :email
-    
+
     # default search parameters stored in the index settings
     minWordSizeForApprox1 4
     minWordSizeForApprox2 8
@@ -779,8 +897,7 @@ end
 p Contact.raw_search("jon doe", { :hitsPerPage => 5, :page => 2 })
 ```
 
-Faceting
----------
+### Faceting
 
 Facets can be retrieved calling the extra ```facets``` method of the search answer.
 
@@ -810,68 +927,46 @@ raw_json = Contact.raw_search("jon doe", { :facets => '*' })
 p raw_json['facets']
 ```
 
-Geo-Search
------------
+### Group by
 
-Use the <code>geoloc</code> method to localize your record:
+More info on distinct for grouping can be found
+[here](https://www.algolia.com/doc/guides/search/distinct#distinct-for-grouping).
 
 ```ruby
 class Contact < ActiveRecord::Base
   include AlgoliaSearch
 
   algoliasearch do
-    geoloc :lat_attr, :lng_attr
+    # [...]
+
+    # specify the attribute to be used for distinguishing the records
+    # in this case the records will be grouped by company
+    attributeForDistinct "company"
   end
 end
 ```
 
-At query time, specify <code>{ aroundLatLng: "37.33, -121.89", aroundRadius: 50000 }</code> as search parameters to restrict the result set to 50KM around San Jose.
+### Geo-Search
 
-Typeahead UI
--------------
-
-Require ```algolia/v3/algoliasearch.min``` (see [algoliasearch-client-js](https://github.com/algolia/algoliasearch-client-js)) and ```algolia/typeahead.jquery.js``` somewhere in your JavaScript manifest, for example in ```application.js``` if you are using Rails 3.1+:
-
-```javascript
-//= require algolia/v3/algoliasearch.min
-//= require algolia/typeahead.jquery
-```
+Use the <code>geoloc</code> method to localize your record:
 
-We recommend the usage of [hogan](http://twitter.github.io/hogan.js/), a JavaScript templating engine from Twitter.
+```ruby
+class Contact < ActiveRecord::Base
+  include AlgoliaSearch
 
-```javascript
-//= require hogan
+  algoliasearch do
+    geoloc :lat_attr, :lng_attr
+  end
+end
 ```
 
-Turns any ```input[type="text"]``` element into a typeahead, for example:
-
-```javascript
-<input name="email" placeholder="test@example.org" id="user_email" />
-
-<script type="text/javascript">
-  $(document).ready(function() {
-    var client = algoliasearch('YourApplicationID', 'SearchOnlyApplicationKey');
-    var template = Hogan.compile('{{{_highlightResult.email.value}}} ({{{_highlightResult.first_name.value}}} {{{_highlightResult.last_name.value}}})');
-    $('input#user_email').typeahead(null, {
-      source: client.initIndex('<%= Contact.index_name %>').ttAdapter(),
-      displayKey: 'email',
-      templates: {
-        suggestion: function(hit) {
-          return template.render(hit);
-        }
-      }
-    });
-  });
-</script>
-```
+At query time, specify <code>{ aroundLatLng: "37.33, -121.89", aroundRadius: 50000 }</code> as search parameters to restrict the result set to 50KM around San Jose.
 
-Caveats
---------
+### Caveats
 
 This gem makes intensive use of Rails' callbacks to trigger the indexing tasks. If you're using methods bypassing ```after_validation```, ```before_save``` or ```after_commit``` callbacks, it will not index your changes. For example: ```update_attribute``` doesn't perform validations checks, to perform validations when updating use ```update_attributes```.
 
-Timeouts
----------
+### Timeouts
 
 You can configure a bunch of timeout threshold by setting the following options at initialization time:
 
@@ -887,8 +982,7 @@ AlgoliaSearch.configuration = {
 }
 ```
 
-Note on testing
------------------
+### Note on testing
 
 To run the specs, please set the <code>ALGOLIA_APPLICATION_ID</code> and <code>ALGOLIA_API_KEY</code> environment variables. Since the tests are creating and removing indexes, DO NOT use your production account.