Use text search

Use text search features in Cloud Firestore to search for specific strings within a collection.

Before you begin

Before you start using text queries, do the following:

  1. Ensure that you have access to an existing MongoDB compatible operations database, or Create a database and connect to it.

  2. Ensure that you have a text index, or Create a text index.

IAM permissions

To create an index in Cloud Firestore, make sure that you are assigned any of the following roles:

  • roles/datastore.owner
  • roles/datastore.indexAdmin
  • roles/editor
  • roles/owner

To grant a role, see Grant a single role. For more information about Cloud Firestore roles and associated permissions, see Predefined roles.

If you have defined custom roles, assign all of the following permissions to create indexes:

  • datastore.indexes.create
  • datastore.indexes.delete
  • datastore.indexes.get
  • datastore.indexes.list
  • datastore.indexes.update

Run a text query

Text queries use the $text operator inside a filter. Specify the queried string in the $search argument.

Run a general text query

Run the following query to perform a general query:

  # Find query
  db.cities.find({ $text: { $search: "french bread" } })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "french bread" } } }
  ]);

If your index is partitioned, then you can filter based on the partition by including the partition in an "and" equality filter within your query. For example, if you had a city partition, you could filter a text query as follows:

db.myCollection.find( { $and: [
  { $text: { $search: "french bread" } },
  { "city": "Paris" }
] } )

You can also filter an aggregation based on a partition. For example:

db.myCollection.aggregate([
 { $match: { $text: { $search: "french bread" } } },
 { "city": "Paris" }
] );

The value of your partition must be a string. Your partition filter must be joined to your query by using an "and".

Set the query language

You can set the query language using the $language argument. For example:

  db.cities.find({ $text: { $search: "french bread", $language: "en"} })

If you don't set the query language, then the query uses the language of the text index.

Query an exact term

To query an exact term, configure the term as a sequence of words enclosed by double quotes. For example:

  # Find query
  db.cities.find({ $text: { $search: "\"best french bread\"" } })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "\"best french bread\"" } } },
  ]);

Query a term combination

To make your query more precise, specify a chain of terms. For example, the following query returns documents that match the combination best AND french AND ("bread" OR "is"):

  # Find query
  db.cities.find({ $text: { $search: "\"best\" \"french\" bread is" } })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "\"best\" \"french\" bread is" } } },
  ]);

Exclude a term

To exclude a term from a query, prefix the term with a hyphen (-):

  # Find query
  db.cities.find({ $text: { $search: "best bread -french"} })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "best bread -french" } } },
  ]);

Calculate relevance score

Use the {$meta: "textScore"} expression to calculate the relevance score of the documents matched by the text query. To sort the results in descending score order, use $meta in a sort expression. Consider the following examples, where SCORE_FIELD is the name of the field used to store the score value:

  # Find query
  db.cities
    .find({ $text: { $search: "best french bread" } })
    .sort({ SCORE_FIELD: { $meta: "textScore" } })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "best french bread" } } },
    { $sort: { "SCORE_FIELD": { $meta: "textScore"} } },
  ]);

You can also use text score in projection expressions. For example:

  # Find query
  db.cities
    .find({ $text: { $search: "best french bread" } })
    .project({ score: { $meta: "textScore" } })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "best french bread" } } },
    { $project: { "scoreField": { $meta: "textScore"} } },
  ]);

Expand query

To enhance the relevance of query outcomes, the $text operator augments the search string according to the specified language to include matches for context-aware synonyms, stemmed forms, spelling-corrected terms, diacritic variations and more.

Limitations

  • $near operators and $text operators can't be used in the same the query.
  • A single $text operator is permitted per find or aggregation query.
  • In aggregations, the $match stage with $text must be the first pipeline stage.
  • $text can only be nested inside $and and $or.
  • If $text is inside $or, the non-search disjuncts may use existing ordered indexes to optimize the query. If the other disjuncts are not indexed, then the query will rely on a collection scan.
  • $text cannot be used with query hints.
  • Queries with text search can't sort by $natural.