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

# Search

> Build a search experience for your 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>;

To create a search experience for your app, you can choose between frontend or backend search.

## Frontend search

Use Algolia's UI libraries, InstantSearch and Autocomplete, for client-side searching.
Search requests are made from the browser or app, and results are returned without going through your server.
This ensures rapid searching.

For more information, see:

* [What is InstantSearch?](/doc/guides/building-search-ui/what-is-instantsearch/js)
* [What is Autocomplete?](/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete)
* [Example Rails app with Autocomplete and InstantSearch.js](https://github.com/algolia/algoliasearch-rails-example)

## Backend search

Sometimes, [backend search](/doc/guides/building-search-ui/going-further/backend-search/js#why-backend-search) can be more suitable.
The search request goes from your server to Algolia.

Algolia sends the response back to your server, where you can process it.

### Backend search response

With backend search, you'll get [ORM-compliant](https://guides.rubyonrails.org/active_record_basics.html#object-relational-mapping) Rails model objects.

```ruby Ruby icon=code theme={"system"}
hits = Contact.search("jon doe")
p(hits)
```

The [`search`](/doc/libraries/sdk/v1/methods/search) method accepts a query and [search parameters](/doc/api-reference/search-api-parameters):

```ruby Ruby icon=code theme={"system"}
# Query and search parameters
p(Contact.search("jon doe", {hitsPerPage: 5, page: 2}))
```

If you always pass the same parameters,
set them as [index settings](/doc/framework-integration/rails/index-configuration/index-settings).

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

  algoliasearch do
    # Default search parameters stored in the index settings
    minWordSizefor1Typo 4
    minWordSizefor2Typos 8
    hitsPerPage 42
  end
end
```

Every ORM object of the response contains the [highlighted text](/doc/guides/building-search-ui/ui-and-ux-patterns/highlighting-snippeting/js#highlighting) for the search query.
This corresponds to the `highlight_result` attribute in Algolia's raw response.

```ruby Ruby icon=code theme={"system"}
hits[0].highlight_result["first_name"]["value"]
```

#### Raw search response

To access attributes from the Algolia search response, use the `raw_answer` object:

```ruby Ruby icon=code theme={"system"}
hits = Contact.search("jon doe")
p(hits.raw_answer.nb_hits)
p(hits.raw_answer.nb_pages)
```

If you don't need models, you can avoid loading objects from the database by retrieving Algolia's raw JSON response:

```ruby Ruby icon=code theme={"system"}
json_answer = Contact.raw_search("jon doe")
p(json_answer)
p(json_answer[:hits])
p(json_answer[:facets])
```

#### Search in specific indices

To search in specific indices, specify the <Index /> with the `index` key:

```ruby Ruby icon=code theme={"system"}
Book.search("new america", index: "Book_by_editor")
Book.raw_search("new america", index: "Book_by_editor")
```

To search in a replica index, use the `replica` key:

```ruby Ruby icon=code theme={"system"}
Book.search("new america", replica: "Book_by_editor")
Book.raw_search("new america", replica: "Book_by_editor")
```

### Backend pagination

To add pagination server-side, use one of the following pagination backends:

* [`will_paginate`](https://github.com/mislav/will_paginate)
* [`kaminari`](https://github.com/amatsuda/kaminari)
* [`pagy`](https://github.com/ddnexus/pagy)

To use `:will_paginate`m `:kamari` or `:pagy`,
pass one of them as `:pagination_backend` option to your global configuration:

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

In your controller:

```ruby Ruby icon=code theme={"system"}
@results = MyModel.search("america", hitsPerPage: 10)
# when using Pagy
pagy, @results = MyModel.search("america", hitsPerPage: 10)
```

In your views:

```ruby ERB icon=code theme={"system"}
# If using will_paginate
<%%= will_paginate @results %>

# If using kaminari
<%%= paginate @results %>
```

### Facets

To retrieve facets,
you must first [configure them](/doc/framework-integration/rails/index-configuration/index-settings#faceting-and-filtering).
To retrieve them, use the `facets` method.

```ruby Ruby icon=code theme={"system"}
hits = Contact.search("jon doe", {facets: "*"})
# ORM-compliant array of objects
p(hits)
# Extra method added to retrieve facets
p(hits.facets)
# Facet values+count of facet 'company'
p(hits.facets[:company])
# Facet values+count of facet 'zip_code'
p(hits.facets[:zip_code])
```

Or perform a raw search and access the JSON response attributes:

```ruby Ruby icon=code theme={"system"}
raw_json = Contact.raw_search("jon doe", {facets: "*"})
p(raw_json[:facets])
```

### Search for facet values

If you have more facet values than what can fit in your UI,
it can be helpful to let users [search for them](/doc/guides/managing-results/refine-results/faceting#search-for-facet-values).

If you want to support searching for facet values, configure the facet as
[`searchable`](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting).

```ruby Ruby icon=code theme={"system"}
# Array of {value, highlighted, count}
Product.search_for_facet_values("category", "Headphones")
```

This method accepts search parameters, such as filters.

```ruby Ruby icon=code theme={"system"}
# Only sends back the categories containing red Apple products (and only counts those)
Product.search_for_facet_values(
  "category",
  "phone",
  {
    query: "red",
    filters: "brand:Apple"
    # Array of phone categories linked to red Apple products
  }
)
```