Searcher

Manages search sessions and requests.

About this widget

This component is handled by objects that implement the Searcher interface. These objects manage the search session and process each search request 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.

Explore example code

Examples

Instantiating a HitsSearcher:

Kotlin

val searcher = HitsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "index_name",
    isAutoSendingHitsViewEvents = true
)

Instantiating a FacetSearcher:

Kotlin

val searcher = FacetsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "index_name",
    attribute = "color"
)

Instantiating a MultiSearcher:

Kotlin

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

indexName · String · required

The index to search into.

Kotlin

val indexName = "index_name"
val searcher = HitsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = indexName
)

query · SearchParamsObject · default: "SearchParamsObject()"

A search query.

Kotlin

val query = SearchParamsObject(analytics = false)
val searcher = HitsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "index_name",
    query = query
)

isAutoSendingHitsViewEvents · Boolean · default: false

Flag defining whether the automatic hits view Insights events sending is enabled.

The default value was true until version 3.3.1.

Kotlin

val searcher = HitsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "index_name",
    isAutoSendingHitsViewEvents = true,
)

userToken · 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.

requestOptions · RequestOptions · default: "null"

RequestOptions that apply to the search.

Kotlin

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
)

FacetSearcher

indexName · String · required

The index to search into.

Kotlin

val indexName = "index_name"
val searcher = FacetsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = indexName,
    attribute = "color"
)

attribute · String · required

An attribute to search facet values for.

Kotlin

val attribute = "color"
val searcher = FacetsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "index_name",
    attribute = attribute
)

query · SearchParamsObject · default: "SearchParamsObject()"

A query used to perform the search.

Kotlin

val query = SearchParamsObject(analytics = true)
val searcher = FacetsSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    indexName = "index_name",
    attribute = "color",
    query = query
)

requestOptions · RequestOptions · default: "null"

RequestOptions that apply to the search.

Kotlin

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
)

MultiSearcher

strategy · 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

val multiSearcher = MultiSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    strategy = MultipleQueriesStrategy.None
)

requestOptions · RequestOptions · default: "RequestOptions()"

RequestOptions that apply to the search.

Kotlin

val requestOptions = RequestOptions(
    headers = mapOf("X-Forwarded-For" to "1.2.3.4")
)
val multiSearcher = MultiSearcher(
    applicationID = "YourApplicationID",
    apiKey = "YourSearchOnlyAPIKey",
    requestOptions = requestOptions
)

Methods

search

Triggers the search and returns a search response.

Kotlin

searcher.search()

searchAsync

Triggers the search. Notifies all listeners of the results.

Kotlin

searcher.searchAsync()

cancel

Cancels the ongoing search requests.

Kotlin

searcher.cancel()

setQuery

Sets the query to the string provided.

Kotlin

searcher.setQuery("foo")

Events

onLoadingChanged

Triggered when the status of the search request is changed.

Kotlin

searcher.onLoadingChanged += { loading ->
    print(if (loading) "Currently loading search response" else "Done loading")
}

onResponseChanged

Triggered when a new response has arrived.

Kotlin

searcher.onResponseChanged += { response ->
    val hits = response.hits.deserialize(MovieHit.serializer())
    // Do something with hits...
}

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

onErrorChanged

Triggered when an error was encountered during a search request.

Kotlin

searcher.onErrorChanged += {
   errorTextView.text = it.localizedMessage
}