# $min (aggregation)¶

## Definition¶

`$min`

¶Returns the minimum value.

`$min`

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

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,

`$min`

is available in the`$group`

stage only.When used in the

`$group`

stage,`$min`

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

`$min`

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

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

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

For more information on expressions, see Expressions.

## Behavior¶

### Null or Missing Values¶

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

operation have either a `null`

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

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

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

operation have `null`

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

operator returns `null`

for the minimum value.

### Array Operand¶

In the `$group`

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

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,
`$min`

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,
`$min`

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 `$min`

accumulator to compute the minimum amount and
minimum quantity for each grouping.

db.sales.aggregate( [ { $group: { _id: "$item", minQuantity: { $min: "$quantity" } } } ] )

The operation returns the following results:

{ "_id" : "xyz", "minQuantity" : 5 } { "_id" : "jkl", "minQuantity" : 1 } { "_id" : "abc", "minQuantity" : 2 }

### 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 `$min`

in the
`$project`

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

db.students.aggregate([ { $project: { quizMin: { $min: "$quizzes"}, labMin: { $min: "$labs" }, examMin: { $min: [ "$final", "$midterm" ] } } } ])

The operation results in the following documents:

{ "_id" : 1, "quizMin" : 6, "labMin" : 5, "examMin" : 75 } { "_id" : 2, "quizMin" : 9, "labMin" : 8, "examMin" : 80 } { "_id" : 3, "quizMin" : 4, "labMin" : 5, "examMin" : 70 }

In the other supported stages:

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

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,
`$min`

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