/ /

Driver Rust

Docs Home

Librerías de clientes

Rust

Driver Rust

Docs Home

Librerías de clientes

Rust

Driver Rust

Insertar documentos

Overview

En esta guía, puedes aprender cómo insertar documentos en una colección de MongoDB.

Antes de que pueda buscar, actualizar y borrar cualquier documento en MongoDB, debe insertarlos. Puede insertar documentos utilizando los siguientes métodos:

insert_one() para insertar un documento
insert_many() para insertar uno o más documentos

Esta guía incluye las siguientes secciones:

El campo _id describe el campo _id que contiene cada documento
Insert a documento describe cómo utilizar el driver para insertar un solo documento en una colección
Insertar varios documentos describe cómo usar el controlador para insertar varios documentos en una colección
Información adicional proporciona enlaces a recursos y documentación de la API para los tipos y métodos mencionados en esta guía

El campo _id

En una colección de MongoDB, cada documento debe contener un valor único de campo _id. El controlador genera automáticamente un valor único para cada documento como un tipo ObjectId cuando agregas datos a una colección.

Si prefiere establecer valores personalizados, puede asignar los valores en los campos _id de los documentos pasados a su operación de inserción.

Importante

Duplicate _id Values

Si intentas insertar documentos que incluyan valores duplicados de _id, estos valores infringen las restricciones del índice único y provocan que la operación de guardar falle.

Para obtener más información sobre el campo _id, consulte Índices únicos en el manual del servidor.

Para obtener más información sobre la estructura y las reglas de los documentos, consulte Documentos en el manual del servidor.

Insertar un documento

Utilice el método insert_one() para insertar un solo documento en una colección.

Tras una inserción exitosa, el método devuelve una instancia InsertOneResult que contiene el _id del documento insertado.

Ejemplo

El siguiente ejemplo utiliza el método insert_one() para insertar un documento en la colección books:

let my_coll: Collection<Book> = client.database("db").collection("books");
let doc = Book { _id: 8, title: "Atonement".to_string(), author: "Ian McEwan".to_string() };
let insert_one_result = my_coll.insert_one(doc).await?;
println!("Inserted document with _id: {}", insert_one_result.inserted_id);

Inserted document with _id: 8

Tip

Bases de datos y colecciones inexistentes

Si una base de datos y una colección no existen cuando realiza una operación de escritura en ellas, el servidor las crea automáticamente.

Modificar el comportamiento de insert_one

Puede modificar el comportamiento del método insert_one() encadenando métodos del generador de opciones a insert_one(). Estos métodos del generador de opciones establecen los campos de la estructura InsertOneOptions.

Nota

Opciones de configuración

Puedes definir los campos InsertOneOptions encadenando los métodos de creación de opciones directamente a la llamada del método insert_one(). Si usas una versión anterior del driver, debes construir una instancia de InsertOneOptions encadenando los métodos de creación de opciones al método builder(). Luego, pasa tu instancia de opciones como parámetro a insert_one().

La siguiente tabla describe las opciones disponibles en InsertOneOptions:

Opción	Descripción
`bypass_document_validation`	If `true`, allows the driver to perform a write that violates document-level validation. To learn more about validation, see the guide on Schema Validation. Type: `bool` Default: `false`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual. Type: `WriteConcern`
`comment`	An arbitrary `Bson` value tied to the operation to trace it through the database profiler, `currentOp`, and logs. This option is available only when connecting to MongoDB Server versions 4.4 and later. Type: `Bson` Default: `None`

El siguiente código muestra cómo establecer el campo bypass_document_validation encadenando el método bypass_document_validation() al método insert_one():

let _result = my_coll.insert_one(doc)
    .bypass_document_validation(true)
    .await?;

Inserta varios documentos

Utiliza el método insert_many() para insertar varios documentos en una colección.

Tras una inserción exitosa, el método retorna una instancia InsertManyResult que contiene los valores _id de los documentos insertados.

Ejemplo

El siguiente ejemplo utiliza el método insert_many() para insertar varios documentos en la colección books:

