> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Algolia for Ruby on Rails

> Integrate Algolia with your Ruby on Rails app.

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

Check the [`algoliasearch-rails-example`](https://github.com/algolia/algoliasearch-rails-example) repository on GitHub for a sample Rails app with Autocomplete and InstantSearch results pages.

## Compatibility

This gem supports:

* Ruby versions 2.5 and later
* Ruby on Rails versions 6 and 7.

This gem is compatible with:

* [ActiveRecord](https://github.com/rails/rails/tree/master/activerecord),
* [Mongoid](https://github.com/mongoid/mongoid)
* [Sequel](https://github.com/jeremyevans/sequel).

## Install

Install the gem directly:

```sh Command line icon=square-terminal theme={"system"}
gem install algoliasearch-rails
```

Or add it to your `Gemfile`:

```rb theme={"system"}
gem "algoliasearch-rails"
```

And run:

```sh Command line icon=square-terminal theme={"system"}
bundle install
```

## Configure

To configure the gem, create a new file `config/initializers/algoliasearch.rb`.

Add your Algolia credentials, the application ID and the API key.
You can find both in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).

```ruby Ruby icon=code theme={"system"}
AlgoliaSearch.configuration = {
  application_id: "ALGOLIA_APPLICATION_ID",
  api_key: "ALGOLIA_API_KEY"
}
```

### API client with custom settings

To customize settings such as timeout for the API client, you can make the Algolia gem use your instance of an API client.
You can do this by setting the `AlgoliaSearch.client` option to your initialized client:

```ruby Ruby icon=code theme={"system"}
# your options
opts = {}
AlgoliaSearch.client = Algolia::SearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", opts)
```

### The `algoliasearch` block

To send your model to Algolia,
include the `AlgoliaSearch` module and the `algoliasearch` block.
This block sets up your <Index /> and options.
If you want to use the default options, declare an empty block.

```ruby Ruby icon=code theme={"system"}
class Contact < ActiveRecord::Base
  include AlgoliaSearch

  algoliasearch do
    # Use all default configuration
  end
end
```

### Example configuration

To see a full configuration example,
see the [repository](https://github.com/algolia/hn-search/blob/e27760e09840a6fa3efc592649fceb89237e4c2f/app/models/item.rb)
for the [HN Search app](https://hn.algolia.com/).

## Method name and aliases

All methods injected by the `AlgoliaSearch` module have the prefix `algolia_` and are aliased to short names if they aren't already defined by Rails:

```ruby Ruby icon=code theme={"system"}
# Both calls do the same
Contact.algolia_reindex!
Contact.reindex!

# Both calls to the same
Contact.algolia_search("jon doe")
Contact.search("jon doe")
```