Tutorial

Vea el código completo de este tutorial en tutorial.cpp.

Requisitos previos

Una instancia de mongod ejecutándose en el host local en el 27017 puerto.
El controlador mongocxx. Ver Instalación.
Las siguientes declaraciones en la parte superior de su archivo fuente:

#include <cstdint>
#include <iostream>
#include <vector>
#include <bsoncxx/builder/basic/document.hpp>
#include <bsoncxx/json.hpp>
#include <mongocxx/client.hpp>
#include <mongocxx/instance.hpp>
#include <mongocxx/stdx.hpp>
#include <mongocxx/uri.hpp>
using bsoncxx::builder::basic::kvp;
using bsoncxx::builder::basic::make_array;
using bsoncxx::builder::basic::make_document;

Compilando

El proceso de instalación del controlador mongocxx instalará un libmongocxx.pc archivo para usar con pkg-config.

Para compilar un programa, ejecute el siguiente comando:

c++ --std=c++11 <input>.cpp $(pkg-config --cflags --libs libmongocxx)

Si no tiene pkg-config disponible, deberá configurar manualmente los indicadores de inclusión y de biblioteca en la línea de comandos o en su IDE. Por ejemplo, si libmongoc y mongocxx están instalados en /usr/local, la línea de compilación anterior se expande a esto:

c++ --std=c++11 <input>.cpp
-I/usr/local/include/mongocxx/v_noabi \
-I/usr/local/include/bsoncxx/v_noabi \
-L/usr/local/lib -lmongocxx -lbsoncxx

Establezca una conexión

Importante

Antes de realizar cualquier conexión, debe crear una única instancia de mongocxx::instance. Esta instancia debe existir durante todo el programa.

Para conectarse a una instancia de MongoDB en ejecución, utilice la clase mongocxx::instance.

Debe especificar el host al que se conectará mediante una instancia mongocxx::uri que contenga una URI de MongoDB y pasarla al mongocxx::client constructor. Para obtener más información sobre las opciones de URI compatibles, consulte la documentación de la versión de libmongoc utilizada para compilar el controlador de C++ o la versión más reciente de libmongoc.

El constructor predeterminado mongocxx::uri se conectará a un servidor que se ejecuta en localhost en el puerto 27017:

mongocxx::instance instance{}; // This should be done only once.
mongocxx::client client{mongocxx::uri{}};

Esto es equivalente a lo siguiente:

mongocxx::instance instance{}; // This should be done only once.
mongocxx::uri uri("mongodb://localhost:27017");
mongocxx::client client(uri);

Acceder a una base de datos

Una vez que tenga una instancia de mongocxx::instance conectada a una implementación de MongoDB, utilice el database() método o operator[] para obtener una instancia de mongocxx::database.

Si la base de datos que solicita no existe, MongoDB la crea cuando almacena los datos por primera vez.

El siguiente ejemplo accede a la base de datos mydb:

auto db = client["mydb"];

Acceder a una colección

Una vez que tenga una instancia de mongocxx::database, utilice el collection() método o operator[] para obtener una instancia de mongocxx::collection.

Si la colección que solicita no existe, MongoDB la crea cuando almacena datos por primera vez.

Por ejemplo, utilizando la instancia db creada en la sección anterior, la siguiente declaración accede a la colección llamada test en la base de datos mydb:

auto collection = db["test"];

Crear un documento

Para crear un document usando el controlador C++, utilice una de las dos interfaces de generación disponibles:

Constructor de transmisiones: bsoncxx::builder::stream
Un generador de documentos que utiliza operadores de transmisión y que funciona bien para la construcción de documentos literales.
Constructor básico: bsoncxx::builder::basic
Un generador de documentos más convencional que implica llamar a métodos en una instancia del generador.

Esta guía solo describe brevemente el constructor básico.

Por ejemplo, considere el siguiente documento JSON:

{
  "name" : "MongoDB",
  "type" : "database",
  "count" : 1,
  "versions": [ "v6.0", "v5.0", "v4.4", "v4.2", "v4.0", "v3.6" ],
  "info" : {
             "x" : 203,
             "y" : 102
           }
}

Utilizando la interfaz básica del generador, puedes construir este documento de la siguiente manera:

auto doc_value = make_document(
     kvp("name", "MongoDB"),
     kvp("type", "database"),
     kvp("count", 1),
     kvp("versions", make_array("v6.0", "v5.0", "v4.4", "v4.2", "v4.0", "v3.6")),
     kvp("info", make_document(kvp("x", 203), kvp("y", 102)))
 );

Este bsoncxx::document::value tipo es un objeto de solo lectura con memoria propia. Para usarlo, debe obtener un objeto bsoncxx::document::view mediante el view() método:

auto doc_view = doc_value.view();

Puede acceder a los campos de esta vista de documento operator[] mediante, lo que devolverá una instancia de bsoncxx::document::element. Por ejemplo, la siguiente instrucción extraerá el name campo cuyo valor es una cadena:

auto element = doc_view["name"];
assert(element.type() == bsoncxx::type::k_string);
auto name = element.get_string().value; // For C++ driver version < 3.7.0, use get_utf8()
assert(0 == name.compare("MongoDB"));

Si el valor en el campo de nombre no es una cadena y no incluye una protección de tipo como se ve en el ejemplo anterior, este código generará una instancia de bsoncxx::exception.

Insertar documentos

Inserta un documento

Para insertar un solo documento en la colección, utilice el insert_one() método de una instancia de mongocxx::collection para { "i": 0 } insertar:

auto insert_one_result = collection.insert_one(make_document(kvp("i", 0)));

insert_one_result Es un mongocxx::result::insert_one opcional. En este ejemplo, insert_one_result se espera que esté configurado. El comportamiento predeterminado para las operaciones de escritura es esperar una respuesta del servidor. Esto se puede anular configurando un mongocxx::write_concern no confirmado.

assert(insert_one_result);  // Acknowledged writes return results.

Si no especifica un campo de nivel superior _id en el documento, MongoDB agrega automáticamente un campo _id al documento insertado.

Puede obtener este valor utilizando el inserted_id() método de la instancia mongocxx::result::insert_one devuelta.

auto doc_id = insert_one_result->inserted_id();
assert(doc_id.type() == bsoncxx::type::k_oid);

Inserta varios documentos

Para insertar varios documentos en la colección, utilice el método de una instancia de mongocxx::collection, insert_many() que toma una lista de documentos para insertar.

El siguiente ejemplo inserta los documentos { "i": 1 } y { "i": 2 }. Cree los documentos y añádalos a la lista:

std::vector<bsoncxx::document::value> documents;
documents.push_back(make_document(kvp("i", 1)));
documents.push_back(make_document(kvp("i", 2)));

Para insertar estos documentos en la colección, pase la lista de documentos al método insert_many().

auto insert_many_result = collection.insert_many(documents);
assert(insert_many_result);  // Acknowledged writes return results.

Si no especifica un campo de nivel superior _id en cada documento, MongoDB agrega automáticamente un campo _id a los documentos insertados.

Puede obtener este valor utilizando el inserted_ids() método de la instancia mongocxx::result::insert_many devuelta.

auto doc0_id = insert_many_result->inserted_ids().at(0);
auto doc1_id = insert_many_result->inserted_ids().at(1);
assert(doc0_id.type() == bsoncxx::type::k_oid);
assert(doc1_id.type() == bsoncxx::type::k_oid);

Consulta de la colección

Para consultar la colección, utilice los métodos find() y find_one() de la colección.

find() Devolverá una instancia de mongocxx::cursor, mientras que find_one() devolverá una instancia std::optional< bsoncxx::document::value > de. Para más información, consulte bsoncxx::document::value.

Puede llamar a cualquiera de los métodos con un documento vacío para consultar todos los documentos de una colección o pasar un filtro para consultar documentos que coincidan con los criterios del filtro.

Buscar un solo documento en una colección

Para devolver un solo documento en la colección, utilice el método find_one() sin ningún parámetro.

auto find_one_result = collection.find_one({});
if (find_one_result) {
    // Do something with *find_one_result
}
assert(find_one_result);

Encuentre todos los documentos en una colección

auto cursor_all = collection.find({});
for (auto doc : cursor_all) {
    // Do something with doc
    assert(doc["_id"].type() == bsoncxx::type::k_oid);
}

Imprimir todos los documentos de una colección

La función bsoncxx::to_json convierte un documento BSON en una cadena JSON.

auto cursor_all = collection.find({});
std::cout << "collection " << collection.name()
          << " contains these documents:" << std::endl;
for (auto doc : cursor_all) {
    std::cout << bsoncxx::to_json(doc, bsoncxx::ExtendedJsonMode::k_relaxed) << std::endl;
}
std::cout << std::endl;

El ejemplo anterior imprime un resultado similar al siguiente:

