As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# $set WindowFields
<a name="setWindowFields"></a>

Novo na versão 8.0.2.

O `$setWindowFields` estágio no Amazon DocumentDB executa operações em uma extensão específica de documentos (uma * janela*) em uma partição e retorna os resultados com base no operador de janela escolhido. O estágio agrupa os documentos de entrada em partições, opcionalmente os classifica e, para cada documento, calcula um ou mais campos de saída em uma janela de documentos ao redor.

**Sintaxe**

```
{
  $setWindowFields: {
    partitionBy: <expression>,
    sortBy: { <sortField1>: <sortOrder>, ... },
    output: {
      <outputField1>: {
        <windowOperator>: <expression>,
        window: {
          documents: [ <lowerBound>, <upperBound> ],
          range: [ <lowerBound>, <upperBound> ],
          unit: <time unit>
        }
      },
      ...
    }
  }
}
```

**Parâmetros**
+ `partitionBy`: opcional. Uma única expressão usada para agrupar os documentos em partições. Isso pode ser um caminho de campo (por exemplo`"$state"`) ou outra expressão. Se omitidos, todos os documentos de entrada pertencerão a uma única partição.
+ `sortBy`: opcional. Um documento que especifica o campo ou os campos pelos quais classificar os documentos em cada partição, no formato `{ <field>: 1 }` de ordem crescente ou `{ <field>: -1 }` decrescente. A `sortBy` é necessário quando você usa limites de janela baseados em documentos ou em intervalos e quando você usa um dos operadores de classificação.
+ `output`: Obrigatório. Um documento que especifica os campos a serem anexados a cada documento. Você pode especificar vários campos de saída, mas cada campo de saída usa exatamente um operador de janela, seu argumento e um `window` documento opcional que define os limites da janela:`{ <field>: { <windowOperator>: <expression>, window: { ... } } }`.

## Limites da janela
<a name="setWindowFields-bounds"></a>

Em cada `output` campo, você pode definir opcionalmente os limites da janela com um `window` documento. Uma janela pode ser definida pela posição do documento ou por um intervalo de valores.
+ `documents`: especifica a janela como um número de documentos antes e depois do documento atual, no formulário`[ <lowerBound>, <upperBound> ]`. Cada limite é um deslocamento inteiro (por exemplo, `-1` ou`2`) ou uma das palavras-chave e. `"unbounded"` `"current"` `"unbounded"`estende a janela até o início da partição quando usada como limite inferior ou até o final da partição quando usada como limite superior. `"current"`significa o documento atual. Uma `documents` janela requer um, `sortBy` a menos que ambos os limites sejam`"unbounded"`.
+ `range`: especifica a janela como um intervalo de valores de `sortBy` campo em relação ao documento atual, no formulário`[ <lowerBound>, <upperBound> ]`. Cada limite é um número adicionado ao `sortBy` valor do documento atual ou à `"unbounded"` palavra-chave. Uma `range` janela exige exatamente um `sortBy` campo ascendente e não aceita a `"current"` palavra-chave.
+ `unit`: opcional. Usado com `range` para interpretar os limites numéricos da janela como um intervalo de tempo em que o `sortBy` campo contém valores de data. O Amazon DocumentDB oferece suporte às seguintes unidades: `"year"` `"quarter"` `"month"``"week"`,`"day"`,`"hour"`,`"minute"`,`"second"`, e. `"millisecond"` Quando `unit` especificado, os `range` limites devem ser inteiros.

Quando o `window` documento é omitido, a janela padrão é`documents: ["unbounded", "unbounded"]`, que abrange toda a partição.

**nota**  
Quando você usa uma `range` janela sobre valores de data, recomendamos uma duração fixa, `unit` como `"day"` (ou menor), em vez de, ou `"month"` `"quarter"``"year"`, cujos comprimentos dependentes do calendário possam produzir limites de janela ambíguos.

## Operadores de janela compatíveis
<a name="setWindowFields-operators"></a>

O Amazon DocumentDB oferece suporte aos seguintes 26 operadores de janela no `output` campo do `$setWindowFields` palco:
+ `$sum`
+ `$avg`
+ `$count`
+ `$push`
+ `$addToSet`
+ `$stdDevPop`
+ `$stdDevSamp`
+ `$covariancePop`
+ `$covarianceSamp`
+ `$first`
+ `$last`
+ `$firstN`
+ `$lastN`
+ `$top`
+ `$bottom`
+ `$topN`
+ `$bottomN`
+ `$min`
+ `$minN`
+ `$max`
+ `$maxN`
+ `$median`
+ `$percentile`
+ `$rank`
+ `$denseRank`
+ `$documentNumber`

