MongoDB $sortArray Operator

What You’ll Learn

The $sortArray operator sorts elements inside an array field and returns a new sorted array. Use it for ordered tag lists, ranked scores, or product line items sorted by price — all within a single document.

Definition and Usage

In MongoDB’s aggregation framework, the $sortArray operator takes an array and a sort specification, then returns a new sorted array. For example, sorting scores descending: { $sortArray: { input: "$scores", sortBy: -1 } } turns [40, 90, 70] into [90, 70, 40].

Unlike the pipeline $sort stage (which orders documents), $sortArray works on array elements within each document. It is available in MongoDB 5.2 and later.

📝 Syntax

The $sortArray operator uses an object with input and sortBy:

{
  $sortArray: {
    input: <array expression>,
    sortBy: <sort specification>
  }
}

sortBy for Primitives vs Objects

// Array of numbers or strings — use 1 or -1
{ sortBy: 1 }   // ascending
{ sortBy: -1 }  // descending

// Array of documents — use field sort object
{ sortBy: { price: 1 } }
{ sortBy: { score: -1, name: 1 } }

Syntax Rules

• input — array expression (field path, literal, or nested result).
• sortBy — 1/-1 for primitives; object for arrays of documents.
• Returns a new array; the original field is unchanged unless you assign the result back.
• Use inside $project, $addFields, or $set.
• null input returns null.
• Requires MongoDB 5.2+.

Examples Gallery

Sort numeric scores, alphabetize tags, order products by price, and combine with $slice for top-N results using $sortArray.

[
  {
    "_id": 1,
    "name": "Alice",
    "scores": [85, 92, 78, 95],
    "tags": ["beta", "alpha", "gamma"]
  },
  {
    "_id": 2,
    "name": "Bob",
    "scores": [70, 88, 91],
    "tags": ["mongo", "node", "api"]
  }
]

db.players.aggregate([
  {
    $project: {
      name: 1,
      scoresSorted: {
        $sortArray: {
          input: "$scores",
          sortBy: -1
        }
      }
    }
  }
])

// Alice: scoresSorted: [95, 92, 85, 78]
// Bob:   scoresSorted: [91, 88, 70]

db.players.aggregate([
  {
    $project: {
      name: 1,
      tagsSorted: {
        $sortArray: {
          input: "$tags",
          sortBy: 1
        }
      }
    }
  }
])

// Alice: ["alpha", "beta", "gamma"]
// Bob:   ["api", "mongo", "node"]

db.orders.aggregate([
  {
    $project: {
      orderId: 1,
      itemsByPrice: {
        $sortArray: {
          input: "$items",
          sortBy: { price: 1 }
        }
      }
    }
  }
])

// items: [
//   { name: "Mouse", price: 25 },
//   { name: "Keyboard", price: 80 },
//   { name: "Cable", price: 10 }
// ]
// itemsByPrice: Cable, Mouse, Keyboard

db.players.aggregate([
  {
    $project: {
      name: 1,
      topThreeScores: {
        $slice: [
          {
            $sortArray: {
              input: "$scores",
              sortBy: -1
            }
          },
          3
        ]
      }
    }
  }
])

// Alice scores [85,92,78,95] → topThree: [95, 92, 85]

db.classes.aggregate([
  {
    $project: {
      className: 1,
      rosterSorted: {
        $sortArray: {
          input: "$students",
          sortBy: { grade: -1, name: 1 }
        }
      }
    }
  }
])

🚀 Use Cases

• Leaderboards — sort scores and slice the top N per player or team.
• Catalog display — order line items or variants by price or priority inside an order document.
• Tag and category lists — present alphabetized or ranked tags in the UI.
• Data normalization — produce consistent array order before comparison with $setEquals.

💡 Best Practices