MongoDB $nin Operator

What You’ll Learn

The $nin operator matches documents when a field’s value is not in a specified list. Use it in $match to exclude multiple statuses, categories, or IDs in one query instead of chaining many $ne conditions.

Definition and Usage

In MongoDB, the $nin operator selects documents where a field’s value does not appear in a specified array. For example, { status: { $nin: [ "archived", "cancelled" ] } } returns every document whose status is neither "archived" nor "cancelled". It is the direct opposite of $in.

In aggregation expressions, { $nin: [ "$role", [ "guest", "banned" ] ] } returns true when the field value is not in the array. This is useful for access checks and conditional labeling.

📝 Syntax

$nin has two forms depending on where you use it:

Query form (in $match or find filters)

{ field: { $nin: [ <value1>, <value2>, ... ] } }

Aggregation expression form (in $project, $cond, etc.)

{ $nin: [ <expression>, <array expression> ] }

Syntax Rules

• Query form — keeps documents where the field does not equal any value in the array.
• Expression form — returns true when the first operand is not found in the second array.
• If the field is an array, a document is excluded when any element in the field array matches a listed value.
• Values must match BSON types exactly (no automatic type conversion).
• An empty $nin array { field: { $nin: [] } } matches all documents.
• Query $nin also matches documents where the field is missing or null.

Examples Gallery

Exclude inactive statuses, filter in find(), add boolean access flags, and drive conditional logic with $nin.

[
  { "_id": ObjectId("609c26812e9274a86871bc6a"), "orderId": "ORD-101", "customer": "Alice", "status": "active" },
  { "_id": ObjectId("609c26812e9274a86871bc6b"), "orderId": "ORD-102", "customer": "Bob",   "status": "archived" },
  { "_id": ObjectId("609c26812e9274a86871bc6c"), "orderId": "ORD-103", "customer": "Carol", "status": "pending" },
  { "_id": ObjectId("609c26812e9274a86871bc6d"), "orderId": "ORD-104", "customer": "Dave",  "status": "cancelled" }
]

db.orders.aggregate([
  {
    $match: {
      status: {
        $nin: [ "archived", "cancelled" ]
      }
    }
  }
])

{ "orderId": "ORD-101", "customer": "Alice", "status": "active" }
{ "orderId": "ORD-103", "customer": "Carol", "status": "pending" }

db.products.find({
  category: {
    $nin: [ "discontinued", "internal" ]
  }
})

// Returns products NOT in "discontinued" or "internal"
// electronics, books, clothing → included
// discontinued, internal       → excluded

db.users.aggregate([
  {
    $project: {
      name: 1,
      role: 1,
      hasAccess: {
        $nin: [
          "$role",
          [ "guest", "banned" ]
        ]
      }
    }
  }
])

// role: "admin"  → hasAccess: true  (not in blocklist)
// role: "editor"  → hasAccess: true
// role: "guest"    → hasAccess: false (in blocklist)
// role: "banned"   → hasAccess: false

db.products.aggregate([
  {
    $project: {
      name: 1,
      category: 1,
      visibility: {
        $cond: [
          {
            $nin: [
              "$category",
              [ "discontinued", "internal" ]
            ]
          },
          "visible",
          "hidden"
        ]
      }
    }
  }
])

db.articles.find({
  tags: {
    $nin: [ "spam", "draft" ]
  }
})

// tags: ["mongodb", "tutorial"]     → included
// tags: ["mongodb", "draft"]         → excluded (draft in tags)
// tags: ["spam"]                     → excluded

🚀 Use Cases

• Status blocklists — hide archived, cancelled, or deleted records from active views.
• Category filtering — exclude discontinued or internal products from public catalogs.
• Access control — flag users whose roles are not in an allowed set (or are in a denied set).
• Content moderation — filter out documents tagged with blocked keywords.

💡 Best Practices