/ /

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 prefieres establecer valores personalizados, puedes asignar los valores en los campos _id de los documentos pasados a tu 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.

Después de una inserción exitosa, el método retorna una instancia de 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 se realiza una operación de guardar en ellas, el servidor las crea automáticamente.

Modifique 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 driver de Rust implementa el patrón de diseño Builder para la creación de muchos tipos diferentes, incluido InsertOneOptions. Puedes usar el método builder() de cada tipo para construir una instancia de opciones encadenando funciones constructoras de opciones una tras otra.

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 de InsertOneOptions:

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

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, 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 se realiza una operación de guardar 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 de InsertManyOptions:

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

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" }

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

Si ordered es true (el valor por defecto), el driver lanza un BulkWriteError cuando intenta insertar el documento con el valor _id duplicado. Sin embargo, el driver aún inserta los documentos antes de que ocurra 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, vea la siguiente documentación de la API:

Volver

Limitar los resultados

Modify