Tutorial

Consulte o código completo para este tutorial em tutorial.cpp.

Pré-requisitos

Uma instância do mongod em execução no localhost na porta 27017.
O driver mongocxx. ConsulteInstalação do .
As seguintes declarações na parte superior do seu arquivo de origem:

#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

O processo de instalação do driver mongocxx instalará um arquivo libmongocxx.pc para uso com pkg-config.

Para compilar um programa, execute o seguinte comando:

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

Se você não tiver pkg-config disponível, precisará definir os sinalizadores de inclusão e biblioteca manualmente na linha de comando ou em seu IDE. Por exemplo, se libmongoc e mongocxx estiverem instalados no /usr/local, a linha de compilação acima se expandirá para o seguinte:

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

Faça uma conexão

Importante

Antes de fazer qualquer conexão, você precisa criar uma e apenas uma instância de mongocxx::instance. Esta instância deve existir durante todo o seu programa.

Para se conectar a uma instância MongoDB em execução, use a classe mongocxx::instance.

Você deve especificar o host para se conectar usando uma instância mongocxx::uri contendo um URI MongoDB e passá-lo para o construtor mongocxx::client. Para obter detalhes sobre as opções de URI compatíveis, consulte a documentação da versão da libmongoc usada para compilar o driver C++ ou da versão mais recente da libmongoc.

O construtor mongocxx::uri padrão se conectará a um servidor em execução no localhost na porta 27017:

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

Isso é equivalente ao seguinte:

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

Acessar um banco de dados

Depois de conectar uma instância do MongoDB a um MongoDB deployment, use o database() método ou operator[] para obter uma instância do banco de dados mongocxx::.

Se o banco de dados solicitado não existir, o MongoDB o criará quando você armazenar os dados pela primeira vez.

O exemplo a seguir acessa o banco de dados do mydb :

auto db = client["mydb"];

Acessar uma coleção

Depois de ter uma instância do banco de dados mongocxx::, use o collection() método ou operator[] para obter uma instância do mongocxx::collection.

Se a coleção que você solicita não existir, o MongoDB a criará quando você armazenar os dados pela primeira vez.

Por exemplo, utilizando a instância db criada na seção anterior, a seguinte declaração acessa a coleção denominada test no banco de dados do mydb :

auto collection = db["test"];

Criar um documento

Para criar um document utilizando o driver C++, utilize uma das duas interfaces de construtor disponíveis:

Construtor de stream: bsoncxx::builder::stream
Um construtor de documentos usando os operadores de streaming que funciona bem para a construção literal de documentos.
Construtor básico: bsoncxx::builder::basic
Um construtor de documentos mais convencional que envolve a chamada de métodos em uma instância do construtor.

Este guia descreve brevemente o construtor básico.

Por exemplo, considere o seguinte JSON document:

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

Usando a interface básica do construtor, você pode construir este documento da seguinte maneira:

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 tipo de bsoncxx::document::value é um objeto somente leitura que possui sua própria memória. Para usá-lo, você deve obter um bsoncxx::document::view usando o método view():

auto doc_view = doc_value.view();

Você pode acessar campos dentro desta visualização de documento usando operator[], que retornará uma bsoncxx::document::element instance. Por exemplo, o seguinte extrairá o campo name cujo valor é uma string:

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"));

Se o valor no campo name não for uma string e você não incluir uma proteção de tipo, como visto no exemplo anterior, esse código lançará uma instância de bsoncxx::exceção.

Insira documentos

Inserir um documento

Para inserir um único documento na coleção, use o método de uma instância mongocxx::collection para insert_one() { "i": 0 }inserir:

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

insert_one_result é um mongocxx::result::insert_one opcional. Neste exemplo, espera-se que insert_one_result seja definido. O comportamento padrão para operações de gravação é aguardar uma resposta do servidor. Isso pode ser substituído definindo um mongocxx::write_concern.não reconhecido.

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

Se você não especificar um campo _id de nível superior no documento, o MongoDB adicionará automaticamente um campo _id ao documento inserido.

