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

MongoDB con controladores

Esta página documenta un método mongosh. Para ver el método equivalente en un driver de MongoDB, consulte la página correspondiente a su lenguaje de programación:

C#Java Sync Node.js PyMongo C C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Mongoid Rust Scala

Definición

db.collection.replaceOne(filter, replacement, options)

Reemplaza un único documento dentro de la colección según el filtro.

Devuelve:

Devuelve:	Un documento que contiene: Un valor booleano `acknowledged` en `true` si la operación se ejecutó con nivel de confirmación de escritura (write concern) o en `false` si el nivel de confirmación de escritura (write concern) estaba deshabilitado `matchedCount` que contiene el número de documentos coincidentes `modifiedCount` que contiene el número de documentos modificados `upsertedId` que contiene el `_id` para el documento actualizado o insertado

Un documento que contiene:

Un valor booleano acknowledged en true si la operación se ejecutó con nivel de confirmación de escritura (write concern) o en false si el nivel de confirmación de escritura (write concern) estaba deshabilitado
matchedCount que contiene el número de documentos coincidentes
modifiedCount que contiene el número de documentos modificados
upsertedId que contiene el _id para el documento actualizado o insertado

Compatibilidad

Este método está disponible en implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

Nota

Este comando es compatible con todos los clústeres de MongoDB Atlas. Para obtener información sobre la compatibilidad de Atlas con todos los comandos, consulte Comandos no compatibles.

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

Sintaxis

Cambiado en la versión 8.0.

El método tiene la siguiente replaceOne() forma:

db.collection.replaceOne(
   <filter>,
   <replacement>,
   {
      upsert: <boolean>,
      writeConcern: <document>,
      collation: <document>,
      hint: <document|string>,
      sort: <document>
   }
)

El método toma los siguientes replaceOne() parámetros:

Parameter

Tipo

Descripción

filtro

Documento

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

Especifica un documento vacío { } para reemplazar el primer documento devuelto en la colección.

replacement

Documento

El documento de reemplazo.

No puede contener operadores de actualización.

upsert

booleano

Opcional.true replaceOne() Cuando,:

Inserta el documento del parámetro replacement si ningún documento coincide con el filter.
Reemplaza el documento que corresponde a filter con el documento de replacement.

MongoDB añadirá el campo _id al documento de reemplazo si no está especificado en los documentos filter o replacement. Si _id está presente en ambos, los valores deben ser iguales.

Para evitar múltiples inserciones, asegúrate de que los campos de query estén indexados de forma única.

Se establece por defecto en false.

writeConcern

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.

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.

collation

Documento

Opcional.

Opcional. Especifica la intercalación que se debe 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.

hint

Documento

Opcional. Un documento o string que especifica el índice que se utilizará para admitir el filtro.

La opción puede tomar un documento de especificación de índice o la string de nombre de índice.

Si especifica un índice que no existe, la operación genera un error.

Para ver un ejemplo, consulte Especificar hint replaceOnepara.

sort

Documento

Opcional.

Ordena los documentos antes de que se aplique la actualización.

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

MongoDB no almacena documentos en una colección en un orden específico. Al ordenar en un campo que contiene valores duplicados, los documentos que contienen esos valores pueden ser devueltos en cualquier orden.

La operación $sort no es un "ordenamiento estable", lo que significa que no se garantiza que los documentos con claves de ordenamiento equivalentes permanezcan en el mismo orden relativo en la salida y en la entrada.

Si el campo especificado en los criterios de ordenación no existe en dos documentos, entonces el valor por el cual se ordenan es el mismo. Los dos documentos pueden ser devueltos en cualquier orden.

Si se desea un orden de clasificación coherente, se debe incluir al menos un campo en la clasificación que contenga valores únicos. La forma más sencilla de garantizar esto es incluir el campo _id en la query de ordenación.

Para obtener más información, consulta Coherencia de organización.

Nuevo en la versión 8.0.

Para ver un ejemplo, consulte Reemplazar un documento y usar una función de ordenación.

Comportamiento

replaceOne() reemplaza el primer documento coincidente en la colección que coincide filter con, utilizando el replacement documento.

`upsert`

