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 agrega uno o más documentos a una colección de MongoDB. Se puede realizar una operación de inserción utilizando el método insert_one() para insertar un solo documento o el método insert_many() para insertar uno o más documentos.

Datos de muestra

Los ejemplos en esta guía utilizan la colección sample_restaurants.restaurants de los conjuntos de datos de muestra de Atlas. Para acceder a esta colección desde tu aplicación C++, instancia un client que se conecte a un clúster de Atlas y asigna los siguientes valores a tus 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`	Si se establece en `true`, permite que la operación de guardar se excluya de la validación a nivel de documento. Por defecto, `false`. Tipo: `bool`
`write_concern`	Establece el nivel de confirmación de escritura (write concern) para la operación. Por defecto, el nivel de confirmación de escritura (write concern) del namespace. Tipo: `mongocxx::write_concern`
`ordered`	Si se establece en `true`, la operación deja de insertar documentos cuando falla una inserción. Si `false`, la operación continúa insertando los documentos restantes cuando falla una inserción. El `true` es por defecto. Tipo: `bool`
`comment`	Un comentario para adjuntar a la operación. Para obtener más información, consulte la guía insertar campos de comando en el manual de MongoDB Server. Tipo: `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