collection test contains these documents:
{ "_id" : { "$oid" : "6409edb48c37f371c70f03a1" }, "i" : 0 }
{ "_id" : { "$oid" : "6409edb48c37f371c70f03a2" }, "i" : 1 }
{ "_id" : { "$oid" : "6409edb48c37f371c70f03a3" }, "i" : 2 }

MongoDB ha añadido automáticamente el elemento _id a su documento y su valor será diferente al mostrado. MongoDB reserva los nombres de campo que empiezan con un guion bajo (_) y el signo de dólar ($) para uso interno.

Especificar un filtro de consulta

Obtener un solo documento que coincida con un filtro

Para encontrar el primer documento donde el campo i tiene el valor 0, pase el documento {"i": 0} para especificar la condición de igualdad:

auto find_one_filtered_result = collection.find_one(make_document(kvp("i", 0)));
if (find_one_filtered_result) {
    // Do something with *find_one_filtered_result
}

Obtener todos los documentos que coinciden con un filtro

El siguiente ejemplo obtiene todos los documentos donde 0 < "i" <= 2:

auto cursor_filtered =
    collection.find(make_document(kvp("i", make_document(kvp("$gt", 0), kvp("$lte", 2)))));
for (auto doc : cursor_filtered) {
    // Do something with doc
    assert(doc["_id"].type() == bsoncxx::type::k_oid);
}

Update Documents

Para actualizar documentos en una colección, puede utilizar los métodos update_one() y update_many() de la colección.

Los métodos de actualización devuelven una instancia std::optional< mongocxx::result::update > de, que proporciona información sobre la operación, incluido el número de documentos modificados por la actualización. Para más información, consulte mongocxx::result::update.

Actualiza un solo documento

Para actualizar como máximo un documento, utilice el método update_one().

El siguiente ejemplo actualiza el primer documento que coincide con el filtro { "i": 0 } y establece el valor de foo en bar:

auto update_one_result =
    collection.update_one(make_document(kvp("i", 0)),
                          make_document(kvp("$set", make_document(kvp("foo", "bar")))));
assert(update_one_result);  // Acknowledged writes return results.
assert(update_one_result->modified_count() == 1);

Actualiza varios documentos

Para actualizar todos los documentos que coinciden con un filtro, utilice el método update_many().

El siguiente ejemplo establece el valor de foo en buzz, donde i es mayor que 0:

auto update_many_result =
    collection.update_many(make_document(kvp("i", make_document(kvp("$gt", 0)))),
                            make_document(kvp("$set", make_document(kvp("foo", "buzz")))));
assert(update_many_result);  // Acknowledged writes return results.
assert(update_many_result->modified_count() == 2);

Delete Documents

Para eliminar documentos de una colección, puede utilizar los métodos delete_one() y delete_many() de una colección.

Los métodos de eliminación devuelven una instancia std::optional< mongocxx::result::delete > de, que contiene el número de documentos eliminados. Para más información, consulte mongocxx::result::delete.

Borrar un único documento

Para eliminar como máximo un solo documento que coincida con un filtro, utilice el método delete_one().

Por ejemplo, para eliminar un documento que coincide con el filtro { "i": 0 }:

auto delete_one_result = collection.delete_one(make_document(kvp("i", 0)));
assert(delete_one_result);  // Acknowledged writes return results.
assert(delete_one_result->deleted_count() == 1);

Eliminar todos los documentos que coinciden con un filtro

Para eliminar todos los documentos que coincidan con un filtro, utilice el método delete_many() de una colección.

El siguiente ejemplo elimina todos los documentos donde i es mayor que 0:

auto delete_many_result =
    collection.delete_many(make_document(kvp("i", make_document(kvp("$gt", 0)))));
assert(delete_many_result);  // Acknowledged writes return results.
assert(delete_many_result->deleted_count() == 2);

Cree índices

Para crear un índice en un campo o conjunto de campos, pase un documento de especificación de índice al create_index() método de una instancia de mongocxx::collection. Un documento de especificación de clave de índice contiene los campos a indexar y el tipo de índice de cada campo:

{ "index1": "<type>", "index2": "<type>" }

Para un tipo de índice ascendente, especifica 1 para <type>.
Para un tipo de índice descendente, especifique -1 para <type>.

El siguiente ejemplo crea un índice ascendente en el campo i:

auto index_specification = make_document(kvp("i", 1));
collection.create_index(std::move(index_specification));

Volver

Cifrado del lado del cliente

Seguridad de hilos