Insertar documentos

Overview

En esta guía, puedes aprender a usar el controlador de C++ para añadir documentos a una colección de MongoDB realizando operaciones de inserción.

Una operación de inserción inserta uno o más documentos en una colección de MongoDB. Puede realizar una operación de inserción utilizando la insert_one() método para insertar un solo documento o el método insert_many() para insertar uno o varios documentos.

Datos de muestra

Los ejemplos en esta guía utilizan la colección sample_restaurants.restaurants de la conjuntos de datos de muestra de Atlas. Para acceder a esta colección desde su aplicación C++, instancie un client que se conecte a un clúster de Atlas y asigne los siguientes valores a sus variables db y collection:

auto db = client["sample_restaurants"];
auto collection = db["restaurants"];

Para aprender cómo crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de ejemplo, consulta la guía MongoDB Get Started.

El campo `_id`

En una colección de MongoDB, cada documento debe contener un campo _id con un valor de campo único.

MongoDB permite gestionar este campo de dos formas:

Uno mismo puede configurar este campo para cada documento, asegurando que el valor de cada campo _id sea único.
Puede permitir que el controlador genere automáticamente valores únicos de ObjectId para cada documento _id.

A menos que pueda garantizar la exclusividad, recomendamos dejar que el controlador genere automáticamente los valores de _id.

Nota

Los valores duplicados _id vulneran las restricciones de índice único, lo cual provoca que el controlador devuelva un error mongocxx::bulk_write_exception.

Para obtener más información sobre el campo _id, consulta la guía Índices únicos en el manual del MongoDB Server.

Para obtener más información sobre la estructura y las reglas de los documentos, consulta la guía de Documentos en el manual de MongoDB Server.

Inserta un documento

Para añadir un único documento a una colección de MongoDB, llama al método insert_one() y pasa el documento que quieras añadir.

El siguiente ejemplo inserta un documento en la colección restaurants:

auto result = collection.insert_one(make_document(kvp("name", "Mongo's Burgers")));

Inserta varios documentos

Para agregar varios documentos a una colección de MongoDB, llama al método insert_many() y pasa un vector que almacene los documentos que deseas agregar.

El siguiente ejemplo inserta dos documentos en la colección restaurants:

std::vector<bsoncxx::document::value> restaurants;
restaurants.push_back(make_document(kvp("name", "Mongo's Burgers")));
restaurants.push_back(make_document(kvp("name", "Mongo's Pizza")));
auto result = collection.insert_many(restaurants);

Modificar el comportamiento de inserción

Puedes modificar el comportamiento de los métodos insert_one() y insert_many() pasando una instancia de la clase mongocxx::options::insert como parámetro opcional. La siguiente tabla describe los campos que puede establecer en una instancia de mongocxx::options::insert:

Campo	Descripción
`bypass_document_validation`	If set to `true`, allows the write to opt out of document-level validation. Defaults to `false`. Type: `bool`
`write_concern`	Sets the write concern for the operation. Defaults to the write concern of the namespace. Type: `mongocxx::write_concern`
`ordered`	If set to `true`, the operation stops inserting documents when one insert fails. If `false`, the operation continues to insert the remaining documents when one insert fails. Defaults to `true`. Type: `bool`
`comment`	A comment to attach to the operation. For more information, see the insert command fields guide in the MongoDB Server manual. Type: `bsoncxx::types::bson_value::view_or_value`

Ejemplo

El siguiente código utiliza el método insert_many() para insertar tres nuevos documentos en una colección. Debido a que el campo bypass_document_validation está configurado en true en una instancia mongocxx::options::insert, esta operación de inserción omite la validación a nivel de documento:

std::vector<bsoncxx::document::value> docs;
docs.push_back(make_document(kvp("name", "Mongo's Burgers")));
docs.push_back(make_document(kvp("name", "Mongo's Pizza")));
docs.push_back(make_document(kvp("name", "Mongo's Tacos")));
mongocxx::options::insert opts;
opts.bypass_document_validation(true);
auto result = collection.insert_many(docs, opts);

Documentación de la API

Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API:

Volver

Bases de datos y colecciones

Especifica un query