let docs = vec![
    Book {
        _id: 5,
        title: "Cat's Cradle".to_string(),
        author: "Kurt Vonnegut Jr.".to_string()
    },
    Book {
        _id: 6,
        title: "In Memory of Memory".to_string(),
        author: "Maria Stepanova".to_string()
    },
    Book {
        _id: 7,
        title: "Pride and Prejudice".to_string(),
        author: "Jane Austen".to_string()
    }
];
let insert_many_result = my_coll.insert_many(docs).await?;
println!("Inserted documents with _ids:");
for (_key, value) in &insert_many_result.inserted_ids {
    println!("{:?}", value);
}

Inserted documents with _ids:
Int32(5)
Int32(6)
Int32(7)

Tip

Bases de datos y colecciones inexistentes

Si una base de datos y una colección no existen cuando realiza una operación de escritura en ellas, el servidor las crea automáticamente.

Modificar el comportamiento de insert_many

Puede modificar el comportamiento del método insert_many() encadenando métodos del generador de opciones a insert_many(). Estos métodos del generador de opciones establecen los campos de la estructura InsertManyOptions.

La siguiente tabla describe las opciones disponibles en InsertManyOptions:

Opción	Descripción
`bypass_document_validation`	If `true`, allows the driver to perform a write that violates document-level validation. To learn more about validation, see the guide on Schema Validation. Type: `bool` Default: `false`
`ordered`	If `true`, when any insert fails, the operation returns without inserting the remaining documents. If `false`, even if an insert fails, the operation continues with the remaining writes. To learn more about ordered inserts, see the Ordered Behavior Example section of this guide. Type: `bool` Default: `true`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual. Type: `WriteConcern`
`comment`	An arbitrary `Bson` value tied to the operation to trace it through the database profiler, `currentOp`, and logs. This option is available only when connecting to MongoDB Server versions 4.4 and later. Type: `Bson` Default: `None`

El siguiente código muestra cómo establecer el campo comment encadenando el método comment() al método insert_many():

let _result = my_coll.insert_many(docs)
    .comment(Some("hello world".into()))
    .await?;

Ejemplo de comportamiento ordenado

Supón que quieres insertar los siguientes documentos en la colección books:

{ "_id": 1, "title": "Where the Wild Things Are" }
{ "_id": 2, "title": "The Very Hungry Caterpillar" }
{ "_id": 1, "title": "Blueberries for Sal" }
{ "_id": 3, "title": "Goodnight Moon" }

Al intentar insertar estos documentos, el resultado depende del valor que se pase al método de creación de la opción ordered():

Si se pasa un valor de true (el valor por defecto), el driver lanza un BulkWriteError cuando intenta insertar el documento con el valor duplicado de _id. Sin embargo, el driver sigue introduciendo los documentos antes de que se produzca el error.
Si pasa un valor de false, el controlador aún arroja un BulkWriteError cuando intenta insertar el documento con el valor duplicado _id, pero inserta todos los demás documentos.

El siguiente código muestra cómo realizar una operación de escritura desordenada para insertar los documentos anteriores:

let docs = vec![
    Book { _id: 1, title: "Where the Wild Things Are".to_string(), author: "".to_string() },
    Book { _id: 2, title: "The Very Hungry Caterpillar".to_string(), author: "".to_string() },
    Book { _id: 1, title: "Blueberries for Sal".to_string(), author: "".to_string() },
    Book { _id: 3, title: "Goodnight Moon".to_string(), author: "".to_string() }
];
my_coll.insert_many(docs).ordered(false).await?;

Aunque esta operación da como resultado un BulkWriteError, aún puedes encontrar los documentos que no producen errores en tu colección:

{ "_id": 1, "title": "Where the Wild Things Are" }
{ "_id": 2, "title": "The Very Hungry Caterpillar" }
{ "_id": 3, "title": "Goodnight Moon" }

Información Adicional

Para ejemplos ejecutables de las operaciones de inserción, consulte los siguientes ejemplos de uso:

Documentación de la API

Para obtener más información sobre los métodos y tipos mencionados en esta guía, vea la siguiente documentación de la API:

Volver

Limitar los resultados

Modify