Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Operações de agregação
/
Referência
/
Operadores

$setField (agregação)

Nesta página

  • Definição
  • Sintaxe
  • Comportamento
  • Exemplos

Definição

$setField

Novidades na versão 5.0.

Adiciona, atualiza ou remove um campo especificado em um documento.

Você pode usar $setField para adicionar, atualizar ou remover campos com nomes que contenham pontos (.) ou começar com cifrões de dólar ($).

Dica

Use $getField para recuperar os valores de campos que contêm cifrões ($) ou pontos (.) que você adiciona ou atualiza com $setField.

Sintaxe

$setField tem a seguinte sintaxe:

{
  $setField: {
    field: <String>,
    input: <Object>,
    value: <Expression>
  }
}

Você deve fornecer os seguintes campos:

Campo
Tipo
Descrição
field
String
Campo no objeto input que você deseja adicionar, atualizar ou remover. field pode ser qualquer expressão válida que resulte em uma constante de string.
input
Objeto
Documento que contém o field que você deseja adicionar ou atualizar. input deve determinar um objeto, missing, null ou undefined.
value
Expressão

O valor que você deseja atribuir a field. value pode ser qualquer expressãoválida.

Defina como $$REMOVE para remover field do documento input.

Comportamento

  • Se input for avaliado como missing, undefined ou null, $setField retornará null e não atualizará input.

  • Se input for avaliado como algo diferente de um objeto, missing, undefined ou null, $setField retornará um erro.

  • Se field resolver para algo diferente de uma constante de string, $setField retornará um erro.

  • Se field não existir em input, $setField adiciona-o.

  • $setField não atravessa implicitamente objetos ou arrays. Por exemplo, $setField avalia um valor field de "a.b.c" como um campo de nível superior "a.b.c" em vez de um campo aninhado, { "a": { "b": { "c": } } }.

  • $unsetField é um alias para $setField com um valor de entrada de $$REMOVE. As seguintes expressões são equivalentes:

    {
       $setField: {
          field: <field name>,
          input: “$$ROOT”,
          value: "$$REMOVE"
       }
    }
    {
       $unsetField: {
          field: <field name>,
          input: “$$ROOT”
       }
    }

Dica

Veja também:

Considerações para nomes de campo

Exemplos

Adicionar Campos que Contêm Períodos (.)

Considere uma coleção inventory com os seguintes documentos:

db.inventory.insertMany( [
   { "_id" : 1, "item" : "sweatshirt", price: 45.99, qty: 300 }
   { "_id" : 2, "item" : "winter coat", price: 499.99, qty: 200 }
   { "_id" : 3, "item" : "sun dress", price: 199.99, qty: 250 }
   { "_id" : 4, "item" : "leather boots", price: 249.99, qty: 300 }
   { "_id" : 5, "item" : "bow tie", price: 9.99, qty: 180 }
] )

A operação a seguir usa o estágio de pipeline $replaceWith e o operador $setField para adicionar um novo campo a cada documento, "price.usd". O valor de "price.usd" será igual ao valor de "price" em cada documento. Finalmente, a operação utiliza o estágio do pipeline $unset para remover o campo "price".

db.inventory.aggregate( [
   { $replaceWith: {
        $setField: {
           field: "price.usd",
           input: "$$ROOT",
           value: "$price"
   } } },
   { $unset: "price" }
] )

A operação retorna os seguintes resultados:

[
  { _id: 1, item: 'sweatshirt', qty: 300, 'price.usd': 45.99 },
  { _id: 2, item: 'winter coat', qty: 200, 'price.usd': 499.99 },
  { _id: 3, item: 'sun dress', qty: 250, 'price.usd': 199.99 },
  { _id: 4, item: 'leather boots', qty: 300, 'price.usd': 249.99 },
  { _id: 5, item: 'bow tie', qty: 180, 'price.usd': 9.99 }
]

Adicionar campos que começam com um cifrão ($)

Considere uma coleção inventory com os seguintes documentos:

db.inventory.insertMany( [
   { "_id" : 1, "item" : "sweatshirt", price: 45.99, qty: 300 }
   { "_id" : 2, "item" : "winter coat", price: 499.99, qty: 200 }
   { "_id" : 3, "item" : "sun dress", price: 199.99, qty: 250 }
   { "_id" : 4, "item" : "leather boots", price: 249.99, qty: 300 }
   { "_id" : 5, "item" : "bow tie", price: 9.99, qty: 180 }
] )

A operação a seguir utiliza o estágio do pipeline $replaceWith e os operadores $setField e $literal para adicionar um novo campo a cada documento, "$price". O valor de "$price" será igual ao valor de "price" em cada documento. Por fim, a operação utiliza o estágio do pipeline $unset para remover o campo "price".

db.inventory.aggregate( [
   { $replaceWith: {
        $setField: {
           field: { $literal: "$price" },
           input: "$$ROOT",
           value: "$price"
   } } },
   { $unset: "price" }
] )

A operação retorna os seguintes resultados:

[
  { _id: 1, item: 'sweatshirt', qty: 300, '$price': 45.99 },
  { _id: 2, item: 'winter coat', qty: 200, '$price': 499.99 },
  { _id: 3, item: 'sun dress', qty: 250, '$price': 199.99 },
  { _id: 4, item: 'leather boots', qty: 300, '$price': 249.99 },
  { _id: 5, item: 'bow tie', qty: 180, '$price': 9.99 }
]

Atualizar Campos que Contêm Períodos (.)

