Index Settings

Index names

The index name will be automatically deduced from the class name. You can customize the index name by passing a string to the index_name option.

1
2
3
4
5
6
7
class Contact < ActiveRecord::Base
  include AlgoliaSearch

  algoliasearch index_name: "MyCustomName" do
    attribute :first_name, :last_name, :email
  end
end

Per-environment indices

In most cases, you’ll have your production indices and you development indices under the same Algolia app.

To make sure you don’t modify your production data while developing, this gem can automatically suffix the index name with the current Rails environment, turning the Contact index to Contact_#{Rails.env}.

It’s also highly recommended to use API keys with index restrictions. For instance, when developing, you would use a key that can only write on indices with names ending in _development and _development.tmp. The tmp index is required when using atomic reindexing. This restriction will make it impossible to write on your production index.

1
2
3
4
5
6
7
class Contact < ActiveRecord::Base
  include AlgoliaSearch

  algoliasearch per_environment: true do
    attribute :first_name, :last_name, :email
  end
end

Index settings

Algolia offers many settings to fine-tune your search. You can find all the available settings in our documentation. Settings will either help with relevance or with displaying results. This gem lets you set all your index settings inside the algoliasearch.

This page will show some common use cases like faceting or distinct.

Relevancy 101

If you don’t want to spend time going over all the settings yet, it’s highly recommended to at least set the searchableAttributes and customRanking settings. Those two will already improve relevancy a lot by reflecting record popularity and ignoring technical attributes (like image URLs or dates).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
class Product < ActiveRecord::Base
  include AlgoliaSearch

  algoliasearch do
    # list of attribute used to build an Algolia record
    attributes :title, :subtitle, :description, :likes_count, :thumbnail_url, :release_date

    # the `searchableAttributes` (formerly known as attributesToIndex) setting defines the attributes
    # you want to search in: here `title`, `subtitle` & `description`.
    # You need to list them by order of importance. `description` is tagged as
    # `unordered` to avoid taking the position of a match into account in that attribute.
    searchableAttributes ['title', 'subtitle', 'unordered(description)']

    # the `customRanking` setting defines the ranking criteria use to compare two matching
    # records in case their text-relevance is equal. It should reflect your record popularity.
    customRanking ['desc(likes_count)']
  end

end

Faceting

If you intend to do filtering or faceting, you must register the necessary attributes in the settings, under attributesForFaceting. To be so fast, Algolia computes a lot of things at indexing time, rather than query time, so the engine must know in advance what will be used for filtering and faceting.

If you have a lot of facet values, you can even make a facet searchable (like categories in the following example).

In the same vein, you may want to look at numericAttributesForFiltering.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
class Product < ActiveRecord::Base
  include AlgoliaSearch

  algoliasearch do
    # list of attribute used to build an Algolia record
    attributes :title, :subtitle, :likes_count, :ratings, :categories, :features, :sizes

    # ... Other settings removed for brevity

    attributesForFaceting ['searchable(categories)', 'features', 'sizes']
    numericAttributesForFiltering ['likes_count', 'equalOnly(ratings)']
  end

end

Synonyms

Currently, this gem only support regular synonyms where all words are mutually equivalent: “Pants” = “trousers” and “trousers” = “pants”.

1
2
3
4
5
6
7
8
9
10
class Contact < ActiveRecord::Base
  include AlgoliaSearch

  algoliasearch do
    attributes :first_name, :email

    synonyms [ ['bob', 'bobby' 'robert'] ]

  end
end

If you wish to use any other type of synonym, you can do so by using the underlying index of the model and the save_synonym or batch_synonyms method.

Synchronizing settings

By default, this gem will look at your settings and detect changes to them to know when to send them to Algolia.

Disable automatic synchronization

In case you don’t want to automatically synchronize your settings, make sure to manually push your changes whenever you update your settings. You can disable automatic setting synchronization as followed:

1
2
3
4
5
6
7
class Musician < ActiveRecord::Base
  include AlgoliaSearch

  algoliasearch check_settings: false do
    searchableAttributes ['name', 'band']
  end
end

Applying all settings

This gem has a rake command to push settings to all indices. It will push settings to your primary indices, replicas indices and all additional indices defined with add_index. See the next section to learn more about additional indices.

This command would typically be part of your deployment script, especially if you disabled automatic settings.

$
rake algoliasearch:set_all_settings