/ /

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, puede aprender cómo insertar documentos en una colección MongoDB.

Para poder buscar, actualizar y eliminar documentos en MongoDB, es necesario insertarlos. Puede insertarlos mediante 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 _id campo que contiene cada documento
Insertar un documento describe cómo usar el controlador 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 API para los tipos y métodos mencionados en esta guía.

El campo _id

En MongoDB, cada documento debe contener un campo único _id. MongoDB te permite gestionar este campo de las siguientes maneras:

Administre este campo usted mismo, asegurándose de que cada valor _id que establezca sea único.
Permita que el controlador genere automáticamente valores ObjectId únicos. El controlador genera un valor ObjectId único para cada documento si no se especifica un valor para el campo _id al realizar una inserción.

A menos que proporcione garantías sólidas de unicidad, le recomendamos que permita que el controlador genere automáticamente valores _id para sus documentos.

Importante

Duplicate _id Values

Si intenta realizar una operación de escritura que incluye valores _id duplicados, los valores duplicados violan las restricciones de índice único y provocan que la operación de escritura falle.

Para obtener más información sobre el _id campo, 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, None).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() construyendo y pasando una estructura InsertOneOptions.

Nota

Opciones de instanciación

El controlador de Rust implementa el patrón de diseño Builder para la creación de diversos tipos, incluyendo InsertOneOptions. Puedes usar el método builder() de cada tipo para construir una instancia de opciones encadenando las funciones del constructor de opciones una a una.

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 construir una instancia InsertOneOptions:

let _opts = InsertOneOptions::builder()
    .bypass_document_validation(true)
    .build();

Inserta varios documentos

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

Tras una inserción exitosa, el método devuelve 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, None).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

Puedes modificar el comportamiento del método insert_many() construyendo y pasando un struct 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 construir una instancia InsertManyOptions:

let _opts = InsertManyOptions::builder()
    .comment(Some("hello world".into()))
    .build();

Ejemplo de comportamiento ordenado

Supongamos que desea 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" }

Cuando intenta insertar estos documentos, el resultado depende del valor de la opción ordered en su InsertManyOptions:

Si ordered es true (valor predeterminado), el controlador genera un error BulkWriteError al intentar insertar el documento con el valor duplicado _id. Sin embargo, el controlador inserta los documentos antes de que se produzca el error.
Si se configura ordered en false, el controlador aún lanza 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: 4, title: "Blueberries for Sal".to_string(), author: "".to_string() },
    Book { _id: 3, title: "Goodnight Moon".to_string(), author: "".to_string() }
];
let opts = InsertManyOptions::builder().ordered(false).build();
my_coll.insert_many(docs, opts).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, consulte la siguiente documentación de API:

Volver

Limitar los resultados

Modify