/ /

$map (expression operator)

Definition

$map: Applies an expression to each item in an array and returns an array with the applied results.

Compatibility

You can use $map for deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

The $map expression has the following syntax:

{
   $map: {
      input: <expression>,
      as: <string>,
      arrayIndexAs: <string>,
      in: <expression>
   }
}

Field	Specification
`input`	An expression that resolves to an array. If `input` resolves to `null` or refers to a missing field, `$map` returns `null`. If `input` resolves to a non-array, non-null value, the pipeline errors.
`as`	Optional. A name for the variable that represents each individual element of the `input` array. If no name is specified, the variable name defaults to `this`.
`arrayIndexAs`	Optional. A name for the aggregation variable that represents the index of the current element in the `input` array. The first array element index is `0`. You can use the variable name in an expression. For example, if you specify `arrayIndexAs: "myIndex"`, you use `$$myIndex` in the expression. `$$myIndex` returns the index of the current element in the `input` array. If you omit `arrayIndexAs`, you can use the `$$IDX` system variable in the expression to return the index of the current element. For examples, see Access the Index of Each Item in an Array and Use `$$IDX` to Access the Index. New in version 8.3. :
`in`	An expression that is applied to each element of the `input` array. The expression references each element individually with the variable name specified in `as`.

For more information on expressions, see Expressions.

Examples

Add to Each Element of an Array

The examples on this page use data from the sample_mflix sample dataset. For details on how to load this dataset into your self-managed MongoDB deployment, see Load the sample dataset. If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

The following aggregation operation uses $map with the $add expression to add 10 to each element in the location.geo.coordinates array:

db.theaters.aggregate( [
   {
      $match: {
         theaterId: { $in: [ 1000, 1003, 1008 ] }
      }
   },
   {
      $project: {
         _id: 0,
         theaterId: 1,
         adjustedCoordinates: {
            $map: {
               input: "$location.geo.coordinates",
               as: "coord",
               in: { $add: [ "$$coord", 10 ] }
            }
         }
      }
   },
   { $sort: { theaterId: 1 } }
] )

[
  { theaterId: 1000, adjustedCoordinates: [ -83.24565, 54.85466 ] },
  { theaterId: 1003, adjustedCoordinates: [ -66.512016, 48.29697 ] },
  { theaterId: 1008, adjustedCoordinates: [ -111.96328, 48.367649 ] }
]

Truncate Each Array Element

The following aggregation operation uses $map to truncate each element in the location.geo.coordinates array to its integer:

db.theaters.aggregate( [
   {
      $match: {
         theaterId: { $in: [ 1000, 1003, 1008 ] }
      }
   },
   {
      $project: {
         _id: 0,
         theaterId: 1,
         integerCoordinates: {
            $map: {
               input: "$location.geo.coordinates",
               as: "coord",
               in: { $trunc: "$$coord" }
            }
         }
      }
   },
   { $sort: { theaterId: 1 } }
] )

[
  { theaterId: 1000, integerCoordinates: [ -93, 44 ] },
  { theaterId: 1003, integerCoordinates: [ -76, 38 ] },
  { theaterId: 1008, integerCoordinates: [ -121, 38 ] }
]

Apply Arithmetic Operators to Each Array Element

The following aggregation operation uses the $addFields stage to add a new genreScores field. The operation uses $map to apply $multiply and $add to each element in the genres array, computing a score based on the character count of each genre name:

db.movies.aggregate( [
  {
     $match: { runtime: { $gt: 1000 } }
  },
  {
     $addFields: {
        genreScores: {
           $map: {
              input: "$genres",
              as: "genre",
              in: {
                 $add: [
                    { $multiply: [ { $strLenCP: "$$genre" }, 2 ] },
                    1
                 ]
              }
           }
        }
     }
  },
  { $project: { _id: 0, title: 1, genres: 1, genreScores: 1 } },
  { $sort: { title: 1 } }
] )

[
  {
    genres: [ 'Documentary', 'History', 'Sport' ],
    title: 'Baseball',
    genreScores: [ 23, 15, 11 ]
  },
  {
    genres: [ 'Action', 'Adventure', 'Drama' ],
    title: 'Centennial',
    genreScores: [ 13, 19, 11 ]
  }
]

Access the Index of Each Item in an Array

The genres field in the movies collection contains an array of genre names for each movie.

The following example uses arrayIndexAs. The myIndex variable has the index of each genre in the genres array. The example returns documents with these fields:

Movie title.
Genre name.
Position of the genre in the genres array in the rank field.
isPrimary boolean that is true for the first genre in the array, and false for the other genres.

db.movies.aggregate( [
   {
      $match: { runtime: { $gt: 1000 } }
   },
   {
      $project: {
         _id: 0,
         title: 1,
         rankedGenres: {
            $map: {
               input: "$genres",
               as: "genre",
               arrayIndexAs: "myIndex",
               in: {
                  genre: "$$genre",
                  rank: { $add: [ "$$myIndex", 1 ] },
                  isPrimary: { $eq: [ "$$myIndex", 0 ] }
               }
            }
         }
      }
   },
   { $sort: { title: 1 } }
] )

[
  {
    title: 'Baseball',
    rankedGenres: [
      { genre: 'Documentary', rank: 1, isPrimary: true },
      { genre: 'History', rank: 2, isPrimary: false },
      { genre: 'Sport', rank: 3, isPrimary: false }
    ]
  },
  {
    title: 'Centennial',
    rankedGenres: [
      { genre: 'Action', rank: 1, isPrimary: true },
      { genre: 'Adventure', rank: 2, isPrimary: false },
      { genre: 'Drama', rank: 3, isPrimary: false }
    ]
  }
]

Use `$$IDX` to Access the Index

The $$IDX variable returns the index of the current element in the input array. You can use $$IDX if you omit the arrayIndexAs field from the expression.

The following example returns the same documents as the previous example in Access the Index of Each Item in an Array, but uses $$IDX instead of arrayIndexAs:

db.movies.aggregate( [
   {
      $match: { runtime: { $gt: 1000 } }
   },
   {
      $project: {
         _id: 0,
         title: 1,
         rankedGenres: {
            $map: {
               input: "$genres",
               as: "genre",
               in: {
                  genre: "$$genre",
                  rank: { $add: [ "$$IDX", 1 ] },
                  isPrimary: { $eq: [ "$$IDX", 0 ] }
               }
            }
         }
      }
   },
   { $sort: { title: 1 } }
] )

[
  {
    title: 'Baseball',
    rankedGenres: [
      { genre: 'Documentary', rank: 1, isPrimary: true },
      { genre: 'History', rank: 2, isPrimary: false },
      { genre: 'Sport', rank: 3, isPrimary: false }
    ]
  },
  {
    title: 'Centennial',
    rankedGenres: [
      { genre: 'Action', rank: 1, isPrimary: true },
      { genre: 'Adventure', rank: 2, isPrimary: false },
      { genre: 'Drama', rank: 3, isPrimary: false }
    ]
  }
]

Learn More

To learn more about expressions used in the previous examples, see:

Back

$ltrim

$maxN-array-element