/ /

$fill (estágio de agregação )

Definição

$fill

Novidades na versão 5.3.

Preenche null e os valores de campo ausentes nos documentos.

You can use $fill to populate missing data points:

Em uma sequência baseada em valores circundantes.
Com um valor fixo.

Sintaxe

The $fill stage has this syntax:

{
   $fill: {
      partitionBy: <expression>,
      partitionByFields: [ <field 1>, <field 2>, ... , <field n> ],
      sortBy: {
         <sort field 1>: <sort order>,
         <sort field 2>: <sort order>,
         ...,
         <sort field n>: <sort order>
      },
      output: {
         <field 1>: { value: <expression> },
         <field 2>: { method: <string> },
         ...
      }
   }
}

The $fill stage takes a document with these fields:

Campo	necessidade	Descrição
partitionBy	Opcional	Specifies an expression to group the documents. In the `$fill` stage, a group of documents is known as a partition. If you omit partitionBy and partitionByFields, `$fill` uses one partition for the entire collection. partitionBy and partitionByFields are mutually exclusive. Veja um exemplo.
Partição por campos	Opcional	Specifies an array of fields as the compound key to group the documents. In the `$fill` stage, each group of documents is known as a partition. If you omit partitionBy and partitionByFields, `$fill` uses one partition for the entire collection. partitionBy and partitionByFields are mutually exclusive. See `partitionByFields` Restrictions.
sortBy	Required if method is specified in at least one output.<field>. Caso contrário, opcional.	Especifica o campo ou campos para classificar os documentos dentro de cada partição. Utiliza a mesma sintaxe que o estágio `$sort`.
saída	Obrigatório	Especifica um objeto contendo cada campo para o qual preencher os valores ausentes. Você pode especificar vários campos no objeto saída. O nome do objeto é o nome do campo a ser preenchido. O valor do objeto especifica como o campo é preenchido.
de saída.<field>	Obrigatório	Especifica um objeto indicando como preencher valores ausentes no campo de destino. O nome do objeto deve ser `value` ou `method`. Se o nome for: `value`, o valor deve ser uma expressão indicando o valor utilizado para preencher o campo de destino. `method`, o valor deve ser `linear` ou `locf`. Se você especificar: `linear` método de preenchimento, os valores são preenchidos usando interpolação linear com base nos valores não-`null` circundantes na sequência. `locf` método de preenchimento, os valores são preenchidos com base no último valor não nulo do campo na partição. `locf` representa a última observação transportada. Para saber mais, consulte: detalhes do comportamento linear exemplo de preenchimento linear Detalhes de comportamento do locf exemplo de preenchimento do local

Comportamento e restrições

`partitionByFields` Restrições

$fill returns an error if any field name in the partitionByFields array:

Avalia para um valor não string.
Começa com $.

`linear` Comportamento

O método de preenchimento linear preenche campos null e ausentes usando interpolação linear com base nos valores não-null circundantes na sequência.

For each document where the field is null or missing, linearFill fills those fields in proportion to the missing value range between surrounding non-null values according to the sortBy order. To determine the values for missing fields, linearFill uses:
- A diferença entre os valores circundantes que não sãonull.
- O número de null campos para preencher entre os valores circundantes.
O método linear pode preencher vários valores de null consecutivos se esses valores forem precedidos e seguidos por valores nãonull de acordo com a ordem sortBy .
Exemplo
Se uma coleção contiver estes documentos:
{ index: 0, value: 0 }, { index: 1, value: null }, { index: 2, value: null }, { index: 3, value: null }, { index: 4, value: 10 }
Após utilizar o método de preenchimento linear para preencher os valores null, os documentos tornam-se:
{ index: 0, value: 0 }, { index: 1, value: 2.5 }, { index: 2, value: 5 }, { index: 3, value: 7.5 }, { index: 4, value: 10 }
null valores que não são precedidos e seguidos por valores diferentes denull permanecem null.
To use the linear fill method, you must also use the sortBy field to sort your data.

Para um exemplo completo utilizando o método de preenchimento linear, consulte Preencher valores de campo ausentes com interpolação linear.

`sortBy` Restrições

Ao usar o método de preenchimento linear:

