/ /

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 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 intenta insertar documentos que incluyen valores _id duplicados, estos valores 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).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 los métodos del generador de opciones a insert_one(). Estos métodos del generador de opciones establecen InsertOneOptions campos de estructura.

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

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).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 los métodos del generador de opciones a insert_many(). Estos métodos del generador de opciones establecen InsertManyOptions campos de estructura.

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

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 pasado al método de creación de la opción ordered():

Si se pasa un valor de true (el 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 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, consulte la siguiente documentación de API:

Volver

Limitar los resultados

Modify