Si upsert: true y ningún documento coincide filter con, crea un nuevo documento basado endb.collection.replaceOne() el replacement documento.

Modificado en la versión 8.0:

Si especifica upsert: true en una colección particionada, no necesita incluir la clave de partición completa en el filter.

Para obtener información adicional sobre el comportamiento en una colección fragmentada,db.collection.replaceOne() consulte Colecciones fragmentadas.

Consulta Reemplazar con inserción.

Colecciones con tamaño fijo

Si una operación de reemplazo cambia el tamaño del documento, la operación fallará.

Colecciones de series de tiempo

No se puede utilizar el método en una replaceOne() colecciónde series temporales.

Colecciones fragmentadas

db.collection.replaceOne() intenta apuntar a una única partición, primero utilizando el filtro de query. Si la operación no puede apuntar a una única partición mediante el filtro de query, entonces intenta apuntar mediante el documento de reemplazo.

En versiones anteriores, la operación intenta dirigirse utilizando el documento de reemplazo.

Requisitos de la clave de fragmentación en el documento de reemplazo

No es necesario que el documento de reemplazo incluya la clave de partición.

Advertencia

Los documentos en colecciones particionadas pueden no tener los campos de clave de partición. Toma precauciones para evitar remover accidentalmente la clave de partición al cambiar el valor de clave de partición de un documento.

`upsert` en una colección fragmentada

A partir de MongoDB,8.0 una operación que db.collection.replaceOne() incluye upsert: true en una colección fragmentada no necesita incluir la clave de fragmentación completa en filter el.

Sin embargo, los documentos en una colección particionada pueden carecer de los campos de clave de partición. Para dirigirse a un documento que carece de la clave de partición, puede usar la coincidencia exacta null junto con otra condición de filtro (como en el campo _id). Por ejemplo:

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

Modificación de la clave de fragmentación

Puede actualizarse el valor de clave de partición de un documento a menos que el campo de clave de partición sea el campo _id inmutable.

Advertencia

Para modificar el valor de la clave de fragmento existente db.collection.replaceOne() con:

Debes ejecutar en un mongos. No emitas la operación directamente en la partición.
Usted debe ejecutar ya sea en una transacción o como una escritura reintentable.
Debes incluir un filtro de igualdad en la clave de partición completa.

Clave de fragmentación faltante

Los documentos en una colección fragmentada pueden carecer de los campos de clave de fragmentación. Para usar y db.collection.replaceOne() establecer la clave de fragmentación faltante del documento, debe ejecutar la mongos operación en un.No ejecute la operación directamente en la fragmentación.

Además, se aplican los siguientes requisitos:

Tarea	Requisitos
Para configurar en `null`	Requiere un filtro de igualdad en la clave de partición completa si se especifica `upsert: true`.
Para establecer en un valor que no sea `null`	Debe realizarse dentro de una transacción o como una escritura reintentable. Requiere filtro de igualdad en la clave de partición completa si: `upsert: true`, o el nuevo valor de clave de fragmentación pertenece a un fragmento diferente.

Tip

Dado que un valor de clave faltante se devuelve como parte de una coincidencia exacta nula, para evitar actualizar una clave con valor nulo, incluya condiciones de query adicionales (como en el campo _id) según corresponda.

Véase también:

Transacciones

db.collection.replaceOne() se puede utilizar dentro de transacciones distribuidas.

Importante

En la mayoría de los casos, una transacción distribuida incurre en un costo de rendimiento mayor que las escrituras de documentos individuales, y la disponibilidad de transacciones distribuidas no debería ser un sustituto para un diseño de esquema efectivo. Para muchos casos, el modelo de datos desnormalizado (documento incrustado y matrices) seguirá siendo óptimo para tus datos y casos de uso. Es decir, en muchos casos, modelar tus datos de forma adecuada minimizará la necesidad de transacciones distribuidas.

Para consideraciones adicionales sobre el uso de transacciones (como el límite de tiempo de ejecución y el límite de tamaño del oplog), consulta también las consideraciones de producción.

Inserta dentro de transacciones

Puedes crear colecciones e índices dentro de una transacción distribuida si la transacción no es una transacción de escritura entre particiones.

