$push

Nesta página

Definição

Compatibilidade
Sintaxe
Comportamento
Modifiers
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 do 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 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 ao usar um operador de atualização como $push com uma expressão de operando vazia ( { } ). Uma atualização vazia não resulta em alteração e nenhuma entrada no oplog é criada (o que significa que é sem operação).

Modifiers

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

Modifier	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:

Atualize a array para adicionar elementos na posição correta.
Aplicar ordenação, se especificado.
Divida a array, se especificado.
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 `$push` o operador 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 $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:

Voltar

$pull

$pullAll