db.collection.findAndModify()

fields Projeção

A opção fields usa um documento no seguinte formato:

{ field1: <value>, field2: <value> ... }

Upsert com índice exclusivo

Os upserts podem criar documentos duplicados, a menos que haja um índice único para evitar duplicatas.

Considere um exemplo em que nenhum documento com o nome Andy existe e vários clientes emitem o seguinte comando ao mesmo tempo:

db.people.findAndModify(
   {
     query: { name: "Andy" },
     update: { $inc: { score: 1 } },
     upsert: true
   }
)

Se todas as operações findOneAndUpdate() terminarem a fase de query antes que qualquer cliente insira dados com êxito e não houver um índice exclusivo no campo name , cada operação findOneAndUpdate() poderá resultar em uma inserção, criando vários documentos com name: Andy.

Um índice único no campo name garante que apenas um documento seja criado. Com um índice único em vigor, as múltiplas operações findOneAndUpdate() agora exibem o seguinte comportamento:

• Exatamente uma operação findOneAndUpdate() inserirá com sucesso um novo documento.

• Outras operações findOneAndUpdate() atualizam o documento recém-inserido ou falham devido a uma colisão de chave exclusiva.

  Para que outras operações do findOneAndUpdate() atualizem o documento recém-inserido, todas as seguintes condições devem ser atendidas:

  • A collection de destino tem um índice único que causaria um erro de chave duplicado.

  • A operação de atualização não é updateMany ou multi é false.

  • A condição de correspondência de atualização é:

    • Um único predicado de igualdade. Por exemplo { "fieldA" : "valueA" }

    • Um E lógico de predicados de igualdade. Por exemplo { "fieldA" : "valueA", "fieldB" : "valueB" }

  • O campo no predicado de igualdade correspondem ao campo no padrão de chave de índice único.

  • A operação de atualização não modifica nenhum campo no padrão de chave de índice único.

A tabela a seguir mostra exemplos de operações upsert que, quando ocorre uma colisão de chaves, resultam em uma atualização ou falha.

{ name : 1 }

db.people.updateOne(
   { name: "Andy" },
   { $inc: { score: 1 } },
   { upsert: true }
)

{ name : 1 }

db.people.updateOne(
   { name: { $ne: "Joe" } },
   { $set: { name: "Andy" } },
   { upsert: true }
 )

{ name : 1 }

db.people.updateOne(
  { name: "Andy", email: "andy@xyz.com" },
  { $set: { active: false } },
  { upsert: true }
)

Coleções fragmentadas

Para usar findAndModify em uma collection fragmentada:

• Se você só tiver como alvo um shard, pode usar uma chave de shard parcial no campo query ou,

• Você pode fornecer uma condição de igualdade em uma chave de shard completa no campo query.

Os documentos em uma coleção fragmentada podem não ter campos de chave de fragmento. Para direcionar um documento que não tem a chave de fragmento, você pode usar a correspondência de igualdade nullem conjunto com outra condição de filtro (como no campo _id). Por exemplo:

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

Validação do documento

O método db.collection.findAndModify() adiciona compatibilidade para a opção bypassDocumentValidation, que permite ignorar a validação de documentos ao inserir ou atualizar documentos em uma coleção com regras de validação.

Comparações com o método update

Ao atualizar um documento, db.collection.findAndModify() e o método updateOne() operam de forma diferente:

• Se vários documentos corresponderem aos critérios de atualização para db.collection.findAndModify(), você poderá especificar uma sort para fornecer alguma medida de controle sobre qual documento atualizar.

  updateOne() atualiza o primeiro documento que corresponde.

• Por padrão, db.collection.findAndModify() retorna a versão pré-modificada do documento. Para obter o documento atualizado, use a opção new.

  O método updateOne() retorna um objeto WriteResult() que contém o status da operação.

  Para retornar o documento atualizado, use o método find(). No entanto, outras atualizações podem ter modificado o documento entre a atualização e a recuperação do documento. Além disso, se a atualização modificou apenas um único documento, mas vários documentos corresponderam, você precisará usar lógica adicional para identificar o documento atualizado.

