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

Objects conforming to the [Searcher protocol](https://github.com/algolia/instantsearch-core-swift/blob/master/Sources/Searcher/Searcher.swift)
manage the search sessions.

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`. Aggregates the hits and facet searchers. This is useful for building a federated search, or query suggestions.

<Card title="Explore example code" icon="github" href="https://github.com/algolia/instantsearch-ios/tree/master/Examples/Showcase">
  Browse the Searcher example code on GitHub.
</Card>

## Examples

Instantiate a `HitsSearcher`.

```swift Swift icon=code theme={"system"}
let searcher = HitsSearcher(appID: "YourApplicationID",
                            apiKey: "YourSearchOnlyApiKey",
                            indexName: "index_name",
                            isAutoSendingHitsViewEvents: true)
```

Instantiate a `FacetSearcher`.

```swift Swift icon=code theme={"system"}
let searcher = FacetSearcher(appID: "YourApplicationID",
                             apiKey: "YourSearchOnlyApiKey",
                             indexName: "index_name",
                             facetName: "facet_name")
```

Instantiate a `MultiSearcher`.

```swift Swift icon=code theme={"system"}
let searcher = MultiSearcher(appID: "YourApplicationID",
                             apiKey: "YourSearchOnlyApiKey")
searcher.addHitsSearcher(indexName: "index_name1")
searcher.addFacetsSearcher(indexName: "index_name1",
                            attribute: "facet_name")
searcher.addHitsSearcher(indexName: "index_name2")
```

## HitsSearcher

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

  ```swift Swift icon=code theme={"system"}
  let searcher = HitsSearcher(appID: "YourApplicationID",
                              apiKey: "YourSearchOnlyApiKey",
                              indexName: "index_name")
  ```
</ParamField>

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

  ```swift Swift icon=code theme={"system"}
  let query = Query()
  query.analytics = true
  let searcher = HitsSearcher(appID: "YourApplicationID",
                              apiKey: "YourSearchOnlyApiKey",
                              indexName: "index_name",
                              query: query)
  ```
</ParamField>

<ParamField body="isAutoSendingHitsViewEvents" type="Bool" default={false} post={["since: v7.26.2"]}>
  Whether to automatically send view <Events /> for hits.

  ```swift Swift icon=code theme={"system"}
  let searcher = HitsSearcher(appID: "YourApplicationID",
                              apiKey: "YourSearchOnlyApiKey",
                              indexName: "index_name",
                              isAutoSendingHitsViewEvents: true)
  ```
</ParamField>

## FacetSearcher

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

  ```swift Swift icon=code theme={"system"}
  let searcher = FacetSearcher(appID: "YourApplicationID",
                               apiKey: "YourSearchOnlyApiKey",
                               indexName: "index_name")
  ```
</ParamField>

<ParamField body="facetName" type="String" required>
  The facet name to search into when doing search for facet values.

  ```swift Swift icon=code theme={"system"}
  let searcher = FacetSearcher(appID: "YourApplicationID",
                               apiKey: "YourSearchOnlyApiKey",
                               indexName: "index_name",
                               facetName: "facet_name")
  ```
</ParamField>

<ParamField body="query" type="Query" default="Query()">
  The query used when doing a search.

  ```swift Swift icon=code theme={"system"}
  let query = Query()
  query.analytics = true
  let searcher = FacetSearcher(appID: "YourApplicationID",
                               apiKey: "YourSearchOnlyApiKey",
                               indexName: "index_name",
                               query: query)
  ```
</ParamField>

## Methods

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

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

<ParamField body="cancel">
  Cancels every ongoing <SearchRequest />.

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

## Events

<ParamField body="isLoading">
  Triggered when the `Searcher` starts or finishes query execution.

  ```swift Swift icon=code theme={"system"}
  searcher.isLoading.subscribe(with: self) { (_, isLoading) in

  }
  ```
</ParamField>

<ParamField body="onQueryChanged">
  Triggered when the query text is modified.

  ```swift Swift icon=code theme={"system"}
  searcher.onQueryChanged.subscribe(with: self) { (_, query) in

  }
  ```
</ParamField>

<ParamField body="onResults">
  Triggered when a new search result is received.

  ```swift Swift icon=code theme={"system"}
  searcher.onResults.subscribe(with: self) { (_, results) in

  }
  ```
</ParamField>

<ParamField body="onError">
  Triggered when a new error is received.

  ```swift Swift icon=code theme={"system"}
  searcher.onError.subscribe(with: self) { (_, args) in
    let (query, error) = args

  }
  ```
</ParamField>