db.collection.findOneAndUpdate()

Os critérios de seleção para a atualização. Os mesmos seletores de consulta que no método find() estão disponíveis.

Para atualizar o primeiro documento retornado na collection, especifique um documento vazio { }.

Se não for especificado, o padrão será um documento vazio.

Se o campo de consulta não for um documento, a operação retornará um erro.

Se nenhum documento corresponder ao filter, nenhum documento será atualizado.

O documento de atualização ou um pipeline de agregação.

• Se for passado um documento com expressões de operador de atualização, db.collection.findOneAndUpdate() executará a modificação especificada.

  Observação

  O documento deve conter somente operadores de atualização. Você não pode especificar um documento substituto { <field1>: <value1>, ...}. Para usar um documento de substituição, consulte db.collection.findOneAndReplace().

• Se for passado um pipeline de agregação [ <stage1>, <stage2>, ... ], db.collection.findOneAndUpdate() modifica o documento de acordo com o pipeline. O pipeline pode consistir nas seguintes etapas:

  • $addFields e seu alias $set

  • $project e seu alias $unset

  • $replaceRoot e seu nome alternativo $replaceWith.

Opcional. Um documento que expressa o write concern. Omitir para usar o write concern padrão.

{ w: <value>, j: <boolean>, wtimeout: <number> }

Não defina explicitamente a preocupação de gravação para a operação se for executada em uma transação. Para usar write concern com transações, consulte Transações e write concern.

Opcional. Um subconjunto de campos para retornar.

Para retornar todos os campos no documento retornado, omita este parâmetro.

Se o argumento de projeção não for um documento, ocorrerá um erro na operação.

Opcional. Especifica uma ordem de classificação para os documentos correspondidos pelo filter.

Se o argumento de classificação não for um documento, ocorrerá um erro com a operação.

Consulte cursor.sort().

Opcional. Quando true, findOneAndUpdate() ou:

• Cria um novo documento se nenhum documento corresponder a filter. Para obter mais detalhes, consulte comportamento upsert. Retorna null após inserir o novo documento, a menos que returnNewDocument seja true.

• Atualiza um único documento que corresponda a filter.

Para evitar várias atualizações, certifique-se de que os campos filter sejam indexados de forma exclusiva.

O padrão é false, que não insere um novo documento quando nenhuma correspondência é encontrada.

Opcional. A partir da versão 0.13.2 do mongosh, returnDocument é uma alternativa a returnNewDocument. Se ambas as opções forem definidas, returnDocument terá precedência.

returnDocument: "before" retorna o documento original. returnDocument: "after" retorna o documento atualizado.

Opcional. Quando true, retorna o documento atualizado em vez do documento original.

Padrão é false.

Opcional.

Especifica o agrupamento a ser usado para a operação.

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.

A opção de agrupamento tem a seguinte sintaxe:

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

Ao especificar agrupamento, o campo locale é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento.

Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão (consulte db.createCollection()), a operação usará o agrupamento especificado para a coleção.

Se nenhum agrupamento for especificado para a coleção ou para as operações, o MongoDB usa a comparação binária simples usada nas versões anteriores para comparações de strings.

Você não pode especificar vários agrupamentos para uma operação. Por exemplo, você não pode especificar agrupamentos diferentes por campo ou, se estiver realizando uma busca com uma classificação, não poderá usar um agrupamento para a busca e outro para a classificação.

Opcional. Uma array de documentos de filtro que determina quais elementos da array modificar para uma operação de atualização em um campo da array.

No documento de atualização, use o operador posicional filtrado $[<identifier>] para definir um identificador, que você então faz referência nos documentos de filtro de array. Você não pode ter um documento de filtro de array para um identificador se o identificador não estiver incluído no documento de atualização.

O <identifier> deve começar com uma letra minúscula e conter apenas caracteres alfanuméricos.

Você pode incluir o mesmo identificador várias vezes no documento de atualização; entretanto, para cada identificador distinto ($[identifier]) no documento de atualização, você deve especificar exatamente um documento de filtro de array correspondente. Ou seja, não é possível especificar vários documentos de filtro de array para o mesmo identificador. Por exemplo, se a instrução de atualização incluir o identificador x (possivelmente várias vezes), você não poderá especificar o seguinte para arrayFilters que inclui 2 documentos de filtro separados para x:

// INVALID
[
  { "x.a": { $gt: 85 } },
  { "x.b": { $gt: 80 } }
]

No entanto, você pode especificar condições compostas no mesmo identificador em um único documento de filtro, como nos exemplos a seguir:

// Example 1
[
  { $or: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 2
[
  { $and: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 3
[
  { "x.a": { $gt: 85 }, "x.b": { $gt: 80 } }
]

Para ver exemplos, consulte a página Operações de atualização de array com arrayFilters.