Você pode obter esse valor usando o método inserted_id() da instância mongocxx::result::insert_one retornada.

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

Insira vários documentos

Para inserir vários documentos na coleção, use o método de uma instância mongocxx::collection insert_many(), que usa uma lista de documentos a serem inseridos.

O exemplo a seguir insere os documentos { "i": 1 } e { "i": 2 }. Criar os documentos e adicionar à lista de documentos:

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

Para inserir estes documentos na collection, passe a lista de documentos para o método insert_many() .

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

Se você não especificar um campo _id de nível superior em cada documento, o MongoDB adicionará automaticamente um campo _id aos documentos inseridos.

Você pode obter este valor utilizando o método inserted_ids() da instância mongocxx::result::insert_many retornada.

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);

Consulte a coleção

Para fazer query da coleção, use os métodos find() e find_one() da coleção.

find() retornará uma instância de mongocxx::cursor, enquanto find_one() retornará uma instância de std::optional< bsoncxx::document::value >. Para obter mais informações, consulte bsoncxx::documento::value.

Você pode chamar qualquer método com um documento vazio para consultar todos os documentos em uma coleção ou passar um filtro para consultar documentos que correspondam aos critérios do filtro.

Encontrar um único documento em uma coleção

Para retornar um único documento na coleção, use o método find_one() sem nenhum parâmetro.

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

Encontre todos os documentos em uma coleção

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

Imprimir todos os documentos de uma coleção

A função bsoncxx::to_json converte um documento BSON em uma string 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;

O exemplo acima imprime uma saída semelhante ao seguinte:

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

O elemento _id foi adicionado automaticamente pelo MongoDB ao seu documento e seu valor será diferente do mostrado. O MongoDB reserva os nomes de campo que começam com um sublinhado (_) e o cifrão ($) para uso interno.

Especificar um filtro de query

Obtenha um único documento que corresponda a um filtro

Para localizar o primeiro documento onde o campo i tem o valor 0, passe o documento {"i": 0} para especificar a condição de igualdade:

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
}

Obter todos os documentos que correspondem a um filtro

O exemplo a seguir obtém todos os documentos onde 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);
}

Atualize documentos

Para atualizar documentos em uma collection, você pode usar os métodos update_one() e update_many() da collection.

Os métodos de atualização retornam uma instância do std::optional< mongocxx::result::update >, que fornece informações sobre a operação, incluindo o número de documentos modificados pela atualização. Para obter mais informações, consulte mongocxx::result::update.

Atualizar um único documento

Para atualizar no máximo um documento, use o método update_one() .

O exemplo a seguir atualiza o primeiro documento que corresponde ao filtro { "i": 0 } e define o valor de foo como 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);

Atualizar vários documentos

Para atualizar todos os documentos correspondentes a um filtro, use o método update_many() .

O exemplo a seguir define o valor de foo como buzz , em que i é maior 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);

Exclua documentos

Para excluir documentos de uma collection, você pode usar os métodos delete_one() e delete_many() de uma collection.

Os métodos de exclusão retornam uma instância de std::optional< mongocxx::result::delete >, que contém o número de documentos excluídos. Para obter mais informações, consulte mongocxx::result::delete.

Excluir um único documento

Para excluir no máximo um único documento que corresponda a um filtro, use o método delete_one() .

Por exemplo, para excluir um documento que corresponda ao 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);

Excluir todos os documentos que correspondem a um filtro

Para excluir todos os documentos correspondentes a um filtro, use o método delete_many() de uma collection.

O exemplo a seguir exclui todos os documentos em que i é maior 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);

Crie índices

Para criar um índice em um campo ou conjunto de campos, passe um documento de especificação de índice para o método create_index() de uma instância mongocxx::collection. Um documento de especificação da chave de índice contém os campos a serem indexados e o tipo de índice para cada campo:

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

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

O exemplo seguinte cria um índice ascendente no campo i :

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

Voltar

Criptografia do lado do cliente

Segurança de thread