Ordenando pela pontuação de texto com $meta

When a $text query runs, MongoDB computes a relevance score for every matching document called the textScore. This score reflects how well the document matches the search terms: more occurrences of the search terms, matches in higher-weighted fields, and matches of rarer tokens all increase the score. By default, results are not sorted by score; you must request the sort explicitly.

To include the relevance score in your results, add a projection field using { $meta: 'textScore' }. You can name this field anything you like (conventionally score). The $meta expression reads metadata computed during query execution—textScore is the only metadata value currently supported in this context.

To sort results by relevance, pass { score: { $meta: 'textScore' } } to .sort(). MongoDB sorts in descending order by default for textScore (highest relevance first). You must project the score field in the same query when sorting by it—if you omit the projection, MongoDB will still sort correctly but won't return the score value to the client.

MongoDB's textScore is based on a variant of TF-IDF (Term Frequency – Inverse Document Frequency) logic. Term frequency: a document with the search word appearing 10 times scores higher than one where it appears once. Field weights: matches in a field with weight 10 score 10× higher than matches in a weight-1 field. Index density: rarer words that appear in fewer documents contribute more to the score than very common words.

In aggregation pipelines, use { $meta: 'textScore' } inside a $addFields or $project stage to attach the score, then pipe into $sort. Remember: the $match stage with $text must come first in the pipeline so MongoDB can compute the score before other stages transform the document stream.

You can combine textScore sorting with other sort keys. For example, sort by relevance first, then by date as a tiebreaker. MongoDB processes sort keys left to right, so put textScore first to prioritise relevance. The additional sort keys only determine order among documents with equal textScore values.

If you want to return only highly relevant documents, you can filter by a minimum textScore using the $meta expression inside a $match stage (in aggregation) after the text match. This is not possible with a direct find() filter; you need the aggregation pipeline to compute the score first and then filter on it.

The textScore values are relative within a query result set, not absolute or comparable across different queries or different collection states. A score of 2.5 today might become 3.1 tomorrow if you add more documents to the collection (changing term frequency calculations). Use textScore for sorting within a result set, not as a stored quality metric.

Standard skip()/limit() pagination works with text search, but it has the usual performance issue at deep offsets. Since results are relevance-ranked rather than ordered by a stable field, keyset pagination is not straightforward for text results. A common pattern is to use offset pagination for the first few pages (where most users stop) and consider Atlas Search for deeper, more consistent pagination at scale.

When using Mongoose, you access textScore via the { meta: 'textScore' } option on a schema path or by using .select() with the score meta projection. Mongoose wraps the MongoDB driver's API, so the underlying concept is the same—you just need to know the Mongoose syntax for projecting and sorting by metadata.

Native text indexes work well for simple use cases, but they lack features like autocomplete, faceted search, synonyms, and custom ranking functions. When you need these capabilities, MongoDB Atlas Search (built on Apache Lucene) provides a much richer relevance scoring engine with BM25 scoring, boosting, and explain output for tuning relevance.

Test your understanding of sorting by text score with $meta.

In this lesson you learned: textScore is a per-document relevance score computed during $text queries, { $meta: 'textScore' } projects and sorts by this score, and field weights and term frequency determine the score magnitude. Next up we cover text index limitations and when Atlas Search is the better choice.