Text Search in the Aggregation Pipeline¶

Restrictions¶

For general $text operator restrictions, see operator restrictions.

In addition, text search in the aggregation pipeline has the following restrictions:

• The $match stage that includes a $text must be the first stage in the pipeline.
• A text operator can only occur once in the stage.
• The text operator expression cannot appear in $or or $not expressions.
• The text search, by default, does not return the matching documents in order of matching scores. To sort by descending score, use the $meta aggregation expression in the $sort stage.

Text Score¶

The $text operator assigns a score to each document that contains the search term in the indexed fields. The score represents the relevance of a document to a given text search query. The score can be part of a $sort pipeline specification as well as part of the projection expression. The { $meta: "textScore" } expression provides information on the processing of the $text operation. See $meta for details on accessing the score for projection or sort.

The metadata is only available after the $match stage that includes the $text operation.

db.articles.createIndex( { subject: "text" } )

Calculate the Total Views for Articles that Contains a Word¶

The following aggregation searches for the term cake in the $match stage and calculates the total views for the matching documents in the $group stage.

db.articles.aggregate(
   [
     { $match: { $text: { $search: "cake" } } },
     { $group: { _id: null, views: { $sum: "$views" } } }
   ]
)

Return Results Sorted by Text Search Score¶

To sort by the text search score, include a {$meta: "textScore"} expression in the $sort stage. The following example matches on either the term cake or tea, sorts by the textScore in descending order, and returns only the title field in the results set.

db.articles.aggregate(
   [
     { $match: { $text: { $search: "cake tea" } } },
     { $sort: { score: { $meta: "textScore" } } },
     { $project: { title: 1, _id: 0 } }
   ]
)

The specified metadata determines the sort order. For example, the "textScore" metadata sorts in descending order. See $meta for more information on metadata as well as an example of overriding the default sort order of the metadata.

Match on Text Score¶

The "textScore" metadata is available for projections, sorts, and conditions subsequent the $match stage that includes the $text operation.

The following example matches on either the term cake or tea, projects the title and the score fields, and then returns only those documents with a score greater than 1.0.

db.articles.aggregate(
   [
     { $match: { $text: { $search: "cake tea" } } },
     { $project: { title: 1, _id: 0, score: { $meta: "textScore" } } },
     { $match: { score: { $gt: 1.0 } } }
   ]
)

Specify a Language for Text Search¶

The following aggregation searches in spanish for documents that contain the term saber but not the term claro in the $match stage and calculates the total views for the matching documents in the $group stage.

db.articles.aggregate(
   [
     { $match: { $text: { $search: "saber -claro", $language: "es" } } },
     { $group: { _id: null, views: { $sum: "$views" } } }
   ]
)