MongoDB $comment Operator

What You’ll Learn

The $comment operator attaches a descriptive label to a MongoDB query. It does not change your data — it helps you find and debug operations in the profiler, logs, and currentOp output.

Definition and Usage

The $comment operator associates a human-readable string with a query predicate. When you enable profiling or inspect server logs, the comment appears next to the operation so you can tell which part of your app issued the query — without guessing from raw BSON.

📝 Syntax

There are two common ways to add comments in aggregation workflows:

1. Inside a query predicate (e.g. $match)

{ $match: { <field>: <value>, $comment: "Your comment here" } }

2. As an option on aggregate()

db.collection.aggregate(
  [ /* pipeline stages */ ],
  { comment: "Your comment here" }
)

Syntax Rules

• $comment — a string (or any valid BSON type) describing the operation.
• Use inside expressions that accept query predicates: $match, find, updateOne, etc.
• The comment option on aggregate() labels the entire command.
• Comments appear in profiler output, logs, and db.currentOp().
• Comments do not filter documents or affect query results.

Examples Gallery

Annotate aggregation pipelines, find queries, and profiler lookups with meaningful comments.

db.orders.aggregate([
  {
    $match: {
      status: "open",
      $comment: "Dashboard: fetch open orders for summary widget"
    }
  },
  {
    $group: {
      _id: "$region",
      total: { $sum: "$amount" }
    }
  }
])

db.movies.aggregate(
  [
    { $match: { year: 1995 } },
    { $limit: 10 },
    { $project: { title: 1, year: 1 } }
  ],
  { comment: "Admin report: top 10 movies from 1995" }
)

db.users
  .find({ active: true })
  .comment("Nightly job: sync active users")
  .limit(1000)

// Equivalent using $comment in the query document:
db.users.find({
  active: true,
  $comment: "Nightly job: sync active users"
}).limit(1000)

// Enable profiling (level 1 = slow ops, level 2 = all ops)
db.setProfilingLevel(1, { slowms: 100 })

// Run your annotated query...
db.orders.aggregate(
  [ { $match: { status: "open" } } ],
  { comment: "Dashboard: open orders summary" }
)

// Find it in the profiler
db.system.profile.find({
  "command.comment": "Dashboard: open orders summary"
}).sort({ ts: -1 }).limit(5)

🚀 Use Cases

• Debugging slow queries — identify which app feature issued an expensive operation.
• Profiler analysis — filter system.profile by comment to isolate recurring patterns.
• Production monitoring — correlate currentOp entries with application code paths.
• Team collaboration — document intent directly in queries shared across developers.

💡 Best Practices