$set WindowFields

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

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 ou2) 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

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 retorna0;$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)

O exemplo a seguir particiona os documentos porregion, 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

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()