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

# Searcher

> Manages search sessions and requests.

export const UserToken = () => <Tooltip tip="A user token is a pseudonymous ID that represents an individual user across Algolia searches and events. It links queries, clicks, and conversions to a user profile, enabling user-level analytics, personalization, and recommendations." cta="User token" href=" /doc/guides/sending-events/concepts/usertoken">
    user token
  </Tooltip>;

export const SearchRequest = () => <Tooltip tip="A search request is a single HTTP call to the Algolia Search API that can run one or more search operations. It can include multiple queries, for example, when querying several indices at once.">
    search request
  </Tooltip>;

export const SearchQuery = () => <Tooltip tip="The text users enter into a search box. In the Search API, this corresponds to the query parameter. A search query is often used with filters, facets, and other parameters, but these aren't part of the query text itself.">
    search query
  </Tooltip>;

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

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>;

export const Facet = () => <Tooltip tip="An attribute in your records that lets users filter or group results (for example, by color, brand, or price)." cta="Faceting" href="/doc/guides/managing-results/refine-results/faceting">
    facet
  </Tooltip>;

export const Events = () => <Tooltip tip="An event is a specific action a user takes in your app or on your website." cta="Events" href="/doc/guides/sending-events">
    events
  </Tooltip>;

## About this widget

This component is handled by objects that implement the [`Searcher` interface](https://github.com/algolia/instantsearch-android/blob/master/instantsearch-core/src/commonMain/kotlin/com/algolia/instantsearch/core/searcher/Searcher.kt).
These objects manage the search session and process each <SearchRequest /> as it occurs.

Algolia provides you with several out of the box searchers to help build your InstantSearch experience:

* `HitsSearcher`: searches a single <Index />.
* `FacetSearcher`: searches for <Facet /> values.
* `MultiSearcher`: searches in multiple indices.
  This is useful for a federated search, or query suggestions search experience.

<Card title="Explore example code" icon="github" href="https://github.com/algolia/instantsearch-android/blob/master/examples/android/src/main/kotlin/com/algolia/instantsearch/examples/android/showcase/androidview/search/SearchAsYouTypeShowcase.kt">
  Browse the Searcher example code on GitHub.
</Card>

## Examples

Instantiating a `HitsSearcher`:

```kotlin Kotlin icon=code theme={"system"}
val searcher = HitsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "index_name",
    isAutoSendingHitsViewEvents = true
)
```

Instantiating a `FacetSearcher`:

```kotlin Kotlin icon=code theme={"system"}
val searcher = FacetsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "index_name",
    attribute = "color"
)
```

Instantiating a `MultiSearcher`:

```kotlin Kotlin icon=code theme={"system"}
val multiSearcher = MultiSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
)
val hitsSearcher = multiSearcher.addHitsSearcher(indexName = "index_name1")
val facetsSearcher = multiSearcher.addFacetsSearcher(
    indexName = "index_name1",
    attribute = "facet_name"
)
```

## HitsSearcher

<ParamField body="indexName" type="String" required>
  The index to search into.

  ```kotlin Kotlin icon=code theme={"system"}
  val indexName = "index_name"
  val searcher = HitsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = indexName
  )
  ```
</ParamField>

<ParamField body="query" type="SearchParamsObject" default="SearchParamsObject()">
  A <SearchQuery />.

  ```kotlin Kotlin icon=code theme={"system"}
  val query = SearchParamsObject(analytics = false)
  val searcher = HitsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = "index_name",
      query = query
  )
  ```
</ParamField>

<ParamField body="isAutoSendingHitsViewEvents" type="Boolean" default={false}>
  Flag defining whether the automatic hits view Insights <Events /> sending is enabled.

  <Note>
    The default value was `true` until version 3.3.1.
  </Note>

  ```kotlin Kotlin icon=code theme={"system"}
  val searcher = HitsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = "index_name",
      isAutoSendingHitsViewEvents = true,
  )
  ```
</ParamField>

<ParamField body="userToken" type="String">
  The user token assigned to automatically send click and conversion events in the `HitsSearcher` component.
  If not explicitly set during initialization,
  the `HitsSearcher` generates and assigns a default user token.
</ParamField>

<ParamField body="requestOptions" type="RequestOptions" default="null">
  RequestOptions that apply to the search.

  ```kotlin Kotlin icon=code theme={"system"}
  val requestOptions = RequestOptions(
      headers = mapOf("X-Forwarded-For" to "1.2.3.4")
  )
  val searcher = HitsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = "index_name",
      requestOptions = requestOptions
  )
  ```
</ParamField>

## FacetSearcher

<ParamField body="indexName" type="String" required>
  The index to search into.

  ```kotlin Kotlin icon=code theme={"system"}
  val indexName = "index_name"
  val searcher = FacetsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = indexName,
      attribute = "color"
  )
  ```
</ParamField>

<ParamField body="attribute" type="String" required>
  An attribute to search facet values for.

  ```kotlin Kotlin icon=code theme={"system"}
  val attribute = "color"
  val searcher = FacetsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = "index_name",
      attribute = attribute
  )
  ```
</ParamField>

<ParamField body="query" type="SearchParamsObject" default="SearchParamsObject()">
  A query used to perform the search.

  ```kotlin Kotlin icon=code theme={"system"}
  val query = SearchParamsObject(analytics = true)
  val searcher = FacetsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = "index_name",
      attribute = "color",
      query = query
  )
  ```
</ParamField>

<ParamField body="requestOptions" type="RequestOptions" default="null">
  `RequestOptions` that apply to the search.

  ```kotlin Kotlin icon=code theme={"system"}
  val requestOptions = RequestOptions(
      headers = mapOf("X-Forwarded-For" to "1.2.3.4")
  )
  val searcher = FacetsSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      indexName = "index_name",
      attribute = "facet_name",
      requestOptions = requestOptions
  )
  ```
</ParamField>

## MultiSearcher

<ParamField body="strategy" type="MultipleQueriesStrategy" default="None">
  The strategy of the query.

  Can be one of the following values:

  * `None`. Execute the sequence of queries until the end.
    This is recommended when each query is of equal importance, meaning all
    <Records /> of all queries need to be returned.
  * `StopIfEnoughMatches`. Execute queries one by one, but stop as soon
    as the cumulated number of hits is at least `hitsPerPage`.
    This is recommended when each query is an alternative,
    and where, if the first returns enough records,
    there is no need to perform the remaining queries.

  ```kotlin Kotlin icon=code theme={"system"}
  val multiSearcher = MultiSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      strategy = MultipleQueriesStrategy.None
  )
  ```
</ParamField>

<ParamField body="requestOptions" type="RequestOptions" default="RequestOptions()">
  `RequestOptions` that apply to the search.

  ```kotlin Kotlin icon=code theme={"system"}
  val requestOptions = RequestOptions(
      headers = mapOf("X-Forwarded-For" to "1.2.3.4")
  )
  val multiSearcher = MultiSearcher(
      applicationID = "YourApplicationID",
      apiKey = "YourSearchOnlyAPIKey",
      requestOptions = requestOptions
  )
  ```
</ParamField>

## Methods

<ParamField body="search">
  Triggers the search and returns a search response.

  ```kotlin Kotlin icon=code theme={"system"}
  searcher.search()
  ```
</ParamField>

<ParamField body="searchAsync">
  Triggers the search.
  Notifies all listeners of the results.

  ```kotlin Kotlin icon=code theme={"system"}
  searcher.searchAsync()
  ```
</ParamField>

<ParamField body="cancel">
  Cancels the ongoing search requests.

  ```kotlin Kotlin icon=code theme={"system"}
  searcher.cancel()
  ```
</ParamField>

<ParamField body="setQuery">
  Sets the query to the string provided.

  ```kotlin Kotlin icon=code theme={"system"}
  searcher.setQuery("foo")
  ```
</ParamField>

## Events

<ParamField body="onLoadingChanged">
  Triggered when the status of the search request is changed.

  ```kotlin Kotlin icon=code theme={"system"}
  searcher.onLoadingChanged += { loading ->
      print(if (loading) "Currently loading search response" else "Done loading")
  }
  ```
</ParamField>

<ParamField body="onResponseChanged">
  Triggered when a new response has arrived.

  ```kotlin Kotlin icon=code theme={"system"}
  searcher.onResponseChanged += { response ->
      val hits = response.hits.deserialize(MovieHit.serializer())
      // Do something with hits...
  }
  ```

  <Note>
    The deserialize extension is deprecated in 4.x.
    Consider parsing hits directly from `SearchResponse.hits`, which returns `List<Hit>` from the Algolia client.
  </Note>
</ParamField>

<ParamField body="onErrorChanged">
  Triggered when an error was encountered during a search request.

  ```kotlin Kotlin icon=code theme={"system"}
  searcher.onErrorChanged += {
     errorTextView.text = it.localizedMessage
  }
  ```
</ParamField>