La operacióndb.collection.replaceOne() con puede ejecutarse en una colección existente o en una colección inexistente. Si se ejecuta en una colección inexistente, la operación crea la colección.upsert: true

Tip

Crear colecciones e índices en una transacción

Nivel de confirmación de escritura y transacciones

Ejemplos

Reemplaza

La colección restaurant contiene los siguientes documentos:

db.restaurant.insertMany ( [
   { _id: 1, name: "Central Perk Cafe", Borough: "Manhattan" },
   { _id: 2, name: "Rock A Feller Bar and Grill", Borough: "Queens", violations: 2 },
   { _id: 3, name: "Empire State Pub", Borough: "Brooklyn", violations: 0 }
] )

La siguiente operación reemplaza un único documento en el que name: "Central Perk Cafe":

try {
   db.restaurant.replaceOne(
      { "name" : "Central Perk Cafe" },
      { "name" : "Central Pork Cafe", "Borough" : "Manhattan" }
   );
} catch (e){
   print(e);
}

La operación arroja:

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

Si no se encuentra ninguna coincidencia, la operación arroja lo siguiente:

{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }

Al configurar upsert: true se insertaría el documento si no se encuentra ninguna coincidencia. Consulta Reemplazar con inserción.

Reemplazar por inserción

La colección restaurant contiene los siguientes documentos:

db.restaurant.insertMany( [
   { _id: 1, name: "Central Perk Cafe", Borough: "Manhattan",  violations: 3 },
   { _id: 2, name: "Rock A Feller Bar and Grill", Borough: "Queens", violations: 2 },
   { _id: 3, name: "Empire State Pub", Borough: "Brooklyn", violations: 0 }
] )

La siguiente operación intenta reemplazar el documento con name : "Pizza Rat's Pizzaria", con upsert : true:

try {
   db.restaurant.replaceOne(
      { "name" : "Pizza Rat's Pizzaria" },
      { "_id": 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 8 },
      { upsert: true }
   );
} catch (e){
   print(e);
}

En upsert : true, el documento se inserta basándose en el documento replacement. La operación devuelve:

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : 4
}

La colección ahora contiene los siguientes documentos:

{ _id: 1, name: "Central Perk Cafe", Borough: "Manhattan", violations: 3 },
{ _id: 2, name: "Rock A Feller Bar and Grill", Borough: "Queens", violations: 2 },
{ _id: 3, name: "Empire State Pub", Borough: "Brooklyn", violations: 0 },
{ _id: 4, name: "Pizza Rat's Pizzaria", Borough: "Manhattan", violations: 8 }

Reemplazar con nivel de confirmación de escritura (Write Concern)

Dado un set de réplicas de tres nodos, la siguiente operación especifica un w de majority y un wtimeout de 100:

try {
   db.restaurant.replaceOne(
       { "name" : "Pizza Rat's Pizzaria" },
       { "name" : "Pizza Rat's Pub", "Borough" : "Manhattan", "violations" : 3 },
       { w: "majority", wtimeout: 100 }
   );
} catch (e) {
   print(e);
}

Si el reconocimiento tarda más que el límite de wtimeout, se obtiene la siguiente excepción:

WriteConcernError({
   "code" : 64,
   "errmsg" : "waiting for replication timed out",
   "errInfo" : {
     "wtimeout" : true,
     "writeConcern" : {
       "w" : "majority",
       "wtimeout" : 100,
       "provenance" : "getLastErrorDefaults"
     }
   }
})

La siguiente tabla explica los posibles valores de errInfo.writeConcern.provenance:

Origen	Descripción
`clientSupplied`	El nivel de confirmación de escritura se especificó en la aplicación.
`customDefault`	El nivel de confirmación de escritura se originó a partir de un valor por defecto personalizado. Vea `setDefaultRWConcern`.
`getLastErrorDefaults`	El nivel de confirmación de escritura se originó en el campo `settings.getLastErrorDefaults` del set de réplicas.
`implicitDefault`	El nivel de confirmación de escritura (write concern) se originó en el servidor en ausencia de todas las demás especificaciones de nivel de confirmación de escritura (write concern).

Especificar la intercalació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.

Una colección myColl tiene los siguientes documentos:

db.myColl.insertMany( [
   { _id: 1, category: "café", status: "A" },
   { _id: 2, category: "cafe", status: "a" },
   { _id: 3, category: "cafE", status: "a" }
] )

La siguiente operación incluye la opción de intercalación:

db.myColl.replaceOne(
   { category: "cafe", status: "a" },
   { category: "cafÉ", status: "Replaced" },
   { collation: { locale: "fr", strength: 1 } }
);

Especifique `hint` para `replaceOne`

Crea una colección de ejemplo members con los siguientes documentos:

db.members.insertMany( [
   { _id: 1, member: "abc123", status: "P", points:  0,  misc1: null, misc2: null },
   { _id: 2, member: "xyz123", status: "A", points: 60,  misc1: "reminder: ping me at 100pts", misc2: "Some random comment" },
   { _id: 3, member: "lmn123", status: "P", points:  0,  misc1: null, misc2: null },
   { _id: 4, member: "pqr123", status: "D", points: 20,  misc1: "Deactivated", misc2: null },
   { _id: 5, member: "ijk123", status: "P", points:  0,  misc1: null, misc2: null },
   { _id: 6, member: "cde123", status: "A", points: 86,  misc1: "reminder: ping me at 100pts", misc2: "Some random comment" }
] )

Cree los siguientes índices en la colección:

db.members.createIndex( { status: 1 } )
db.members.createIndex( { points: 1 } )

La siguiente operación de actualización indica explícitamente que se debe usar el índice { status: 1 }:

Nota

Si especifica un índice que no existe, la operación genera un error.

db.members.replaceOne(
   { "points": { $lte: 20 }, "status": "P" },
   { "misc1": "using index on status", status: "P", member: "replacement", points: "20"},
   { hint: { status: 1 } }
)

La operación devuelve lo siguiente:

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

Para ver los índices utilizados, puede usar el pipeline $indexStats:

db.members.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] )

Reemplazar un documento y usar un orden

Cree la siguiente colección restaurantsSort:

db.restaurantsSort.insertMany( [
   { _id: 1, name: "Pizza Place", rating: 4, violations: 2 },
   { _id: 2, name: "Burger Joint", rating: 3, violations: 5 },
   { _id: 3, name: "Taco Shop", rating: 4, violations: 1 }
] )

El siguiente ejemplo reemplaza "Pizza Place" por "Clean Eats":

db.restaurantsSort.replaceOne(
   // Find restaurants with a rating of 4
   { rating: 4 },
   // Replace the found restaurant with Clean Eats
   { name: "Clean Eats", rating: 4, violations: 2 },
   // Sort restaurants found by the most violations with a descending sort
   { sort: { violations: -1 } }
)

El ejemplo:

Encuentra restaurantes con un rating de 4, que son "Pizza Place" y "Taco Shop".
Ordena los restaurantes encontrados por violations en orden descendente, lo que coloca a "Pizza Place" en la primera posición.
Reemplace "Pizza Place" con "Clean Eats".

El siguiente query devuelve los restaurantes:

db.restaurantsSort.find()

La salida muestra que "Pizza Place" fue reemplazado por "Clean Eats":

[
   { _id: 1, name: 'Clean Eats', rating: 4, violations: 2 },
   { _id: 2, name: 'Burger Joint', rating: 3, violations: 5 },
   { _id: 3, name: 'Taco Shop', rating: 4, violations: 1 }
]

Volver

db.collection.renameCollection

db.colección.stats

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

Definición

Compatibilidad

Nota

Sintaxis

Comportamiento

upsert

Colecciones con tamaño fijo

Colecciones de series de tiempo

Colecciones fragmentadas

Requisitos de la clave de fragmentación en el documento de reemplazo

Advertencia

upsert en una colección fragmentada

Modificación de la clave de fragmentación

Advertencia

Clave de fragmentación faltante

Tip

Transacciones

Importante

Inserta dentro de transacciones

Tip

Nivel de confirmación de escritura y transacciones

Ejemplos

Reemplaza

Reemplazar por inserción

Reemplazar con nivel de confirmación de escritura (Write Concern)

Especificar la intercalación

Especifique hint para replaceOne

Nota

Reemplazar un documento y usar un orden

`upsert`

`upsert` en una colección fragmentada

Especifique `hint` para `replaceOne`