You can specify exactly one field in sortBy. $fill returns an error if you specify multiple fields.
$fill returns an error if there are any repeated values in the sortBy field in a single partition.
$fill returns the following error message if different partitions contain identical sortBy values, even when the values do not repeat within a partition:
There can be no repeated values in the sort field.

`locf` Comportamento

locf significa a última observação realizada.

If a field being filled contains both null and non-null values, locf sets the null and missing values to the field's last known non-null value according to the sortBy order.
- If the field contains only null or missing values in a partition, locf sets the field value to null for that partition.
- null e os valores de campo ausentes que aparecem antes dos valores não nulos na ordem de classificação permanecem null.
To use the locf fill method, you must also use the sortBy field to sort your data.

Para um exemplo completo utilizando o método de preenchimento locf, consulte Preencher Valores de Campo Faltando Baseado no Último Valor Observado.

Comparação de `$fill` e Operadores de Agregação

Para preencher null e os valores de campo ausentes em um documento, você pode usar:

The $fill stage.

When you use the $fill stage, the field you specify in the output is the same field used as the source data.
Os operadores de agregação $linearFill e $locf.

Quando você $linearFill ou $locf, você pode configurar valores para um campo diferente do campo utilizado como os dados de origem.

Exemplos

The examples in this section show how to use $fill to fill missing values:

Com um valor constante
Com interpolação linear
Com base no último valor observado
Para partições distintas

Preencher valores de campo ausentes com um valor constante

Uma loja de calçados mantém uma coleção dailySales que contém um documento resumindo as vendas de cada dia. A loja de sapatos vende estes tipos de sapatos:

boots
sandals
sneakers

Crie a seguinte coleção do dailySales:

db.dailySales.insertMany( [
   {
      "date": ISODate("2022-02-02"),
      "bootsSold": 10,
      "sandalsSold": 20,
      "sneakersSold": 12
   },
   {
      "date": ISODate("2022-02-03"),
      "bootsSold": 7,
      "sneakersSold": 18
   },
   {
      "date": ISODate("2022-02-04"),
      "sneakersSold": 5
   }
] )

Nem todos os documentos na coleção dailySales contêm cada tipo de sapato. Se um tipo de sapato estiver faltando, significa que não havia sapatos desse tipo vendidos na data correspondente.

The following example uses $fill to set the quantities sold to 0 for the missing shoe types for each day's sales:

db.dailySales.aggregate( [
   {
      $fill:
         {
            output:
               {
                  "bootsSold": { value: 0 },
                  "sandalsSold": { value: 0 },
                  "sneakersSold": { value: 0 }
               }
         }
   }
] )

No pipeline anterior:

$fill preenche valores para campos em falta.
saída especifica:
Os nomes dos campos para preencher.
O valor para definir os campos preenchidos. Neste exemplo, o
saída especifica um valor constante de 0.

Saída de exemplo:

[
   {
   _id: ObjectId("6202df9f394d47411658b51e"),
   date: ISODate("2022-02-02T00:00:00.000Z"),
   bootsSold: 10,
   sandalsSold: 20,
   sneakersSold: 12
   },
   {
   _id: ObjectId("6202df9f394d47411658b51f"),
   date: ISODate("2022-02-03T00:00:00.000Z"),
   bootsSold: 7,
   sneakersSold: 18,
   sandalsSold: 0
   },
   {
   _id: ObjectId("6202df9f394d47411658b520"),
   date: ISODate("2022-02-04T00:00:00.000Z"),
   sneakersSold: 5,
   bootsSold: 0,
   sandalsSold: 0
   }
]

Preencher valores de campo ausentes com interpolação linear

Crie uma coleção stock que contenha os seguintes documentos, que acompanham o preço das ações de uma única empresa em intervalos de hora em hora:

db.stock.insertMany( [
   {
      time: ISODate("2021-03-08T09:00:00.000Z"),
      price: 500
   },
   {
      time: ISODate("2021-03-08T10:00:00.000Z"),
   },
   {
      time: ISODate("2021-03-08T11:00:00.000Z"),
      price: 515
   },
   {
      time: ISODate("2021-03-08T12:00:00.000Z")
   },
   {
      time: ISODate("2021-03-08T13:00:00.000Z")
   },
   {
      time: ISODate("2021-03-08T14:00:00.000Z"),
      price: 485
   }
] )

O campo price está faltando em alguns documentos da coleção.