Se modificar um único documento, ambos o db.collection.findAndModify() e o método updateOne() atualizam atomicamente o documento. Consulte Atomicidade e transações para obter mais detalhes sobre as interações e a ordem das operações desses métodos.

Transações

db.collection.findAndModify() pode ser usado dentro de transações distribuídas.

Entradas de oplog

Se uma operação db.collection.findAndModify() conseguir localizar e modificar um documento, ela adicionará uma entrada no oplog (log de operações). Se a operação falhar ou não encontrar um documento para modificar, ela não adicionará uma entrada no oplog.

Atualização e devolução

O método a seguir atualiza e retorna um documento existente na collection de pessoas onde o documento corresponde aos critérios de query:

db.people.findAndModify({
    query: { name: "Tom", state: "active", rating: { $gt: 10 } },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } }
})

Este método executa as seguintes ações:

1. A query localiza um documento na collection people onde o campo name tem o valor Tom, o campo state tem o valor active e o campo rating tem um valor greater than 10.

2. O sort classifica os resultados da query em ordem crescente. Se vários documentos atenderem à condição query, o método selecionará para modificação o primeiro documento conforme ordenado por este sort.

3. A atualização increments do valor do campo score por 1.

4. O método retorna o documento original (ou seja, pré-modificação) selecionado para esta atualização:

   {
     "_id" : ObjectId("50f1e2c99beb36a0f45c6453"),
     "name" : "Tom",
     "state" : "active",
     "rating" : 100,
     "score" : 5
   }

   Para retornar o documento atualizado, adicione a opção new:true ao método.

   Se nenhum documento corresponder à condição query, o método retornará null.

Upsert

O método a seguir inclui a opção upsert: true para a operação update atualizar um documento correspondente ou, se não existir nenhum documento correspondente, criar um novo documento:

