Setup
Introduction
This gem let you easily integrate the Algolia Search API to your favorite ORM. It’s based on the algoliasearch-client-ruby gem.
You might be interested in the sample Ruby on Rails application providing examples of auto-complete and InstantSearch result page: algoliasearch-rails-example.
Compatibility
This gem supports Ruby from 2.4.x to 3.0.0 and Rails 5.x and 6.x.
It’s compatible with ActiveRecord, Mongoid and Sequel.
Install
1
gem install algoliasearch-rails
With Bundler, add the gem to your Gemfile:
1
gem "algoliasearch-rails"
And run:
1
bundle install
Global configuration
Create a new file config/initializers/algoliasearch.rb to configure the gem.
You will at least need to set up your Algolia credentials: APPLICATION_ID and API_KEY.
1
2
3
4
AlgoliaSearch.configuration = {
application_id: 'YourApplicationID',
api_key: 'YourAdminAPIKey'
}
Timeouts
You can also configure various timeout thresholds by setting the following options:
1
2
3
4
5
6
7
8
9
AlgoliaSearch.configuration = {
application_id: 'YourApplicationID',
api_key: 'YourAdminAPIKey',
connect_timeout: 2,
receive_timeout: 30,
send_timeout: 30,
batch_timeout: 120,
search_timeout: 5
}
Method name and aliases
All methods injected by the AlgoliaSearch module are prefixed by algolia_ and aliased
to the associated short names if they aren’t already defined. This documentation uses mostly the short
name.
1
2
3
4
5
6
7
Contact.algolia_reindex!
# can also be called via
Contact.reindex!
Contact.algolia_search("jon doe")
# can also be called via
Contact.search("jon doe")
Introducing algoliasearch block
To index your model into Algolia, you need to include the AlgoliaSearch module and
the algoliasearch block.
This block will be used to set up your index and define many options. Note that even
if you want to use all the default options, you must declare an empty block.
1
2
3
4
5
6
7
class Contact < ActiveRecord::Base
include AlgoliaSearch
algoliasearch do
# Use all default configuration
end
end
Final configuration example
This documentation will go over everything you need to know to add Algolia to your Rails project. To give you an example of what it will look like in the end, here is a real-world configuration example from HN Search. You can find the project repository on GitHub.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
class Item < ActiveRecord::Base
include AlgoliaSearch
algoliasearch per_environment: true do
# the list of attributes sent to Algolia's API
attribute :created_at, :title, :url, :author, :points, :story_text, :comment_text, :author, :num_comments, :story_id, :story_title
# integer version of the created_at datetime field, to use numerical filtering
attribute :created_at_i do
created_at.to_i
end
# `title` is more important than `{story,comment}_text`, `{story,comment}_text` more than `url`, `url` more than `author`
# btw, do not take into account position in most fields to avoid first word match boost
searchableAttributes ['unordered(title)', 'unordered(story_text)', 'unordered(comment_text)', 'unordered(url)', 'author']
# tags used for filtering
tags do
[item_type, "author_#{author}", "story_#{story_id}"]
end
# use associated number of HN points to sort results (last sort criteria)
customRanking ['desc(points)', 'desc(num_comments)']
# google+, $1.5M raises, C#: we love you
separatorsToIndex '+#$'
end
def story_text
item_type_cd != Item.comment ? text : nil
end
def story_title
comment? && story ? story.title : nil
end
def story_url
comment? && story ? story.url : nil
end
def comment_text
comment? ? text : nil
end
def comment?
item_type_cd == Item.comment
end
# [...]
end
