db.colección.findOneAndUpdate() (método mongosh)

Documento

Los criterios de selección para actualizar. Los mismos selectores query que en el método find() están disponibles.

Para actualizar el primer documento devuelto en la colección, especifique un documento vacío { }.

Si no se especifica, el valor es por defecto un documento vacío.

Si el campo de query no es un documento, la operación devuelve un error.

Si ningún documento coincide con filter, no se actualizará ningún documento.

documento o arreglo

El documento de actualización o una pipeline de agregación.

• Si se transfiere un documento con expresiones de operador de actualización, db.collection.findOneAndUpdate() realiza la modificación especificada.

  El documento debe contener únicamente operadores de actualización. No puede especificar un documento de reemplazo { <field1>: <value1>, ...}. Para usar un documento de reemplazo, consulte db.collection.findOneAndReplace() en su lugar.

• Si transfiere un pipeline de agregación [ <stage1>, <stage2>, ... ], db.collection.findOneAndUpdate() modifica el documento según el pipeline. El pipeline puede constar de las siguientes etapas:

  • $addFields y su alias $set

  • $project y su alias $unset

  • $replaceRoot y su alias $replaceWith

Documento

Opcional. Un documento que expresa el nivel de confirmación de escritura. Omite el uso del nivel de confirmación de escritura por defecto.

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

No establezcas explícitamente el nivel de confirmación de escritura para la operación si se ejecuta en una transacción. Para usar el nivel de confirmación de escritura con transacciones, consulta Transacciones y nivel de confirmación de escritura.

Documento

Opcional. Un subconjunto de campos que se deben devolver.

Para devolver todos los campos en el documento devuelto, omita este parámetro.

Si el argumento de proyección no es un documento, la operación genera un error.

Documento

Opcional. Especifica un orden de clasificación para los documentos que coinciden con el filter.

Si el argumento de orden no es un documento, la operación genera un error.

Consulte cursor.sort().

Número

Opcional. Especifica un límite de tiempo en milisegundos dentro del cual debe completarse la operación. Genera un error si se supera el límite.

booleano

Opcional. Cuando true, findOneAndUpdate() puede:

• Crea un nuevo documento si no hay documentos que coincidan con filter. Para obtener más detalles, consulte comportamiento de inserción. Devuelve null después de insertar el nuevo documento, a menos que returnNewDocument sea true.

• Actualiza un solo documento que coincida con filter.

Para evitar múltiples upserts, asegúrate de que el/los campo(s) filter estén indexados de forma única.

Se establece por defecto en false, lo que no inserta un nuevo documento cuando no se encuentra ninguna coincidencia.

string

Opcional. A partir de mongosh 0.13.2, returnDocument es una alternativa a returnNewDocument. Si ambas opciones están configuradas, returnDocument tiene prioridad.

returnDocument: "before" devuelve el documento original. returnDocument: "after" devuelve el documento actualizado.

booleano

Opcional. Cuando true, devuelve el documento actualizado en lugar del documento original.

Se establece por defecto en false.

Documento

Opcional.

Especifica la intercalación a utilizar para la operación.

La intercalación permite a los usuarios especificar reglas propias del lenguaje para la comparación de strings, como reglas para el uso de mayúsculas y minúsculas y marcas de acento.

La opción de intercalación tiene la siguiente sintaxis:

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

Al especificar la intercalación, el campo locale es obligatorio; todos los demás campos de intercalación son opcionales. Para las descripciones de los campos, consulta Documento de intercalación.

Si no se especifica la intercalación, pero la colección tiene una intercalación por defecto (ver db.createCollection()), la operación utiliza la intercalación especificada para la colección.

Si no se especifica ninguna intercalación para la colección o para las operaciones, MongoDB utiliza la comparación binaria simple usada en versiones anteriores para las comparaciones de strings.

No puedes especificar varias intercalaciones para una operación. Por ejemplo, no puedes especificar diferentes intercalaciones por campo, o si realizas una búsqueda con un ordenamiento, no puedes usar una intercalación para la búsqueda y otra para el ordenamiento.

arreglo

Opcional. Un arreglo de documentos de filtro que determinan qué elementos del arreglo modificar para una operación de actualización en un campo de arreglo.

En el documento de actualización, usa el operador posicional filtrado $[<identifier>] para definir un identificador, al que luego puedes hacer referencia en los documentos de filtro de arreglo. No puedes tener un documento de filtro de arreglo para un identificador si dicho identificador no está incluido en el documento de actualización.

El <identifier> debe comenzar con una letra minúscula y contener solo caracteres alfanuméricos.

Puedes incluir el mismo identificador varias veces en el documento de actualización; sin embargo, para cada identificador distinto ($[identifier]) en el documento de actualización, debes especificar exactamente un documento de filtro de arreglo correspondiente. Es decir, no puedes especificar múltiples documentos de filtro de arreglo para el mismo identificador. Por ejemplo, si la instrucción de actualizar incluye el identificador x (posiblemente varias veces), no puedes especificar lo siguiente para arrayFilters que incluya dos documentos de filtro separados para x:

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

Sin embargo, se pueden especificar condiciones compuestas sobre el mismo identificador en un único documento de filtro, como en los siguientes ejemplos:

// 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 ejemplos, consulte Operaciones de actualización de arreglos con arrayFilters.

arrayFilters no está disponible para actualizaciones que utilizan un pipeline de agregación.

Especifica la inclusión de un campo. Si especificas un entero distinto de cero para el valor de proyección, la operación trata el valor como true.

Especifica la exclusión de un campo.

Utiliza el operador de proyección de arreglo $ para devolver el primer elemento que coincide con la condición de query en el campo de arreglo. Si especificas un entero distinto de cero para el valor de proyección, la operación trata el valor como true.

No disponible para las vistas.

Utiliza los operadores de proyección de arreglos ($elemMatch, $slice) para especificar los elementos del arreglo que se deben incluir.

No disponible para las vistas.

Especifica el valor del campo proyectado.

Con el uso de expresiones y sintaxis de agregación, incluido el uso de literales y variables de agregación, se pueden proyectar campos nuevos o proyectar campos existentes con valores nuevos.

• Si se especifica un literal no numérico, no booleano (como una cadena de caracteres, un arreglo o una expresión de operador) para el valor de proyección, el campo se proyecta con el nuevo valor, por ejemplo:

  • { field: [ 1, 2, 3, "$someExistingField" ] }

  • { field: "New String Value" }

  • { field: { status: "Active", total: { $sum: "$existingArray" } } }

• Para proyectar un valor literal para un campo, utiliza la expresión de agregación $literal, por ejemplo:

  • { field: { $literal: 5 } }

  • { field: { $literal: true } }

  • { field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }