$addFields (agregação)

Nesta página

Definição

Compatibilidade
Sintaxe
Comportamento
Exemplos

Definição

$addFields

Adiciona novos campos aos documentos. $addFields gera documentos que contêm todos os campos existentes dos documentos de entrada e novos campos adicionados.

O estágio $addFields é equivalente a um estágio $project que especifica explicitamente todos os campos existentes nos documentos de entrada e adiciona os novos campos.

Observação

Você também pode usar o estágio $set , que é um alias para $addFields.

Compatibilidade

Você pode utilizar o $addFields para implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

O estágio tem a seguinte sintaxe:

{ $addFields: { <newField>: <expression>, ... } }

Especifique o nome de cada campo a ser adicionado e defina seu valor como uma expressão de agregação ou um objeto vazio. Para mais informações sobre expressões, consulte Operadores de Expressão.

Importante

Se o nome do novo campo for o mesmo de um nome de campo existente (incluindo _id), $addFields sobrescreve o valor existente desse campo com o valor da expressão especificada.

Comportamento

$addFields anexa novos campos a documentos existentes. Você pode incluir um ou mais estágios $addFields em uma operação de aggregation.
$addFields aceita a incorporação de objetos onde você pode definir um valor para uma expressão de agregação ou para um objeto vazio. Por exemplo, os seguintes objetos aninhados são aceitos:
```
{$addFields: { a: { b: { } } } }
```
Para adicionar um campo ou campos a documentos incorporados (incluindo documentos em matrizes), use a notação de ponto. Consulte o exemplo.
Para adicionar um elemento a um campo de matriz existente com $addFields, utilize com $concatArrays. Consulte o exemplo.

Exemplos

Usando dois estágios `$addFields`

Uma coleção chamada scores contém os seguintes documentos:

db.scores.insertMany( [
   {
      _id: 1,
      student: "Maya",
      homework: [ 10, 5, 10 ],
      quiz: [ 10, 8 ],
      extraCredit: 0
   },
   {
      _id: 2,
      student: "Ryan",
      homework: [ 5, 6, 5 ],
      quiz: [ 8, 8 ],
      extraCredit: 8
   }
] )

A seguinte operação utiliza duas etapas do $addFields para incluir três novos campos nos documentos de saída:

db.scores.aggregate( [
   {
     $addFields: {
       totalHomework: { $sum: "$homework" } ,
       totalQuiz: { $sum: "$quiz" }
     }
   },
   {
     $addFields: { totalScore:
       { $add: [ "$totalHomework", "$totalQuiz", "$extraCredit" ] } }
   }
] )

A operação retorna os seguintes documentos:

[
   {
      _id: 1,
      student: "Maya",
      homework: [ 10, 5, 10 ],
      quiz: [ 10, 8 ],
      extraCredit: 0,
      totalHomework: 25,
      totalQuiz: 18,
      totalScore: 43
   },
   {
      _id: 2,
      student: "Ryan",
      homework: [ 5, 6, 5 ],
      quiz: [ 8, 8 ],
      extraCredit: 8,
      totalHomework: 16,
      totalQuiz: 16,
      totalScore: 40
   }
]

Adicionando campos a um documento incorporado

Use a notação de pontos para adicionar novos campos a documentos incorporados.

Por exemplo, crie uma collection chamada vehicles com os seguintes documentos:

db.vehicles.insertMany( [
      { _id: 1, type: "car", specs: { doors: 4, wheels: 4 } },
      { _id: 2, type: "motorcycle", specs: { doors: 0, wheels: 2 } },
      { _id: 3, type: "jet ski" }
] )

A seguinte operação de agregação adiciona um novo campo fuel_type ao documento incorporado specs.

db.vehicles.aggregate( [
   { $addFields: { "specs.fuel_type": "unleaded" } }
] )

A operação retorna os seguintes resultados:

[
   { _id: 1, type: "car",
      specs: { doors: 4, wheels: 4, fuel_type: "unleaded" } },
   { _id: 2, type: "motorcycle",
      specs: { doors: 0, wheels: 2, fuel_type: "unleaded" } },
   { _id: 3, type: "jet ski",
      specs: { fuel_type: "unleaded" } }
]

Substituindo um campo existente

A especificação de um nome de campo existente em uma operação $addFields faz com que o campo original seja substituído.

Uma coleção chamada animals contém o seguinte documento:

db.animals.insertOne(
   { _id: 1, dogs: 10, cats: 15 }
)

A seguinte operação $addFields especifica o campo cats.

db.animals.aggregate( [
  {
    $addFields: { cats: 20 }
  }
] )

A operação retorna o seguinte documento:

[ { _id: 1, dogs: 10, cats: 20 } ]

É possível substituir um campo por outro. No exemplo a seguir, o campo item substitui o campo _id.

Uma coleção chamada fruit contém os seguintes documentos:

db.fruit.insertMany( [
   { _id: 1, item: "tangerine", type: "citrus" },
   { _id: 2, item: "lemon", type: "citrus" },
   { _id: 3, item: "grapefruit", type: "citrus" }
] )

A operação de aggregation seguinte usa $addFields para substituir o campo _id de cada documento pelo valor do campo item e substitui o campo item por um valor estático.

db.fruit.aggregate( [
  {
    $addFields: {
      _id : "$item",
      item: "fruit"
    }
  }
] )

A operação retorna o seguinte:

[
   { _id: "tangerine", item: "fruit", type: "citrus" },
   { _id: "lemon", item: "fruit", type: "citrus" },
   { _id: "grapefruit", item: "fruit", type: "citrus" }
]

Adicionar Elemento a uma Array

Crie uma coleção de amostra scores com o seguinte:

db.scores.insertMany( [
   { _id: 1, student: "Maya", homework: [ 10, 5, 10 ], quiz: [ 10, 8 ], extraCredit: 0 },
   { _id: 2, student: "Ryan", homework: [ 5, 6, 5 ], quiz: [ 8, 8 ], extraCredit: 8 }
] )

Você pode usar $addFields com uma expressão $concatArrays para adicionar um elemento a um campo de array existente. Por exemplo, a operação a seguir usa $addFields para substituir o campo homework por uma nova array cujos elementos são a array homework atual concatenada com outra array contendo uma nova pontuação [ 7 ].

db.scores.aggregate( [
   { $match: { _id: 1 } },
   { $addFields: { homework: { $concatArrays: [ "$homework", [ 7 ] ] } } }
] )