MongoDB $objectToArray Operator

What You’ll Learn

The $objectToArray operator converts an object into an array of { k, v } pairs. Use it when you need to iterate over dynamic keys, flatten metadata, or reshape nested objects for reporting.

Definition and Usage

In MongoDB’s aggregation framework, the $objectToArray operator takes an object and returns an array where each property becomes one element. For example, { theme: "dark", lang: "en" } becomes [ { k: "theme", v: "dark" }, { k: "lang", v: "en" } ].

This is especially useful for objects with dynamic or unknown keys — user preferences, product attributes, or configuration maps — where you cannot hard-code field names.

📝 Syntax

The $objectToArray operator takes one object expression:

{ $objectToArray: <object expression> }

Output Format

// Input object:
{ color: "blue", size: "M" }

// Output array:
[
  { k: "color", v: "blue" },
  { k: "size",  v: "M" }
]

Syntax Rules

• Argument — any expression that evaluates to an object (field path or literal).
• Output — array of documents with string k and any-type v.
• Use inside $project, $addFields, or $set.
• An empty object {} returns an empty array [].
• null or missing input returns null.
• Pair with $unwind to process one key-value pair per document.

Examples Gallery

Convert settings objects to arrays, unwind key-value pairs, filter by key, and round-trip with $arrayToObject.

[
  {
    "_id": 1,
    "username": "alice",
    "settings": {
      "theme": "dark",
      "notifications": true,
      "language": "en"
    }
  },
  {
    "_id": 2,
    "username": "bob",
    "settings": {
      "theme": "light",
      "notifications": false,
      "language": "fr"
    }
  }
]

db.users.aggregate([
  {
    $project: {
      username: 1,
      settingsArray: { $objectToArray: "$settings" }
    }
  }
])

{
  "username": "alice",
  "settingsArray": [
    { "k": "theme", "v": "dark" },
    { "k": "notifications", "v": true },
    { "k": "language", "v": "en" }
  ]
}

db.users.aggregate([
  {
    $project: {
      username: 1,
      pair: { $objectToArray: "$settings" }
    }
  },
  { $unwind: "$pair" },
  {
    $project: {
      username: 1,
      settingKey: "$pair.k",
      settingValue: "$pair.v"
    }
  }
])

{ "username": "alice", "settingKey": "theme",          "settingValue": "dark" }
{ "username": "alice", "settingKey": "notifications", "settingValue": true }
{ "username": "alice", "settingKey": "language",      "settingValue": "en" }

db.users.aggregate([
  {
    $project: {
      username: 1,
      pairs: { $objectToArray: "$settings" }
    }
  },
  { $unwind: "$pairs" },
  {
    $match: {
      "pairs.k": "theme",
      "pairs.v": "dark"
    }
  },
  {
    $project: {
      username: 1,
      theme: "$pairs.v"
    }
  }
])

db.users.aggregate([
  {
    $project: {
      username: 1,
      settingsRestored: {
        $arrayToObject: {
          $objectToArray: "$settings"
        }
      }
    }
  }
])

db.products.aggregate([
  {
    $project: {
      name: 1,
      attr: { $objectToArray: "$attributes" }
    }
  },
  { $unwind: "$attr" },
  {
    $project: {
      product: "$name",
      attribute: "$attr.k",
      value: "$attr.v"
    }
  }
])

// attributes: { weight: 2.5, color: "blue" }
// → two rows: weight/2.5 and color/blue

🚀 Use Cases

• Dynamic key iteration — process objects when field names are not fixed at design time.
• Settings flattening — convert preference objects into rows for reporting.
• Attribute normalization — reshape product specs or metadata for export.
• Pipeline transforms — modify key-value pairs with $map before converting back with $arrayToObject.

💡 Best Practices