db.people.findAndModify({
    query: { name: "Gus", state: "active", rating: 100 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true
})

Se encontrar um documento correspondente, o método executará uma atualização.

Se não encontrar um documento correspondente, o método criará um novo documento. Como o método incluiu a opção sort, ele retorna um documento vazio { } como o documento original (pré-modificação):

{ }

Se o método não incluiu uma opção sort , o método retorna null.

null

Retornar novo documento

O método seguinte inclui a opção upsert: true e a opção new:true. O método atualiza um documento correspondente e retorna o documento atualizado ou, se não existir nenhum documento correspondente, insere um documento e retorna o documento recém-inserido no campo value.

No exemplo a seguir, nenhum documento na collection people corresponde à condição query:

db.people.findAndModify({
    query: { name: "Pascal", state: "active", rating: 25 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true,
    new: true
})

O método retorna o documento recém-inserido:

{
   "_id" : ObjectId("50f49ad6444c11ac2448a5d6"),
   "name" : "Pascal",
   "rating" : 25,
   "score" : 1,
   "state" : "active"
}

Classificar e remover

Ao incluir uma especificação sort no campo rating, o exemplo seguinte remove da collection people um único documento com o valor state de active e o menor rating entre os documentos correspondentes:

db.people.findAndModify(
   {
     query: { state: "active" },
     sort: { rating: 1 },
     remove: true
   }
)

O método retorna o documento excluído:

{
   "_id" : ObjectId("52fba867ab5fdca1299674ad"),
   "name" : "XYZ123",
   "score" : 1,
   "state" : "active",
   "rating" : 3
}

Especifique o agrupamento

A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento.

Uma coleção myColl possui os seguintes documentos:

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

A seguinte operação inclui a opção coleção:

db.myColl.findAndModify({
    query: { category: "cafe", status: "a" },
    sort: { category: 1 },
    update: { $set: { status: "Updated" } },
    collation: { locale: "fr", strength: 1 }
});

A operação retorna o seguinte documento:

{ "_id" : 1, "category" : "café", "status" : "A" }

Especificar arrayFilters para operações de atualização de array

Ao atualizar um campo de array, você pode especificar arrayFilters que determinam quais elementos de array atualizar.

db.students.insertMany( [
   { "_id" : 1, "grades" : [ 95, 92, 90 ] },
   { "_id" : 2, "grades" : [ 98, 100, 102 ] },
   { "_id" : 3, "grades" : [ 95, 110, 100 ] }
] )

db.students.findAndModify({
   query: { grades: { $gte: 100 } },
   update: { $set: { "grades.$[element]" : 100 } },
   arrayFilters: [ { "element": { $gte: 100 } } ]
})

{ "_id" : 1, "grades" : [ 95, 92, 90 ] }
{ "_id" : 2, "grades" : [ 98, 100, 100 ] }
{ "_id" : 3, "grades" : [ 95, 110, 100 ] }

db.students2.insertMany( [
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
] )

db.students2.findAndModify({
   query: { _id : 1 },
   update: { $set: { "grades.$[elem].mean" : 100 } },
   arrayFilters: [ { "elem.grade": { $gte: 85 } } ]
})

{
   "_id" : 1,
   "grades" : [
      { "grade" : 80, "mean" : 75, "std" : 6 },
      { "grade" : 85, "mean" : 100, "std" : 4 },
      { "grade" : 85, "mean" : 100, "std" : 6 }
   ]
}
{
   "_id" : 2,
   "grades" : [
      { "grade" : 90, "mean" : 75, "std" : 6 },
      { "grade" : 87, "mean" : 90, "std" : 3 },
      { "grade" : 85, "mean" : 85, "std" : 4 }
   ]
}

Usar um aggregation pipeline para atualizações

db.collection.findAndModify() pode aceitar um pipeline de agregação para a atualização. O pipeline pode consistir nas seguintes etapas:

• $addFields e seu alias $set

• $project e seu alias $unset

• $replaceRoot e seu nome alternativo $replaceWith.

O uso do aggregation pipeline permite uma instrução de atualização mais expressiva, como atualizações condicionais Express com base em valores de campo atuais ou atualização de um campo usando o valor de outro(s) campo(s).

Por exemplo, criar uma collection students2 com os seguintes documentos:

db.students2.insertMany( [
   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 90, "std" : 4 },
         { "grade" : 85, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }
] )

A operação a seguir localiza um documento em que o campo _id é igual a 1 e usa um aggregation pipeline para calcular um novo total de campo a partir do campo grades:

db.students2.findAndModify( {
   query: {  "_id" : 1 },
   update: [ { $set: { "total" : { $sum: "$grades.grade" } } } ],  // The $set stage is an alias for ``$addFields`` stage
   new: true
} )

A operação retorna o documento atualizado:

{
   "_id" : 1,
   "grades" : [ { "grade" : 80, "mean" : 75, "std" : 6 }, { "grade" : 85, "mean" : 90, "std" : 4 }, { "grade" : 85, "mean" : 85, "std" : 6 } ],
   "total" : 250
}

Usar variáveis em let

Para definir variáveis que você pode acessar em outro lugar no comando, use a opção let .

Criar uma coleção cakeFlavors:

db.cakeFlavors.insertMany( [
   { _id: 1, flavor: "chocolate" },
   { _id: 2, flavor: "strawberry" },
   { _id: 3, flavor: "cherry" }
] )

O exemplo a seguir define uma variável targetFlavor em let e usa a variável para alterar o sabor do bolo de cereja para laranja:

db.cakeFlavors.findAndModify( {
   query: {
      $expr: { $eq: [ "$flavor", "$$targetFlavor" ] }
   },
   update: { flavor: "orange" },
   let: { targetFlavor: "cherry" }
} )