Para preencher os valores de price ausentes utilizando interpolação linear, utilize $fill com o método de preenchimento linear:

db.stock.aggregate( [
   {
      $fill:
         {
            sortBy: { time: 1 },
            output:
               {
                  "price": { method: "linear" }
               }
         }
   }
] )

No pipeline anterior:

$fill preenche valores para campos em falta.
sortBy: { time: 1 } classifica os documentos pelo campo time em ordem crescente, do mais antigo ao mais recente.
saída especifica:
price como o campo para o qual preencher os valores ausentes.
{ method: "linear" } como método de preenchimento. O preenchimento linear
O método preenche os valores price ausentes usando interpolação linear com base nos valores price adjacentes na sequência.

Saída de exemplo:

[
   {
      _id: ObjectId("620ad41c394d47411658b5e9"),
      time: ISODate("2021-03-08T09:00:00.000Z"),
      price: 500
   },
   {
      _id: ObjectId("620ad41c394d47411658b5ea"),
      time: ISODate("2021-03-08T10:00:00.000Z"),
      price: 507.5
   },
   {
      _id: ObjectId("620ad41c394d47411658b5eb"),
      time: ISODate("2021-03-08T11:00:00.000Z"),
      price: 515
   },
   {
      _id: ObjectId("620ad41c394d47411658b5ec"),
      time: ISODate("2021-03-08T12:00:00.000Z"),
      price: 505
   },
   {
      _id: ObjectId("620ad41c394d47411658b5ed"),
      time: ISODate("2021-03-08T13:00:00.000Z"),
      price: 495
   },
   {
      _id: ObjectId("620ad41c394d47411658b5ee"),
      time: ISODate("2021-03-08T14:00:00.000Z"),
      price: 485
   }
]

Preencher valores de campo ausentes com base no último valor observado

Crie uma coleção restaurantReviews que contenha os seguintes documentos, que armazenam as pontuações das avaliações de um único restaurante ao longo do tempo:

db.restaurantReviews.insertMany( [
   {
      date: ISODate("2021-03-08"),
      score: 90
   },
   {
      date: ISODate("2021-03-09"),
      score: 92
   },
   {
      date: ISODate("2021-03-10")
   },
   {
      date: ISODate("2021-03-11")
   },
   {
      date: ISODate("2021-03-12"),
      score: 85
   },
   {
      date: ISODate("2021-03-13")
   }
] )

O campo score está faltando em alguns documentos da coleção.

To populate the missing score fields and ensure that there are no gaps in the data, use $fill. In the following example, $fill uses the locf fill method to fill the missing score values with the previous score in the sequence:

db.restaurantReviews.aggregate( [
   {
      $fill:
         {
            sortBy: { date: 1 },
            output:
               {
                  "score": { method: "locf" }
               }
         }
   }
] )

No pipeline anterior:

$fill fills in missing score values.
sortBy: { date: 1 } classifica os documentos pelo campo date em ordem crescente, do mais antigo ao mais recente.
saída especifica:
score como o campo para o qual preencher os valores ausentes.
{ method: "locf" } como método de preenchimento. O preenchimento locf
O método preenche os valores score ausentes com o último score observado na sequência.

Saída de exemplo:

[
   {
   _id: ObjectId("62040bc9394d47411658b553"),
   date: ISODate("2021-03-08T00:00:00.000Z"),
   score: 90
   },
   {
   _id: ObjectId("62040bc9394d47411658b554"),
   date: ISODate("2021-03-09T00:00:00.000Z"),
   score: 92
   },
   {
   _id: ObjectId("62040bc9394d47411658b555"),
   date: ISODate("2021-03-10T00:00:00.000Z"),
   score: 92
   },
   {
   _id: ObjectId("62040bc9394d47411658b556"),
   date: ISODate("2021-03-11T00:00:00.000Z"),
   score: 92
   },
   {
   _id: ObjectId("62040bc9394d47411658b557"),
   date: ISODate("2021-03-12T00:00:00.000Z"),
   score: 85
   },
   {
   _id: ObjectId("62040bc9394d47411658b558"),
   date: ISODate("2021-03-13T00:00:00.000Z"),
   score: 85
   }
]

Preencha dados para partições distintas

Consider the previous example with restaurant reviews but instead of tracking a single restaurant, the collection now contains reviews for multiple restaurants.

Crie uma coleção denominada restaurantReviewsMultiple e preencha a coleção com estes documentos:

db.restaurantReviewsMultiple.insertMany( [
   {
      date: ISODate("2021-03-08"),
      restaurant: "Joe's Pizza",
      score: 90
   },
   {
      date: ISODate("2021-03-08"),
      restaurant: "Sally's Deli",
      score: 75
   },
   {
      date: ISODate("2021-03-09"),
      restaurant: "Joe's Pizza",
      score: 92
   },
   {
      date: ISODate("2021-03-09"),
      restaurant: "Sally's Deli"
   },
   {
      date: ISODate("2021-03-10"),
      restaurant: "Joe's Pizza"
   },
   {
      date: ISODate("2021-03-10"),
      restaurant: "Sally's Deli",
      score: 68
   },
   {
      date: ISODate("2021-03-11"),
      restaurant: "Joe's Pizza",
      score: 93
   },
   {
      date: ISODate("2021-03-11"),
      restaurant: "Sally's Deli"
   }
] )

O campo score está faltando em alguns documentos da coleção.

db.restaurantReviewsMultiple.aggregate( [
   {
      $fill:
         {
            sortBy: { date: 1 },
            partitionBy: { "restaurant": "$restaurant" },
            output:
               {
                  "score": { method: "locf" }
               }
         }
   }
] )

No pipeline anterior:

$fill fills in missing score values.
sortBy: { date: 1 } classifica os documentos pelo campo date em ordem crescente, do mais antigo ao mais recente.
partitionBy: { "restaurant": "$restaurant" } partições dos dados de restaurant. Existem dois restaurantes: Joe's Pizza e Sally's Deli.
saída especifica:
score como o campo para o qual preencher os valores ausentes.
{ method: "locf" } como método de preenchimento. O preenchimento locf
O método preenche os valores score ausentes com o último score observado na sequência.

Saída de exemplo:

[
{
   _id: ObjectId("620559f4394d47411658b58f"),
   date: ISODate("2021-03-08T00:00:00.000Z"),
   restaurant: "Joe's Pizza",
   score: 90
},
{
   _id: ObjectId("620559f4394d47411658b591"),
   date: ISODate("2021-03-09T00:00:00.000Z"),
   restaurant: "Joe's Pizza",
   score: 92
},
{
   _id: ObjectId("620559f4394d47411658b593"),
   date: ISODate("2021-03-10T00:00:00.000Z"),
   restaurant: "Joe's Pizza",
   score: 92
},
{
   _id: ObjectId("620559f4394d47411658b595"),
   date: ISODate("2021-03-11T00:00:00.000Z"),
   restaurant: "Joe's Pizza",
   score: 93
},
{
   _id: ObjectId("620559f4394d47411658b590"),
   date: ISODate("2021-03-08T00:00:00.000Z"),
   restaurant: "Sally's Deli",
   score: 75
},
{
   _id: ObjectId("620559f4394d47411658b592"),
   date: ISODate("2021-03-09T00:00:00.000Z"),
   restaurant: "Sally's Deli",
   score: 75
},
{
   _id: ObjectId("620559f4394d47411658b594"),
   date: ISODate("2021-03-10T00:00:00.000Z"),
   restaurant: "Sally's Deli",
   score: 68
},
{
   _id: ObjectId("620559f4394d47411658b596"),
   date: ISODate("2021-03-11T00:00:00.000Z"),
   restaurant: "Sally's Deli",
   score: 68
}
]

Indique se um campo foi preenchido usando `$fill`

Quando você preenche valores ausentes, a saída não indica se um valor foi preenchido com o operador $fill ou se o valor existia no documento originalmente. Para distinguir entre valores preenchidos e preexistentes, você pode usar um estágio $set antes de $fill e definir um novo campo com base na existência ou não do valor.

Por exemplo, crie uma coleção restaurantReviews que contenha os seguintes documentos, que armazenam as pontuações das avaliações de um restaurante ao longo do tempo:

db.restaurantReviews.insertMany( [
   {
      date: ISODate("2021-03-08"),
      score: 90
   },
   {
      date: ISODate("2021-03-09"),
      score: 92
   },
   {
      date: ISODate("2021-03-10")
   },
   {
      date: ISODate("2021-03-11")
   },
   {
      date: ISODate("2021-03-12"),
      score: 85
   },
   {
      date: ISODate("2021-03-13")
   }
] )

