MongoDB $type Operator

What You’ll Learn

The $type operator works with BSON data types. Use it in find() queries to filter documents by field type, or in aggregation pipelines to inspect what type a value actually is.

Definition and Usage

MongoDB stores values in BSON format, and each value has a type such as string, double, int, array, object, or null. The $type operator lets you work with those types in two ways.

As a query operator, it filters documents where a field matches a specified type. As an aggregation expression, it returns the BSON type name of a value. This is especially useful when cleaning imported data, auditing schema inconsistencies, or debugging mixed-type fields.

📝 Syntax

Query Syntax (find / $match)

Filter documents where a field is a specific BSON type:

{ <field>: { $type: <BSON type> } }

// Examples:
{ age: { $type: "number" } }
{ name: { $type: "string" } }
{ tags: { $type: "array" } }
{ value: { $type: ["string", "null"] } }

Aggregation Expression Syntax

Return the BSON type name of an expression:

{ $type: <expression> }

// Examples:
{ $type: "$price" }
{ $type: "$tags" }
{ $type: 42 }

Common BSON Type Aliases

// String aliases (most common in tutorials)
"double", "string", "object", "array", "bool", "date",
"null", "int", "long", "decimal", "objectId", "number"

// Numeric codes also work in queries
{ age: { $type: 16 } }   // 16 = int
{ name: { $type: 2 } }   // 2  = string

Syntax Rules

• Query form — use on a field in find() or $match filters.
• Expression form — use inside $project, $addFields, $cond, or $expr.
• "number" — matches int, long, double, and decimal types.
• Array of types — query form only; matches any listed type.
• Expression form returns a string like "double" or "string".
• Missing fields in expression form return "missing".

Examples Gallery

Filter a mixed-type records collection by BSON type in queries, inspect types in aggregation, and find schema inconsistencies with $type.

[
  { "_id": 1, "label": "Score A", "value": 95 },
  { "_id": 2, "label": "Score B", "value": "88" },
  { "_id": 3, "label": "Tags",    "value": ["mongo", "db"] },
  { "_id": 4, "label": "Empty",   "value": null },
  { "_id": 5, "label": "Meta",    "value": { active: true } }
]

db.records.find({
  value: { $type: "string" }
})

// Returns: { _id: 2, label: "Score B", value: "88" }

{ "_id": 2, "label": "Score B", "value": "88" }

db.records.find({
  value: { $type: "number" }
})

// Returns: { _id: 1, label: "Score A", value: 95 }

// Documents where value is null
db.records.find({
  value: { $type: "null" }
})

// Documents where value is string OR null
db.records.find({
  value: { $type: ["string", "null"] }
})

// Returns for array query:
// { _id: 2, label: "Score B", value: "88" }
// { _id: 4, label: "Empty",   value: null }

db.records.aggregate([
  {
    $project: {
      label: 1,
      value: 1,
      valueType: { $type: "$value" }
    }
  }
])

{ "_id": 1, "label": "Score A", "value": 95,           "valueType": "int" }
{ "_id": 2, "label": "Score B", "value": "88",         "valueType": "string" }
{ "_id": 3, "label": "Tags",    "value": ["mongo","db"], "valueType": "array" }
{ "_id": 4, "label": "Empty",   "value": null,         "valueType": "null" }
{ "_id": 5, "label": "Meta",    "value": { active: true }, "valueType": "object" }

db.records.aggregate([
  {
    $match: {
      $expr: {
        $eq: [
          { $type: "$value" },
          "string"
        ]
      }
    }
  },
  {
    $project: {
      label: 1,
      value: 1,
      valueType: { $type: "$value" }
    }
  }
])

// Same result as find({ value: { $type: "string" } })
// but useful when type logic is part of a longer pipeline

db.records.aggregate([
  {
    $project: {
      label: 1,
      value: 1,
      valueType: { $type: "$value" },
      needsFix: {
        $cond: [
          {
            $in: [
              { $type: "$value" },
              ["int", "long", "double", "decimal"]
            ]
          },
          false,
          true
        ]
      }
    }
  }
])

// Score B (value: "88") → needsFix: true
// Score A (value: 95)   → needsFix: false

🚀 Use Cases

• Schema auditing — find fields stored as the wrong BSON type after imports.
• Data cleanup — filter string numbers like "42" before converting them.
• Null detection — locate explicit null values vs missing fields.
• Pipeline validation — inspect types before applying math or array operators.
• Migration checks — verify documents match expected types after schema changes.

💡 Best Practices