Getting Started with the C++ Driver

Installing the Driver Library and Headers¶

A good source for general information about setting up a MongoDB development environment on various operating systems is the Windows快捷链接和参考中心 page.

The normal database distribution used to include the C++ driver, but there were many problems with library version mismatches so now you have to build from source. You can either get the full source code for the database and just build the C++ driver or download the driver separately and build it.

Unix¶

For Unix, the MongoDB driver library is libmongoclient.a. Run scons --help to see all building options.

scons --full install

scons --prefix /opt/mongo --full install.

Windows¶

For more information, see the Windows快捷链接和参考中心.

Compiling¶

The C++ driver utilizes several Boost libraries. Be sure they are in your include and lib paths. You can usually install them from your OS’s package manager if you don’t already have them. We recommend using Boost 1.49.

Writing Client Code¶

#include <cstdlib>
#include <iostream>
#include "mongo/client/dbclient.h"

void run() {
  mongo::DBClientConnection c;
  c.connect("localhost");
}

int main() {
  try {
    run();
    std::cout << "connected ok" << std::endl;
  } catch( const mongo::DBException &e ) {
    std::cout << "caught " << e.what() << std::endl;
  }
  return EXIT_SUCCESS;
}

$ g++ tutorial.cpp -pthread -lmongoclient -lboost_thread-mt -lboost_filesystem -lboost_program_options -lboost_system -o tutorial
$ ./tutorial
connected ok

BSONObjBuilder b;
b.append("name", "Joe");
b.append("age", 33);
BSONObj p = b.obj();

BSONObj p = BSONObjBuilder().append("name", "Joe").append("age", 33).obj();

BSONObjBuilder b;
b << "name" << "Joe" << "age" << 33;
BSONObj p = b.obj();

BSONObj p = BSON( "name" << "Joe" << "age" << 33 );

BSONObj p = BSON( GENOID << "name" << "Joe" << "age" << 33 );
// result is: { _id : ..., name : "Joe", age : 33 }

BSONObj p =
  BSONObjBuilder().genOID().append("name","Joe").append("age",33).obj();

Inserting¶

We now save our person object in a persons collection in the database:

c.insert("tutorial.persons", p);

The first parameter to insert is the namespace. tutorial is the database and persons is the collection name.

Querying¶

Let’s now fetch all objects from the persons collection, and display them. We’ll also show here how to use count().

cout << "count:" << c.count("tutorial.persons") << endl;

auto_ptr<DBClientCursor> cursor =
 c.query("tutorial.persons", BSONObj());
while (cursor->more())
   cout << cursor->next().toString() << endl;

BSONObj() is an empty BSON object – it represents {} which indicates an empty query pattern (an empty query is a query for all objects).

We use BSONObj::toString() above to print out information about each object retrieved. BSONObj::toString is a diagnostic function which prints an abbreviated JSON string representation of the object. For full JSON output, use BSONObj::jsonString.

Let’s now write a function which prints out the name (only) of all persons in the collection whose age is a given value:

void printIfAge(DBClientConnection& c, int age) {
  auto_ptr<DBClientCursor> cursor =
    c.query("tutorial.persons", QUERY("age" << age));
  while (cursor->more()) {
    BSONObj p = cursor->next();
    cout << p.getStringField("name") << endl;
  }
}

getStringField() is a helper that assumes the name field is of type string. To manipulate an element in a more generic fashion we can retrieve the particular BSONElement from the enclosing object:

BSONElement name = p["name"];
// or:
//BSONElement name = p.getField("name");

See the api docs, and jsobj.h, for more information.

Our query above, written as JSON, is of the form

{ age : <agevalue> }

Queries are BSON objects of a particular format – in fact, we could have used the BSON() macro above instead of QUERY(). See class Query in dbclient.h for more information on Query objects, and the Sorting section below.

In the mongo shell (which uses javascript), we could invoke:

use tutorial;
db.persons.find({age : 33});

Indexing¶

Let’s suppose we want to have an index on age so that our queries are fast. We would use:

c.ensureIndex("tutorial.persons", fromjson("{age:1}"));

The ensureIndex method checks if the index exists; if it does not, it is created. ensureIndex is intelligent and does not repeat transmissions to the server; thus it is safe to call it many times in your code, for example, adjacent to every insert operation.

In the above example we use a new function, fromjson. fromjson converts a JSON string to a BSONObj. This is sometimes a convenient way to specify BSON. Alternatively, we could have written:

c.ensureIndex("tutorial.persons", BSON( "age" << 1 ));

Sorting¶

Let’s now make the results from printIfAge sorted alphabetically by name. To do this, we change the query statement from:

auto_ptr<DBClientCursor> cursor = c.query("tutorial.persons", QUERY("age" << age));

to

auto_ptr<DBClientCursor> cursor = c.query("tutorial.persons", QUERY("age" << age ).sort("name"));

Here we have used Query::sort() to add a modifier to our query expression for sorting.

Updating¶

Use the update() method to perform a database update . For example the following update in the mongo shell:

> use tutorial
> db.persons.update( { name : 'Joe', age : 33 },
...                  { $inc : { visits : 1 } } )

is equivalent to the following C++ code:

db.update("tutorial.persons",
           BSON("name" << "Joe" << "age" << 33),
           BSON("$inc" << BSON( "visits" << 1)));

Example¶

A simple example illustrating usage of BSON arrays and the $nin operator is available here.

Further Reading¶

This overview just touches on the basics of using MongoDB from C++. There are many more capabilities. For further exploration:

• See the language-independent MongoDB Manual;
• Experiment with the mongo shell;
• Review the doxygen API docs;
• See connecting pooling information in the API docs;
• See GridFS file storage information in the API docs;
• See the HOWTO pages under the C++ Language Center
• Consider getting involved to make the product (either C++ driver, tools, or the database itself) better!