Integrations / Frameworks / Rails / 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

Did you find this page helpful?