$push (operador de atualização)

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 vários valores a um array. 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:

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

Os exemplos nesta página usam dados do conjunto de dados de amostra sample_mflix. Para obter detalhes sobre como carregar esse conjunto de dados em sua implantação autogerenciada do MongoDB , consulte Carregar o conjunto de dados de amostra. Se você fez modificações nos bancos de dados de amostra, talvez seja necessário descartar e recriar os bancos de dados para executar os exemplos nesta página.

db.movies.updateOne(
   { title: "The Dark Knight" },
   { $push: { genres: "Classic" } }
)

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

db.movies.updateMany(
   { "imdb.rating": { $gt: 9 } },
   { $push: { genres: "Acclaimed" } }
)

{
  acknowledged: true,
  insertedId: null,
  matchedCount: '...',
  modifiedCount: '...',
  upsertedCount: 0
}

db.movies.updateOne(
   { title: "The Dark Knight" },
   { $push: { genres: { $each: [ "Modern Classic", "Award-Winning" ] } } }
)

{
  acknowledged: true,
  insertedId: null,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedCount: 0
}

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

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
       }
     }
   }
)

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