Considere uma coleção inventory com os seguintes documentos:

db.inventory.insertMany( [
   { _id: 1, item: 'sweatshirt', qty: 300, 'price.usd': 45.99 },
   { _id: 2, item: 'winter coat', qty: 200, 'price.usd': 499.99 },
   { _id: 3, item: 'sun dress', qty: 250, 'price.usd': 199.99 },
   { _id: 4, item: 'leather boots', qty: 300, 'price.usd': 249.99 },
   { _id: 5, item: 'bow tie', qty: 180, 'price.usd': 9.99 }
] )

A operação a seguir utiliza o estágio de pipeline $match para encontrar um documento específico e o estágio de pipeline $replaceWith e o operador $setField para atualizar o campo "price.usd" no documento correspondente:

db.inventory.aggregate( [
   { $match: { _id: 1 } },
   { $replaceWith: {
        $setField: {
           field: "price.usd",
           input: "$$ROOT",
           value: 49.99
    } } }
] )

A operação retorna os seguintes resultados:

[
  { _id: 1, item: 'sweatshirt', qty: 300, 'price.usd': 49.99 }
]

Atualizar campos que começam com um cifrão ($)

Considere uma coleção inventory com os seguintes documentos:

db.inventory.insertMany([
   { _id: 1, item: 'sweatshirt', qty: 300, '$price': 45.99 },
   { _id: 2, item: 'winter coat', qty: 200, '$price': 499.99 },
   { _id: 3, item: 'sun dress', qty: 250, '$price': 199.99 },
   { _id: 4, item: 'leather boots', qty: 300, '$price': 249.99 },
   { _id: 5, item: 'bow tie', qty: 180, '$price': 9.99 }
] )

A operação a seguir usa o estágio de pipeline $match para localizar um documento específico e o estágio de pipeline $replaceWith e os operadores $setField e $literal para atualizar o campo "$price" no documento correspondente:

db.inventory.aggregate( [
   { $match: { _id: 1 } },
   { $replaceWith: {
        $setField: {
           field: { $literal: "$price" },
           input: "$$ROOT",
           value: 49.99
   } } }
] )

A operação retorna os seguintes resultados:

[
  { _id: 1, item: 'sweatshirt', qty: 300, '$price': 49.99 }
]

Remover Campos que Contêm Períodos (.)

Considere uma coleção inventory com os seguintes documentos:

db.inventory.insertMany([
   { _id: 1, item: 'sweatshirt', qty: 300, 'price.usd': 45.99 },
   { _id: 2, item: 'winter coat', qty: 200, 'price.usd': 499.99 },
   { _id: 3, item: 'sun dress', qty: 250, 'price.usd': 199.99 },
   { _id: 4, item: 'leather boots', qty: 300, 'price.usd': 249.99 },
   { _id: 5, item: 'bow tie', qty: 180, 'price.usd': 9.99 }
] )

A operação a seguir usa o estágio de pipeline $replaceWith e o operador $setField e $$REMOVE para remover o campo "price.usd" de cada documento:

db.inventory.aggregate( [
   { $replaceWith:  {
        $setField: {
           field: "price.usd",
           input: "$$ROOT",
           value: "$$REMOVE"
   } } }
] )

A operação retorna os seguintes resultados:

[
  { _id: 1, item: 'sweatshirt', qty: 300 },
  { _id: 2, item: 'winter coat', qty: 200 },
  { _id: 3, item: 'sun dress', qty: 250 },
  { _id: 4, item: 'leather boots', qty: 300 },
  { _id: 5, item: 'bow tie', qty: 180 }
]

Uma query semelhante escrita utilizando o nome alternativo $unsetField retorna os mesmos resultados:

db.inventory.aggregate( [
   { $replaceWith:  {
        $unsetField: {
           field: "price.usd",
           input: "$$ROOT"
   } } }
] )

Remover campos que começam com um cifrão ($)

Considere uma coleção inventory com os seguintes documentos:

db.inventory.insertMany( [
   { _id: 1, item: 'sweatshirt', qty: 300, '$price': 45.99 },
   { _id: 2, item: 'winter coat', qty: 200, '$price': 499.99 },
   { _id: 3, item: 'sun dress', qty: 250, '$price': 199.99 },
   { _id: 4, item: 'leather boots', qty: 300, '$price': 249.99 },
   { _id: 5, item: 'bow tie', qty: 180, '$price': 9.99 }
} )

A operação a seguir usa o estágio de pipeline $replaceWith, os operadores $setField e $literal, e $$REMOVE para remover o campo "$price" de cada documento:

db.inventory.aggregate( [
   { $replaceWith: {
        $setField: {
           field: { $literal: "$price" },
           input: "$$ROOT",
           value: "$$REMOVE"
   } } }
] )

A operação retorna os seguintes resultados:

[
  { _id: 1, item: 'sweatshirt', qty: 300 },
  { _id: 2, item: 'winter coat', qty: 200 },
  { _id: 3, item: 'sun dress', qty: 250 },
  { _id: 4, item: 'leather boots', qty: 300 },
  { _id: 5, item: 'bow tie', qty: 180 }
]

Uma query semelhante escrita utilizando o nome alternativo $unsetField retorna os mesmos resultados:

db.inventory.aggregate( [
  { $replaceWith: {
       $unsetField: {
          field: { $literal: "$price" },
          input: "$$ROOT"
  } } }
] )

Dica

Veja também:

$unsetField

Voltar

$setEquals

Próximo

$setIntersection