Menu Docs

Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

$push

Nesta página

  • Definição
  • Compatibilidade
  • Sintaxe
  • Comportamento
  • Modificadores
  • Exemplos

Definição

$push

O operador $push acrescenta um valor especificado a uma array.

Compatibilidade

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

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

Sintaxe

O operador $push tem o formato:

{ $push: { <field1>: <value1>, ... } }

Para especificar um <field> em um documento incorporado ou em uma array, use a notação de ponto.

Comportamento

A partir do MongoDB 5.0, os operadores de atualização processam campos de documento com nomes baseados em cadeia de caracteres em ordem lexicográfica. Os campos com nomes numéricos são processados em ordem numérica. Consulte Atualizar Comportamento de Operadores para detalhes.

Se o campo estiver ausente no documento a ser atualizado, $push adicionará o campo de array com o valor como seu elemento.

Se o campo não for uma array, a operação falhará.

Se o valor for uma array, $push acrescentará a array inteira como um único elemento. Para adicionar cada elemento do valor separadamente, utilize o modificador $each com $push. Para obter um exemplo, consulte Anexar um valor a arrays em vários documentos. Para obter uma lista de modificadores disponíveis para $push, consulte Modificadores.

A partir do MongoDB 5.0, mongod não gera mais um erro quando você usa um operador de atualização como $push com uma expressão de operando vazia ( { } ). Uma atualização vazia não resulta em nenhuma alteração e nenhuma entrada no oplog é criada (o que significa que a operação é um no-op).

Modificadores

Você pode utilizar o operador $push com os seguintes modificadores:

Modificador
Descrição
$each
Anexa vários valores ao campo de array.
$slice
Limita o número de elementos de array. Requer o uso do modificador $each.
$sort
Ordena elementos da array. Requer o uso do modificador $each.
$position
Especifica o local na array no qual inserir os novos elementos. Requer o uso do modificador $each . Sem o modificador $position , o $push anexa os elementos ao final da array.

Quando usado com modificadores, o operador $push tem o formato:

{ $push: { <field1>: { <modifier1>: <value1>, ... }, ... } }

O processamento da operação do $push com modificadores ocorre na seguinte ordem, independentemente da ordem em que os modificadores aparecem:

  1. Atualize a array para adicionar elementos na posição correta.

  2. Aplicar ordenação, se especificado.

  3. Divida a array, se especificado.

  4. Armazene a array.

Exemplos

Crie a coleção students:

db.students.insertOne( { _id: 1, scores: [ 44, 78, 38, 80 ] } )

Anexar um valor a uma array

O exemplo a seguir anexa 89 à array scores:

db.students.updateOne(
   { _id: 1 },
   { $push: { scores: 89 } }
)

Saída de exemplo:

{ _id: 1, scores: [ 44, 78, 38, 80, 89 ] }

Anexar um valor a arrays em vários documentos

Adicione os seguintes documentos à collection students:

db.students.insertMany( [
   { _id: 2, scores: [ 45, 78, 38, 80, 89 ] } ,
   { _id: 3, scores: [ 46, 78, 38, 80, 89 ] } ,
   { _id: 4, scores: [ 47, 78, 38, 80, 89 ] }
] )

A operação $push a seguir acrescenta 95 à array scores em cada documento:

db.students.updateMany(
   { },
   { $push: { scores: 95 } }
)

Para confirmar que cada array scores inclui 95, execute a seguinte operação:

db.students.find()

A operação retorna os seguintes resultados:

[
   { _id: 1, scores: [ 44, 78, 38, 80, 89, 95 ] },
   { _id: 2, scores: [ 45, 78, 38, 80, 89, 95 ] },
   { _id: 3, scores: [ 46, 78, 38, 80, 89, 95 ] },
   { _id: 4, scores: [ 47, 78, 38, 80, 89, 95 ] }
]

Anexar vários valores a uma array

Use $push com o modificador $each para acrescentar vários valores ao campo de array.

O exemplo a seguir anexa cada elemento de [ 90, 92, 85 ] à array scores para o documento onde o campo name é igual a joe:

db.students.updateOne(
   { name: "joe" },
   { $push: { scores: { $each: [ 90, 92, 85 ] } } }
)

Use o operador $push com vários modificadores

Adicione o seguinte documento à coleção students:

db.students.insertOne(
   {
      "_id" : 5,
      "quizzes" : [
         { "wk": 1, "score" : 10 },
         { "wk": 2, "score" : 8 },
         { "wk": 3, "score" : 5 },
         { "wk": 4, "score" : 6 }
      ]
   }
)

A seguinte operação do $push utiliza:

  • o modificador $each para adicionar vários documentos à array quizzes,

  • o modificador $sort para ordenar todos os elementos da array quizzes modificada pelo campo score em ordem decrescente e

  • o modificador $slice para manter apenas os três primeiros elementos ordenados da array quizzes.

db.students.updateOne(
   { _id: 5 },
   {
     $push: {
       quizzes: {
          $each: [ { wk: 5, score: 8 }, { wk: 6, score: 7 }, { wk: 7, score: 6 } ],
          $sort: { score: -1 },
          $slice: 3
       }
     }
   }
)

Após a operação, somente os três testes de pontuação mais alta estão na array:

{
  "_id" : 5,
  "quizzes" : [
     { "wk" : 1, "score" : 10 },
     { "wk" : 2, "score" : 8 },
     { "wk" : 5, "score" : 8 }
  ]
}

Dica

Veja também:

← $pull
$pullAll →

Nesta página