/ /

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`	Si `true`, permite que el driver realice una operación de guardar que infrinja la validación a nivel de documento. Para obtener más información sobre la validación, consulte la guía sobre validación de esquema. Tipo: `bool` Por defecto: `false`
`write_concern`	El nivel de confirmación de escritura (write concern) para la operación. Si no establece esta opción, la operación hereda el nivel de confirmación de escritura (write concern) establecido para la colección. Para obtener más información sobre el nivel de confirmación de escritura (write concern), consulta Nivel de confirmación de escritura (write concern) en el manual del servidor. Tipo: `WriteConcern`
`comment`	Un valor `Bson` arbitrario vinculado a la operación para rastrearlo a través del perfilador de base de datos, `currentOp` y los registros. Esta opción solo está disponible cuando se conecta a MongoDB Server versiones 4.4 y posteriores. Tipo: `Bson` Por defecto: `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`	Si `true`, permite que el driver realice una operación de guardar que infrinja la validación a nivel de documento. Para obtener más información sobre la validación, consulte la guía sobre validación de esquema. Tipo: `bool` Por defecto: `false`
`ordered`	Si `true`, cuando falla cualquier inserción, la operación regresa sin insertar los documentos restantes. Si `false`, incluso si falla una inserción, la operación continúa con los guardar restantes. Para aprender más sobre las inserciones ordenadas, consulte la sección Ejemplo de comportamiento ordenado de esta guía. Tipo: `bool` Por defecto: `true`
`write_concern`	El nivel de confirmación de escritura (write concern) para la operación. Si no establece esta opción, la operación hereda el nivel de confirmación de escritura (write concern) establecido para la colección. Para obtener más información sobre el nivel de confirmación de escritura (write concern), consulta Nivel de confirmación de escritura (write concern) en el manual del servidor. Tipo: `WriteConcern`
`comment`	Un valor `Bson` arbitrario vinculado a la operación para rastrearlo a través del perfilador de base de datos, `currentOp` y los registros. Esta opción solo está disponible cuando se conecta a MongoDB Server versiones 4.4 y posteriores. Tipo: `Bson` Por defecto: `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