MongoDB $comment Operator

Beginner
5 min read
Updated: Oct 2026
3 examples
Live preview
MongoDB $comment tutorial — label queries for profiler and logs
Definition

What Is $comment?

$comment is a MongoDB query operator that attaches a label to a query predicate. It does not filter or change documents. The label shows up in logs, the profiler, and currentOp so you can trace the operation later.

Remember
$comment = sticky note on a query (not a filter)

{ <query>, $comment: "<label>" }

results → unchanged
visible in → logs, system.profile, currentOp

find:
  { status: "open", $comment: "dashboard-open" }

$match:
  { $match: { status: "open", $comment: "dashboard-open" } }

whole aggregate:
  db.coll.aggregate(pipeline, { comment: "dashboard-open" })
UsePrefer
Label a find / $match filter$comment
Label an entire aggregation{ comment: "..." } option on aggregate()
Filter documents by a fieldNormal query operators ($eq, etc.)
Approach

How to Use $comment in MongoDB

Write your normal filter, add a short label, then look for that label in profiler or logs when debugging.

  1. Write the real query predicate (find filter or $match).
  2. Add $comment: "short-stable-label" next to the filter fields.
  3. Run the query as usual—results stay the same.
  4. When debugging, search profiler / logs / currentOp for that label.
PieceRequired?Role
Query predicateYesWhat actually filters documents
$commentNo (recommended)Label for logs / profiler / currentOp
comment optionNoLabel the whole aggregate() command

Pseudocode

Pseudocode
query = { status: "open", $comment: "dashboard-open" }

run find(query) or $match(query)
    → return matching documents   // same as without $comment

server metadata for this op:
    comment = "dashboard-open"
    visible in logs / profiler / currentOp
Reference

Cheat Sheet

Keep these facts handy while labeling queries.

TopicDetail
TypeQuery operator (observability)
In find / $match{ ..., $comment: "label" }
On aggregate()aggregate(pipeline, { comment: "label" })
Affects results?No
Visible inLogs, system.profile, currentOp
Good labelFeature, route, or ticket id
Bad labelPasswords, tokens, PII
Try it

Live Preview

Pick a label and see the idea: the filter still matches the same orders, while the comment is stored as operation metadata.

Simulates a find with $comment: same matches, different profiler label.

Result
filter = { status: "open", $comment: "dashboard-open" }

matched documents (unchanged):
  { _id: 1, item: "pens",  status: "open" }
  { _id: 3, item: "clips", status: "open" }

profiler / currentOp metadata:
  comment: "dashboard-open"
Trace

Worked Walkthrough — Same Results, Different Label

Two queries filter status: "open". One has a comment. MongoDB returns the same documents either way.

Calculation
Documents:
  { _id: 1, item: "pens",  status: "open" }
  { _id: 2, item: "pads",  status: "closed" }
  { _id: 3, item: "clips", status: "open" }

Without comment:
  find({ status: "open" })
  → _id 1 and 3

With comment:
  find({ status: "open", $comment: "dashboard-open" })
  → _id 1 and 3   (same)

Difference:
  only the operation metadata carries "dashboard-open"
  so logs / profiler can identify this query later
Code

MongoDB Examples

We store three orders, run a commented find, then the same idea inside $match. Run these in mongosh after inserting the sample data once.

Example 1 — Sample Data

Imagine a tiny orders collection. Two orders are open; one is closed.

mongosh
db.orders.insertMany([
  { _id: 1, item: "pens",  status: "open" },
  { _id: 2, item: "pads",  status: "closed" },
  { _id: 3, item: "clips", status: "open" }
]);

How the Data Is Stored in MongoDB

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

mongosh
db.orders.find()

Read those documents like this:

Field in MongoDBValuePlain English
_id1 … 3Document id for this lesson
item"pens", "pads", "clips"Product name
status"open" or "closed"Order state we will filter on
Picture
Filter status: "open"

  pens   open   → match
  pads   closed → skip
  clips  open   → match

$comment only labels that filter for debugging.

How It Works

  1. Insert once. insertMany adds three order documents.
  2. Statuses differ on purpose. Two open rows make a clear filter result.
  3. find() shows the same shape. Ready for a commented query next.

Example 2 — find with $comment

Goal: return open orders and tag the query as dashboard-open for the profiler.

mongosh
db.orders.find({
  status: "open",
  $comment: "dashboard-open"
});

How It Works

  1. Filter as usual. status: "open" selects pens and clips.
  2. Add the sticky note. $comment: "dashboard-open" does not change matches.
  3. Server keeps the label. Logs / profiler / currentOp can show that string.
  4. Easy check. Remove $comment and you still get the same two documents.

Example 3 — $match with $comment

Same filter inside aggregation. You can also label the whole pipeline with the comment option.

mongosh
db.orders.aggregate(
  [
    {
      $match: {
        status: "open",
        $comment: "dashboard-open-match"
      }
    },
    {
      $project: {
        item: 1,
        status: 1,
        _id: 0
      }
    }
  ],
  { comment: "dashboard-open-pipeline" }
);

How It Works

  1. Filter in the pipeline. $match keeps only open orders.
  2. Label the predicate. $comment inside $match tags that filter.
  3. Label the command. The second argument { comment: "..." } tags the whole aggregation.
  4. Project for a short report. $project keeps item and status only.

Edge Cases & Pitfalls

Check these before relying on $comment in production.

results

It never filters by itself

If you forget the real predicate and only send $comment, you are not selecting by business fields. Always keep the actual match criteria.

secrets

Do not put secrets in comments

Comments can land in logs and profiler collections. Never store passwords, tokens, or personal data in the label.

naming

Use stable, searchable labels

Prefer short fixed strings like checkout-v2 over free-form sentences that change every deploy.

vs option

$comment ≠ aggregate comment option

$comment sits inside a predicate. The comment option on aggregate() labels the whole command. Use either or both on purpose.

Analysis

Performance Notes

ApproachCostBest for
$comment on find / $matchTiny metadata overheadTracing specific filters
comment on aggregate()Tiny metadata overheadTracing whole pipelines
No commentSlightly less metadataOnly when you never need to identify the op

Comments are cheap. The expensive part is still the query itself—indexes and early $match matter far more than the label string.

Remember

Key Takeaways

  • Role: label a query for logs / profiler / currentOp.
  • Results: unchanged—observability only.
  • Places: find filters, $match, and aggregate comment option.
  • Safety: never put secrets in comment strings.

One line: $comment answers “which part of my app ran this query?”—without changing what the query returns.

Frequently Asked Questions

$comment attaches a descriptive label to a query predicate. It does not filter or change documents. The label shows up in mongod logs, the database profiler, and db.currentOp() so you can trace which app code issued the query.
No. Documents returned or modified are the same with or without $comment. It is for observability only.
Anywhere a query predicate is accepted: find(), update/delete filters, and the $match stage in aggregation. You can also pass a comment option on aggregate() to label the whole command.
$comment inside a predicate labels that filter (for example inside $match). The comment option on aggregate() labels the entire aggregation command. Both can appear in profiler output.
No. A JS comment is ignored by the language. $comment is sent to the MongoDB server and stored with the operation metadata so operators and tools can read it later.
Use a short, stable label: feature name, ticket id, or route—for example dashboard-open-orders or checkout-v2. Avoid secrets such as passwords or personal data.

Next: $concat

Join string fields and literals in an aggregation pipeline.

$concat tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

9 people found this page helpful

MongoDB $cmp Operator MongoDB $concat Operator