O campo score está faltando em alguns documentos da coleção. Você pode preencher os valores score ausentes usando o operador $fill.

Crie um pipeline para executar as seguintes ações:

Use $set para adicionar um novo campo a cada documento, indicando se o campo score do documento existe antes do operador $fill preencher os valores. Este novo campo é chamado valueExisted.
Preencha os valores score ausentes com o último score observado na sequência. O método de preenchimento locf significa "última observação realizada adiante".

O pipeline se assemelha ao seguinte código:

db.restaurantReviews.aggregate( [
   {
      $set: {
         "valueExisted": {
            "$ifNull": [
               { "$toBool": { "$toString": "$score" } },
               false
            ]
         }
      }
   },
   {
      $fill: {
         sortBy: { date: 1 },
         output:
            {
               "score": { method: "locf" }
            }
      }
   }
] )

Observação

Manipulação de valores de zero

Na expressão $ifNull, os valores score são convertidos em strings e, em seguida, em booleanos. A expressão $toBool sempre converte strings em true. Se os valores de score não forem convertidos em strings, os valores de score de 0 terão valueExisted definido para false.

Saída:

[
   {
      _id: ObjectId("63595116b1fac2ee2e957f15"),
      date: ISODate("2021-03-08T00:00:00.000Z"),
      score: 90,
      valueExisted: true
   },
   {
      _id: ObjectId("63595116b1fac2ee2e957f16"),
      date: ISODate("2021-03-09T00:00:00.000Z"),
      score: 92,
      valueExisted: true
   },
   {
      _id: ObjectId("63595116b1fac2ee2e957f17"),
      date: ISODate("2021-03-10T00:00:00.000Z"),
      valueExisted: false,
      score: 92
   },
   {
      _id: ObjectId("63595116b1fac2ee2e957f18"),
      date: ISODate("2021-03-11T00:00:00.000Z"),
      valueExisted: false,
      score: 92
   },
   {
      _id: ObjectId("63595116b1fac2ee2e957f19"),
      date: ISODate("2021-03-12T00:00:00.000Z"),
      score: 85,
      valueExisted: true
   },
   {
      _id: ObjectId("63595116b1fac2ee2e957f1a"),
      date: ISODate("2021-03-13T00:00:00.000Z"),
      valueExisted: false,
      score: 85
   }
]

Os exemplos de Node.js nesta página usam a coleção sample_weatherdata.data dos conjuntos de dados de amostra do Atlas. Para aprender como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de amostra, consulte Introdução na documentação do driver MongoDB Node.js.

Para usar o driver Node.js do MongoDB para adicionar um estágio $fill a um pipeline de agregação , use o operador $fill em um objeto de pipeline.

O exemplo a seguir cria um pipeline que preenche valores nulos ou ausentes. O pipeline inclui os seguintes estágios:

O estágio $group agrupa documentos de entrada por seu campo ts e calcula a média de cada grupo seaSurfaceTemperature.value.
The $fill stage sorts the grouped data by the _id field in ascending order and fills null or missing seaSurfaceTemperature values by using linear interpolation.

const pipeline = [
  {
    $group: {
      _id: "$ts",
      seaSurfaceTemperature: { $avg: "$seaSurfaceTemperature.value" },
    }
  },
  {
    $fill: {
      sortBy: { _id: 1 },  
      output: { seaSurfaceTemperature: { method: "linear" } }
    }
  }
]; 
const cursor = collection.aggregate(pipeline);
return cursor;

Voltar

$facet

$geoNear

$fill (estágio de agregação )

Definição

Sintaxe

Comportamento e restrições

partitionByFields Restrições

linear Comportamento

sortBy Restrições

locf Comportamento

Comparação de $fill e Operadores de Agregação

Exemplos

Preencher valores de campo ausentes com um valor constante

Preencher valores de campo ausentes com interpolação linear

Preencher valores de campo ausentes com base no último valor observado

Preencha dados para partições distintas

Indique se um campo foi preenchido usando $fill

`partitionByFields` Restrições

`linear` Comportamento

`sortBy` Restrições

`locf` Comportamento

Comparação de `$fill` e Operadores de Agregação

Indique se um campo foi preenchido usando `$fill`