# $min
The `$min` aggregation operator returns the minimum value of a specified field across a set of documents. This operator is useful for finding the lowest value in a set of documents.
**Parameters**
+ `expression`: The expression to evaluate. This can be a field path, a variable, or any expression that resolves to a value.
## Example (MongoDB Shell)
The following example demonstrates the usage of the `$min` operator to find the minimum value of the `age` field across multiple documents.
**Create sample documents**
```
db.users.insertMany([
{ name: "John", age: 35 },
{ name: "Jane", age: 28 },
{ name: "Bob", age: 42 },
{ name: "Alice", age: 31 }
]);
```
**Query example**
```
db.users.aggregate([
{ $group: { _id: null, minAge: { $min: "$age" } } },
{ $project: { _id: 0, minAge: 1 } }
])
```
**Output**
```
[ { minAge: 28 } ]
```
## Window operator usage example (MongoDB Shell)
New from version 8.0.2.
The `$min` operator can also be used as a window operator in the `$setWindowFields` stage. In this context, it returns the minimum value for the documents in each window. You specify the operator under the `output` field, and optionally define the window boundaries with a `window` document.
**Note**
When used as a window operator in `$setWindowFields`, `$min` is limited to 100 MB of intermediate data. An operation that exceeds this limit returns an error.
**Create sample documents**
```
db.stockPrices.insertMany([
{ _id: 1, ticker: "ABC", hour: 1, price: 50 },
{ _id: 2, ticker: "ABC", hour: 2, price: 45 },
{ _id: 3, ticker: "ABC", hour: 3, price: 60 },
{ _id: 4, ticker: "ABC", hour: 4, price: 40 },
{ _id: 5, ticker: "XYZ", hour: 1, price: 30 },
{ _id: 6, ticker: "XYZ", hour: 2, price: 35 },
{ _id: 7, ticker: "XYZ", hour: 3, price: 25 }
]);
```
**Query example**
The following example partitions the documents by `ticker`, sorts each partition by `hour`, and returns the lowest price seen from the start of the partition through the current document.
```
db.stockPrices.aggregate([
{
$setWindowFields: {
partitionBy: "$ticker",
sortBy: { hour: 1 },
output: {
lowestSoFar: {
$min: "$price",
window: { documents: ["unbounded", "current"] }
}
}
}
}
]);
```
**Output**
```
[
{ "_id": 1, "ticker": "ABC", "hour": 1, "price": 50, "lowestSoFar": 50 },
{ "_id": 2, "ticker": "ABC", "hour": 2, "price": 45, "lowestSoFar": 45 },
{ "_id": 3, "ticker": "ABC", "hour": 3, "price": 60, "lowestSoFar": 45 },
{ "_id": 4, "ticker": "ABC", "hour": 4, "price": 40, "lowestSoFar": 40 },
{ "_id": 5, "ticker": "XYZ", "hour": 1, "price": 30, "lowestSoFar": 30 },
{ "_id": 6, "ticker": "XYZ", "hour": 2, "price": 35, "lowestSoFar": 30 },
{ "_id": 7, "ticker": "XYZ", "hour": 3, "price": 25, "lowestSoFar": 25 }
]
```
Each document is augmented with `lowestSoFar`, the running minimum of `price` within its partition up to and including the current document.
## Code examples
To view a code example for using the `$min` operator, choose the tab for the language that you want to use. The following examples show both accumulator usage (in `$group`) and window operator usage (in `$setWindowFields`):
------
#### [ Node.js ]
```
const { MongoClient } = require('mongodb');
async function example() {
const client = await MongoClient.connect('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
const db = client.db('test');
// Accumulator usage: minimum value across a group
const users = db.collection('users');
await users.insertMany([
{ name: "John", age: 35 },
{ name: "Jane", age: 28 },
{ name: "Bob", age: 42 },
{ name: "Alice", age: 31 }
]);
const accumulatorResult = await users.aggregate([
{ $group: { _id: null, minAge: { $min: "$age" } } }
]).toArray();
console.log('Accumulator result:', accumulatorResult);
// Window operator usage: running minimum within each partition
const stockPrices = db.collection('stockPrices');
await stockPrices.insertMany([
{ _id: 1, ticker: "ABC", hour: 1, price: 50 },
{ _id: 2, ticker: "ABC", hour: 2, price: 45 },
{ _id: 3, ticker: "ABC", hour: 3, price: 60 },
{ _id: 4, ticker: "ABC", hour: 4, price: 40 },
{ _id: 5, ticker: "XYZ", hour: 1, price: 30 },
{ _id: 6, ticker: "XYZ", hour: 2, price: 35 },
{ _id: 7, ticker: "XYZ", hour: 3, price: 25 }
]);
const windowResult = await stockPrices.aggregate([
{
$setWindowFields: {
partitionBy: "$ticker",
sortBy: { hour: 1 },
output: {
lowestSoFar: {
$min: "$price",
window: { documents: ["unbounded", "current"] }
}
}
}
}
]).toArray();
console.log('Window result:', windowResult);
client.close();
}
example();
```
------
#### [ Python ]
```
from pymongo import MongoClient
def example():
client = MongoClient('mongodb://:@:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
db = client['test']
# Accumulator usage: minimum value across a group
users = db.users
users.insert_many([
{ "name": "John", "age": 35 },
{ "name": "Jane", "age": 28 },
{ "name": "Bob", "age": 42 },
{ "name": "Alice", "age": 31 }
])
accumulator_result = list(users.aggregate([
{ "$group": { "_id": None, "minAge": { "$min": "$age" } } }
]))
print('Accumulator result:', accumulator_result)
# Window operator usage: running minimum within each partition
stock_prices = db.stockPrices
stock_prices.insert_many([
{ "_id": 1, "ticker": "ABC", "hour": 1, "price": 50 },
{ "_id": 2, "ticker": "ABC", "hour": 2, "price": 45 },
{ "_id": 3, "ticker": "ABC", "hour": 3, "price": 60 },
{ "_id": 4, "ticker": "ABC", "hour": 4, "price": 40 },
{ "_id": 5, "ticker": "XYZ", "hour": 1, "price": 30 },
{ "_id": 6, "ticker": "XYZ", "hour": 2, "price": 35 },
{ "_id": 7, "ticker": "XYZ", "hour": 3, "price": 25 }
])
window_result = list(stock_prices.aggregate([
{
"$setWindowFields": {
"partitionBy": "$ticker",
"sortBy": { "hour": 1 },
"output": {
"lowestSoFar": {
"$min": "$price",
"window": { "documents": ["unbounded", "current"] }
}
}
}
}
]))
print('Window result:', window_result)
client.close()
example()
```
------