MongoDB $objectToArray Operator

What Is $objectToArray?

$objectToArray is a MongoDB aggregation expression that turns an object into an array of { k, v } pairs—one element per top-level field. It is the inverse of $arrayToObject.

$objectToArray = object → [ { k, v }, ... ]

{ $objectToArray: <objectExpression> }

input:
  { theme: "dark", lang: "en" }

output:
  [
    { k: "theme", v: "dark" },
    { k: "lang",  v: "en" }
  ]

k → field name (string)
v → field value
top-level only (not recursive)
null / missing → null

How to Use $objectToArray in MongoDB

Point at an embedded object field, convert it to pairs, then optionally unwind.

1. Choose an expression stage ($addFields or $project).
2. Write { $objectToArray: "$settings" }.
3. Read each pair as k (key) and v (value).
4. Optionally $unwind the array for one document per field.

Pseudocode

obj = evaluate(objectExpression)
if obj is null or missing:
    result = null
else:
    result = []
    for each top-level field in obj:
        append { k: fieldName, v: fieldValue }
    emit { ..., field: result }

Cheat Sheet

Keep these facts handy while converting objects to arrays.

Live Preview

Watch $objectToArray turn a small object into { k, v } pairs.

input:
  { theme: "dark", lang: "en" }

$objectToArray →
  [
    { k: "theme", v: "dark" },
    { k: "lang", v: "en" }
  ]

Worked Walkthrough — Settings Object

A user has settings: { theme: "dark", lang: "en" }. We want an array of pairs.

Object:
  { theme: "dark", lang: "en" }

Field by field:
  theme → { k: "theme", v: "dark" }
  lang  → { k: "lang",  v: "en" }

$objectToArray result:
  [
    { k: "theme", v: "dark" },
    { k: "lang",  v: "en" }
  ]

MongoDB Examples

We use one user document with a settings object. First we store it, then we convert to pairs, then we unwind to one document per setting. Run these in mongosh after inserting the sample data once.

db.users.insertOne({
  _id: 1,
  name: "Asha",
  settings: {
    theme: "dark",
    lang: "en"
  }
});

db.users.find()

{
  _id: 1,
  name: "Asha",
  settings: {
    theme: "dark",
    lang: "en"
  }
}

settings object          $objectToArray
─────────────────        ─────────────────────────
theme: "dark"    →       { k: "theme", v: "dark" }
lang:  "en"      →       { k: "lang",  v: "en" }

db.users.aggregate([
  {
    $addFields: {
      pairs: { $objectToArray: "$settings" }
    }
  }
]);

{
  _id: 1,
  name: "Asha",
  settings: { theme: "dark", lang: "en" },
  pairs: [
    { k: "theme", v: "dark" },
    { k: "lang", v: "en" }
  ]
}

db.users.aggregate([
  {
    $project: {
      name: 1,
      pairs: { $objectToArray: "$settings" }
    }
  },
  { $unwind: "$pairs" },
  {
    $project: {
      name: 1,
      key: "$pairs.k",
      value: "$pairs.v"
    }
  }
]);

[
  { _id: 1, name: "Asha", key: "theme", value: "dark" },
  { _id: 1, name: "Asha", key: "lang", value: "en" }
]

Performance Notes

Converting a small settings-style object is inexpensive. Unwinding multiplies document count—filter early when you only need some keys.

Key Takeaways