IMPORTANT: In July 2025, we stopped releasing new versions of KTX modules, and we removed the KTX libraries from the Firebase Android BoM (v34.0.0). If you use KTX APIs from the previously released KTX modules, we recommend that you migrate your app to use KTX APIs from the main modules instead. For details, see the FAQ about this initiative.

SearchStage

@Beta
class SearchStage : Stage

kotlin.Any
↳	com.google.firebase.firestore.pipeline.Stage
	↳	com.google.firebase.firestore.pipeline.SearchStage

The Search stage executes full-text search or geo search operations.

The Search stage must be the first stage in a Pipeline.

db.pipeline().collection("restaurants").search(
  SearchStage(
    query = documentMatches("waffles OR pancakes"),
    sort = arrayOf(score().descending())
  )
)

Summary

Public companion functions
`SearchStage`	`withQuery(query: BooleanExpression)` Create `SearchStage` with an expression search query.
`SearchStage`	`withQuery(rquery: String)` Create `SearchStage` with a string search query.

Public functions
`open operator Boolean`	`equals(other: Any?)`
`open Int`	`hashCode()`
`SearchStage`	`withAddFields(field: Selectable, vararg additionalFields: Selectable)` Specify the fields to add to each document.
`SearchStage`	`withLanguageCode(languageCode: String)` Specify the BCP-47 language code of text in the search query, such as "en" or "sr".
`SearchStage`	`withLimit(limit: Long)` Specify the maximum number of documents to return.
`SearchStage`	`withOffset(offset: Long)` Specify the number of documents to skip.
`SearchStage`	`withRetrievalDepth(retrievalDepth: Long)` Specify the maximum number of documents to retrieve from the search index.
`SearchStage`	`withSort(order: Ordering, vararg additionalOrderings: Ordering)` Specify how the returned documents are sorted.

Inherited functions

From com.google.firebase.firestore.pipeline.Stage

`SearchStage`	`withOption(key: String, value: <Error class: unknown class>)`
`SearchStage`	`withOption(key: String, value: Boolean)` Specify named `Boolean` parameter
`SearchStage`	`withOption(key: String, value: Double)` Specify named `Double` parameter
`SearchStage`	`withOption(key: String, value: Field)` Specify named `Field` parameter
`SearchStage`	`withOption(key: String, value: Long)` Specify named `Long` parameter
`SearchStage`	`withOption(key: String, value: String)` Specify named `String` parameter

Public companion functions

withQuery

fun withQuery(query: BooleanExpression): SearchStage

Create SearchStage with an expression search query.

query specifies the search query that will be used to query and score documents by the search stage.

The query can be expressed as an Expression, which will be used to score and filter the results. Not all expressions supported by Pipelines are supported in the Search query.

db.pipeline().collection("restaurants").search(
  SearchStage.withQuery(
    or(
      documentContainsText("breakfast"),
      field("menu").containsText("waffle AND coffee")
    )
  )
)

withQuery

fun withQuery(rquery: String): SearchStage

Create SearchStage with a string search query. The string will be used as rquery for searching the document.

query specifies the search query that will be used to query and score documents by the search stage.

db.pipeline().collection("restaurants").search(
  SearchStage.withQuery("breakfast -diner")
)

// The above query is equivalent to:
db.pipeline().collection("restaurants").search(
  SearchStage.withQuery(documentMatches("breakfast -diner"))
)

Public functions

equals

open operator fun equals(other: Any?): Boolean

hashCode

open fun hashCode(): Int

withAddFields

fun withAddFields(field: Selectable, vararg additionalFields: Selectable): SearchStage

Specify the fields to add to each document.

withLanguageCode

fun withLanguageCode(languageCode: String): SearchStage

Specify the BCP-47 language code of text in the search query, such as "en" or "sr".

withLimit

fun withLimit(limit: Long): SearchStage

Specify the maximum number of documents to return. The limit is applied after documents are scored and sorted.

withOffset

fun withOffset(offset: Long): SearchStage

Specify the number of documents to skip.

withRetrievalDepth

fun withRetrievalDepth(retrievalDepth: Long): SearchStage

Specify the maximum number of documents to retrieve from the search index. Documents will be retrieved in the pre-sort order specified by the search index. The retrievalDepth is a limit applied before documents are scored and sorted, which can reduce costs of expensive scoring and sorting operations.

withSort

fun withSort(order: Ordering, vararg additionalOrderings: Ordering): SearchStage

Specify how the returned documents are sorted. One or more ordering are required.