/ /

Métodos mongosh

Colecciones

Docs Home

Manual de base de datos

Referencia

Métodos mongosh

Colecciones

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

Esta versión de la documentación está archivada y ya no recibe soporte. Para actualizar su implementación 6.0, consulte Procedimientos de actualización de MongoDB.7.0

MongoDB con controladores

Esta página documenta una mongosh . Para ver el método equivalente en un driver de MongoDB, se debe consultar la página correspondiente al 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:	Un documento que contiene: Un valor booleano `acknowledged` como `true` si la operación se ejecutó con escribir `false` preocupación o si escribir preocupación estaba deshabilitada `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 el soporte de Atlas para 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

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

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

El método replaceOne() toma los siguientes 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. Cuando true, replaceOne() puede:

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.

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.

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 un ejemplo, consulta Especifica hint para replaceOne.

Comportamiento

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

`upsert`

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

Si especificas upsert: true en una colección particionada, debes incluir la clave de partición completa en el filter. Para obtener información adicional sobre el comportamiento db.collection.replaceOne() en una colección particionada, consulta Colecciones particionadas.

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 puedes utilizar el método replaceOne() en una colección de series de tiempo.

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

Una operación de db.collection.replaceOne() que incluya upsert: true en una colección particionada debe incluir la clave de fragmentación completa en filter.

Sin embargo, a los documentos de una colección fragmentada pueden faltarles los campos de clave de fragmento. Para identificar un documento que no tenga la clave de fragmento, puede usar la null coincidencia de igualdad. Junto con otra condición de filtro (como en el _id campo). 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 clave de fragmentación existente con db.collection.replaceOne():

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 particionada pueden carecer de los campos de clave de partición. Para usar db.collection.replaceOne() para establecer la clave de partición faltante del documento, se debe ejecutar en un mongos. No realizar la operación directamente en la partició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() puede usarse 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.

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

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

Volver

db.collection.renameCollection

db.colección.stats

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

`upsert`

`upsert` en una colección fragmentada

Especifique `hint` para `replaceOne`