Docs Menu
Docs Home
/
MongoDB Manual
/ / /

$map (aggregation)

On this page

  • Definition
  • Compatibility
  • Syntax
  • Examples
  • Add to Each Element of an Array
  • Truncate Each Array Element
  • Convert Celsius Temperatures to Fahrenheit
  • Learn More
$map

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

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

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

The $map expression has the following syntax:

{ $map: { input: <expression>, as: <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.

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.

In mongosh, create a sample collection named grades with the following documents:

db.grades.insertMany( [
{ quizzes: [ 5, 6, 7 ] },
{ quizzes: [ ] },
{ quizzes: [ 3, 8, 9 ] }
] )

The following aggregation operation uses $map with the $add expression to increment each element in the quizzes array by 2.

db.grades.aggregate( [
{
$project: {
adjustedGrades: {
$map: {
input: "$quizzes",
as: "grade",
in: { $add: [ "$$grade", 2 ] }
}
}
}
}
] )

This operation returns the following results:

[
{
_id: ObjectId("6390b8f7237da390c6869a62"),
adjustedGrades: [ 7, 8, 9 ]
},
{
_id: ObjectId("6390b8f7237da390c6869a63"),
adjustedGrades: []
},
{
_id: ObjectId("6390b8f7237da390c6869a64"),
adjustedGrades: [ 5, 10, 11 ]
}
]

In mongosh, create a sample collection named deliveries with the following documents:

db.deliveries.insertMany( [
{
"city" : "Bakersfield",
"distances" : [ 34.57, 81.96, 44.24 ]
},
{
"city" : "Barstow",
"distances" : [ 73.28, 9.67, 124.36 ]
},
{
"city" : "San Bernadino",
"distances" : [ 16.04, 3.25, 6.82 ]
}
] )

The following aggregation operation uses $map to truncate each element in the distances array to its integer.

db.deliveries.aggregate( [
{
$project: {
city: "$city",
integerValues: {
$map: {
input: "$distances",
as: "decimalValue",
in: { $trunc: "$$decimalValue" }
}
}
}
}
] )

This operation returns the following results:

[
{
_id: ObjectId("6390b9b1237da390c6869a65"),
city: 'Bakersfield',
integerValues: [ 34, 81, 44 ]
},
{
_id: ObjectId("6390b9b1237da390c6869a66"),
city: 'Barstow',
integerValues: [ 73, 9, 124 ]
},
{
_id: ObjectId("6390b9b1237da390c6869a67"),
city: 'San Bernadino',
integerValues: [ 16, 3, 6 ]
}
]

In mongosh, create a sample collection named temperatures with the following documents:

db.temperatures.insertMany( [
{
"date" : ISODate("2019-06-23"),
"tempsC" : [ 4, 12, 17 ]
},
{
"date" : ISODate("2019-07-07"),
"tempsC" : [ 14, 24, 11 ]
},
{
"date" : ISODate("2019-10-30"),
"tempsC" : [ 18, 6, 8 ]
}
] )

The following aggregation operation uses the $addFields stage to add a new field to the documents called tempsF which contains Fahrenheit equivalents of the elements in the tempsC array. To convert from Celsius to Fahrenheit, the operation uses $map to $multiply the Celsius values by 9/5 and then $add 32.

db.temperatures.aggregate( [
{
$addFields: {
"tempsF": {
$map: {
input: "$tempsC",
as: "tempInCelsius",
in: {
$add: [ { $multiply: [ "$$tempInCelsius", 9/5 ] }, 32 ]
}
}
}
}
}
] )

This operation returns the following results:

[
{
_id: ObjectId("6390ba11237da390c6869a68"),
date: ISODate("2019-06-23T00:00:00.000Z"),
tempsC: [ 4, 12, 17 ],
tempsF: [ 39.2, 53.6, 62.6 ]
},
{
_id: ObjectId("6390ba11237da390c6869a69"),
date: ISODate("2019-07-07T00:00:00.000Z"),
tempsC: [ 14, 24, 11 ],
tempsF: [ 57.2, 75.2, 51.8 ]
},
{
_id: ObjectId("6390ba11237da390c6869a6a"),
date: ISODate("2019-10-30T00:00:00.000Z"),
tempsC: [ 18, 6, 8 ],
tempsF: [ 64.4, 42.8, 46.4 ]
}
]

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

Back

$ltrim