**nota**  
O `$rand` operador não é suportado em um operador de janela no `$setWindowFields` palco.

**Janelas vazias **

Quando uma janela não contém documentos (por exemplo, uma `range` janela sem valores no intervalo), o resultado depende do operador: `$count` e `$sum` retorna`0`;`$push`,,,, `$addToSet` `$firstN` `$lastN` `$minN` `$maxN``$topN`, e retorna uma matriz vazia; `$bottomN` `$percentile` retorna uma matriz de `null` valores (um por percentil solicitado); todos os outros operadores retornam. `null`

## Exemplo (MongoDB Shell)
<a name="setWindowFields-examples"></a>

O exemplo a seguir particiona os documentos por`region`, classifica cada partição por `day` e calcula um total em execução `revenue` desde o início da partição até o documento atual.

**Crie documentos de amostra **

```
db.sales.insertMany([
  { _id: 1, region: "east", day: 1, revenue: 100 },
  { _id: 2, region: "east", day: 2, revenue: 150 },
  { _id: 3, region: "east", day: 3, revenue: 120 },
  { _id: 4, region: "west", day: 1, revenue: 200 },
  { _id: 5, region: "west", day: 2, revenue: 180 }
]);
```

**Exemplo de consulta **

```
db.sales.aggregate([
  {
    $setWindowFields: {
      partitionBy: "$region",
      sortBy: { day: 1 },
      output: {
        runningRevenue: {
          $sum: "$revenue",
          window: { documents: ["unbounded", "current"] }
        }
      }
    }
  }
]);
```

**Saída**

```
[
  { "_id": 1, "region": "east", "day": 1, "revenue": 100, "runningRevenue": 100 },
  { "_id": 2, "region": "east", "day": 2, "revenue": 150, "runningRevenue": 250 },
  { "_id": 3, "region": "east", "day": 3, "revenue": 120, "runningRevenue": 370 },
  { "_id": 4, "region": "west", "day": 1, "revenue": 200, "runningRevenue": 200 },
  { "_id": 5, "region": "west", "day": 2, "revenue": 180, "runningRevenue": 380 }
]
```

Cada documento é aumentado com `runningRevenue` a soma cumulativa de `revenue` dentro de sua partição até e incluindo o documento atual.

## Exemplos de código
<a name="setWindowFields-code"></a>

Para ver um exemplo de código para usar o `$setWindowFields` estágio, escolha a guia do idioma que você deseja usar:

------
#### [ Node.js ]

```
const { MongoClient } = require('mongodb');

async function example() {
  const client = new MongoClient('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');

  try {
    await client.connect();
    const db = client.db('test');
    const sales = db.collection('sales');

    await sales.insertMany([
      { _id: 1, region: "east", day: 1, revenue: 100 },
      { _id: 2, region: "east", day: 2, revenue: 150 },
      { _id: 3, region: "east", day: 3, revenue: 120 },
      { _id: 4, region: "west", day: 1, revenue: 200 },
      { _id: 5, region: "west", day: 2, revenue: 180 }
    ]);

    const result = await sales.aggregate([
      {
        $setWindowFields: {
          partitionBy: "$region",
          sortBy: { day: 1 },
          output: {
            runningRevenue: {
              $sum: "$revenue",
              window: { documents: ["unbounded", "current"] }
            }
          }
        }
      }
    ]).toArray();

    console.log(result);
  } finally {
    await client.close();
  }
}

example();
```

------
#### [ Python ]

```
from pymongo import MongoClient

def example():
    client = MongoClient('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')

    try:
        db = client['test']
        sales = db['sales']

        sales.insert_many([
            { '_id': 1, 'region': 'east', 'day': 1, 'revenue': 100 },
            { '_id': 2, 'region': 'east', 'day': 2, 'revenue': 150 },
            { '_id': 3, 'region': 'east', 'day': 3, 'revenue': 120 },
            { '_id': 4, 'region': 'west', 'day': 1, 'revenue': 200 },
            { '_id': 5, 'region': 'west', 'day': 2, 'revenue': 180 }
        ])

        result = list(sales.aggregate([
            {
                '$setWindowFields': {
                    'partitionBy': '$region',
                    'sortBy': { 'day': 1 },
                    'output': {
                        'runningRevenue': {
                            '$sum': '$revenue',
                            'window': { 'documents': ['unbounded', 'current'] }
                        }
                    }
                }
            }
        ]))

        print(result)
    finally:
        client.close()

example()
```

------