Database Manual / Reference / Query Language / Expressions

$minMaxScaler (Window Function)

Definition

New in version 8.2.

$minMaxScaler

Normalizes a numeric expression within a window of values. By default, values can range between zero and one. The smallest value becomes zero, the largest value becomes one, and all other values scale proportionally in between zero and one. You can also specify a custom minimum and maximum value for the normalized output range.

$minMaxScaler is only available in the $setWindowFields stage.

$minMaxScaler window operator has the following syntax:

{ $minMaxScaler: <numeric expression> }

The value can be:

A numeric expression, which is the value that you want to normalize. It can be a specific numeric field or value calculated from your documents.

A document in the following format:

{
  input: <numeric expression>,
  min: <constant numeric expression>,
  max: <constant numeric expression>
}

Field	Description
`input`	Numeric expression, which contains the value that you want to normalize.
`min`	Minimum value that you want in the output. If omitted, defaults to `0`.
`max`	Maximum value that you want in the output. If omitted, defaults to `1`.

Behavior

$minMaxScaler uses the following formula to normalize the numeric expression:

minMaxScaler(x, min, max) = ((x - min(X)) / (max(X) - min(X))) * (max - min) + min

Where:

`x`	Value to normalize.
`min`	Desired minimum value of outputs.
`max`	Desired maximum value of outputs.
`min(X)`	Minimum value in the range.
`max(X)`	Maximum value in the range.

The $minMaxScaler returns an error if the input value is any of the following:

Non-numeric
Null
Empty arrays
Strings

Examples

Suppose your documents in your collection have a field named a with the following values:

{ "_id": 1, "a": 1 }
{ "_id": 2, "a": 5 }
{ "_id": 3, "a": 13 }
{ "_id": 4, "a": 21 }

Consider the following pipeline stage and the output:

db.example.aggregate([
  {$setWindowFields: {
    sortBy: {a: 1},
    output: {
      scaled: {$minMaxScaler: "$a"},
      scaledTo100: {$minMaxScaler: {input: "$a", min: 0, max: 100}},
    }
  }}
])

{a: 1, scaled: 0, scaledTo100: 0}
{a: 5, scaled: 0.2, scaledTo100: 20}
{a: 13, scaled: 0.6, scaledTo100: 60}
{a: 21, scaled: 1, scaledTo100: 100}

In the preceding example, the pipeline uses the $minMaxScaler to calculate two scaled values:

scaled, which applies the default values, 0 and 1, to scale.
scaledTo100, which applies a range between 0 and 100 to scale.

The output shows the original value of a and the two scaled values. The $minMaxScaler uses the following for the documents, where min(X) is 1 and max(X) is 21 (calculated from the documents), to return the scaled values:

{a: 1}
scaled = ((1 - 1) / (21 - 1)) * (1 - 0) + 0 = 0
scaledTo100 = ((1 - 1) / (21 - 1)) * (100 - 0) + 0 = 0{a: 5}
scaled = ((5 - 1) / (21 - 1)) * (1 - 0) + 0 = (4 / 20) * 1 + 0 = 0.2
scaledTo100 = ((5 - 1) / (21 - 1)) * (100 - 0) + 0 = (4 / 20) * 100 + 0 = 20{a: 13}
scaled = ((13 - 1) / (21 - 1)) * (1 - 0) + 0 = (12 / 20) * 1 + 0 = 0.6
scaledTo100 = ((13 - 1) / (21 - 1)) * (100 - 0) + 0 = (12 / 20) * 100 + 0 = 60{a: 21}
scaled = ((21 - 1) / (21 - 1)) * (1 - 0) + 0 = (20 / 20) * 1 + 0 = 1
scaledTo100 = ((21 - 1) / (21 - 1)) * (100 - 0) + 0 = (20 / 20) * 100 + 0 = 100

Back

$millisecond

$minute