Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
Click here >
Docs Menu
Docs Home
/ /
Expressions
Docs Home
/
Development
/
Query Language
/
Expressions
Docs Home
/
Development
/
Query Language
/
Expressions

$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

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

Next

$maxN-array-element

On this page