# $max (aggregation)¶

## Definition¶

`$max`

¶Returns the maximum value.

`$max`

compares both value and type, using the specified BSON comparison order for values of different types.`$max`

is available in the following stages:`$group`

`$project`

`$addFields`

(Available starting in MongoDB 3.4)`$set`

(Available starting in MongoDB 4.2)`$replaceRoot`

(Available starting in MongoDB 3.4)`$replaceWith`

(Available starting in MongoDB 4.2)`$match`

stage that includes an`$expr`

expression

In MongoDB 3.2 and earlier,

`$max`

is available in the`$group`

stage only.When used in the

`$group`

stage,`$max`

has the following syntax and returns the maximum value that results from applying an expression to each document in a group of documents that share the same group by key:{ $max: <expression> } When used in the other supported stages,

`$max`

returns the maximum of the specified expression or list of expressions for each document and has one of two syntaxes:`$max`

has one specified expression as its operand:{ $max: <expression> } `$max`

has a list of specified expressions as its operand:{ $max: [ <expression1>, <expression2> ... ] }

For more information on expressions, see Expressions.

## Behavior¶

### Null or Missing Values¶

If some, **but not all**, documents for the `$max`

operation have either a `null`

value for the field or are
missing the field, the `$max`

operator only considers the
non-null and the non-missing values for the field.

If **all** documents for the `$max`

operation have `null`

value for the field or are missing the field, the `$max`

operator returns `null`

for the maximum value.

### Array Operand¶

In the `$group`

stage, if the expression resolves to an
array, `$max`

does not traverse the array and compares the array
as a whole.

In the other supported stages:

- With a single expression as its operand, if the expression resolves
to an array,
`$max`

traverses into the array to operate on the numerical elements of the array to return a single value. - With a list of expressions as its operand, if any of the expressions
resolves to an array,
`$max`

does**not**traverse into the array but instead treats the array as a non-numerical value.

## Examples¶

### Use in `$group`

Stage¶

Consider a `sales`

collection with the following documents:

{ "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") } { "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") } { "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") } { "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") } { "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:05:00Z") }

Grouping the documents by the `item`

field, the following operation
uses the `$max`

accumulator to compute the maximum total amount and
maximum quantity for each group of documents.

db.sales.aggregate( [ { $group: { _id: "$item", maxTotalAmount: { $max: { $multiply: [ "$price", "$quantity" ] } }, maxQuantity: { $max: "$quantity" } } } ] )

The operation returns the following results:

{ "_id" : "xyz", "maxTotalAmount" : 50, "maxQuantity" : 10 } { "_id" : "jkl", "maxTotalAmount" : 20, "maxQuantity" : 1 } { "_id" : "abc", "maxTotalAmount" : 100, "maxQuantity" : 10 }

### Use in `$project`

Stage¶

A collection `students`

contains the following documents:

{ "_id": 1, "quizzes": [ 10, 6, 7 ], "labs": [ 5, 8 ], "final": 80, "midterm": 75 } { "_id": 2, "quizzes": [ 9, 10 ], "labs": [ 8, 8 ], "final": 95, "midterm": 80 } { "_id": 3, "quizzes": [ 4, 5, 5 ], "labs": [ 6, 5 ], "final": 78, "midterm": 70 }

The following example uses the `$max`

in the
`$project`

stage to calculate the maximum quiz scores, the
maximum lab scores, and the maximum of the final and the midterm:

db.students.aggregate([ { $project: { quizMax: { $max: "$quizzes"}, labMax: { $max: "$labs" }, examMax: { $max: [ "$final", "$midterm" ] } } } ])

The operation results in the following documents:

{ "_id" : 1, "quizMax" : 10, "labMax" : 8, "examMax" : 80 } { "_id" : 2, "quizMax" : 10, "labMax" : 8, "examMax" : 95 } { "_id" : 3, "quizMax" : 5, "labMax" : 6, "examMax" : 78 }

In the other supported stages:

- With a single expression as its operand, if the expression resolves
to an array,
`$max`

traverses into the array to operate on the numerical elements of the array to return a single value. - With a list of expressions as its operand, if any of the expressions
resolves to an array,
`$max`

does**not**traverse into the array but instead treats the array as a non-numerical value.