MongoDB $meta Operator

Example 1 — Sample Data + Text Index

Imagine six short article titles. We save them in articles, then create a text index on title.

db.articles.insertMany([
  { _id: 1, title: "cakes and ale" },
  { _id: 2, title: "more cakes" },
  { _id: 3, title: "bread" },
  { _id: 4, title: "some cakes" },
  { _id: 5, title: "two cakes to go" },
  { _id: 6, title: "pie" }
]);

db.articles.createIndex({ title: "text" });

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps six documents. Run find() to see them:

db.articles.find()

[
  { _id: 1, title: "cakes and ale" },
  { _id: 2, title: "more cakes" },
  { _id: 3, title: "bread" },
  { _id: 4, title: "some cakes" },
  { _id: 5, title: "two cakes to go" },
  { _id: 6, title: "pie" }
]

Read the setup like this:

How It Works

1. Insert once. Six title documents land in articles.
2. Create a text index. createIndex({ title: "text" }) enables full-text search on titles.
3. Ready for $meta. Without this index, $text and textScore cannot run.

Example 2 — Project textScore

Goal: search for "cake" and show each match’s relevance with $meta.

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

{ _id: 4, title: "some cakes", score: 1 }
{ _id: 1, title: "cakes and ale", score: 0.75 }
{ _id: 5, title: "two cakes to go", score: 0.6666666666666666 }
{ _id: 2, title: "more cakes", score: 1 }

Same idea with find():

db.articles.find(
  { $text: { $search: "cake" } },
  { score: { $meta: "textScore" } }
);

How It Works

1. $match + $text. Keeps only titles that match the word cake.
2. $meta reads metadata. { $meta: "textScore" } copies the relevance score into score.
3. Order may vary. Without an explicit sort, match order is not guaranteed to be best-first.
4. Non-matches stay out. "bread" and "pie" do not appear.

Example 3 — Sort by textScore

Same search, but rank results so the best matches come first.

db.articles.aggregate([
  { $match: { $text: { $search: "cake" } } },
  {
    $addFields: {
      score: { $meta: "textScore" }
    }
  },
  { $sort: { score: { $meta: "textScore" } } }
]);

{ _id: 4, title: "some cakes", score: 1 }
{ _id: 2, title: "more cakes", score: 1 }
{ _id: 1, title: "cakes and ale", score: 0.75 }
{ _id: 5, title: "two cakes to go", score: 0.6666666666666666 }

How It Works

1. Same $text match. Still searching for "cake" on the indexed titles.
2. Expose the score. $addFields + $meta stores relevance in score.
3. Sort by metadata. $sort with { $meta: "textScore" } ranks highest scores first (descending by default).
4. Ties are fine. Both "some cakes" and "more cakes" can share score 1.