Working with BSON

Overview

In this guide, you can learn how to use the C++ driver to store and interact with BSON data by using the bsoncxx library.

BSON Data Format

MongoDB uses the BSON, or Binary JSON, data format to store documents and make remote procedure calls. This data format includes all JSON data structure types and supports additional types, including dates, different-sized integers, ObjectId values, and binary data. For a complete list of supported types, see the BSON Types page in the MongoDB Server manual.

Note

Avoid adding duplicate keys to BSON documents. Although the BSON specification allows duplicate keys, they can cause unexpected behavior in MongoDB Server.

BSON Values and Views

Many C++ driver methods accept a BSON document as an argument. The bsoncxx library provides two data types that you can use to represent a BSON document: bsoncxx::document::value and bsoncxx:document::view.

A document::value object represents a BSON document that owns its underlying buffer of data. When you pass a document::value object to a C++ driver method, the method receives a copy of the BSON document data. When a document::value object goes out of scope, its underlying buffer is freed.

Tip

You can convert builder types to document::value types by calling helper methods on the builder. To learn more about the builder types, see the Build a BSON Document section in this guide.

A document::view object provides a non-owning view into a document::value. This type allows you to read and interact with the contents of a BSON document without owning the document's underlying data. When you pass a document::view object to a C++ driver method, the method can use data from the underlying document without copying it. You can create a view by calling the view() method on a document::value object.

Tip

To avoid excess copying, we recommend passing documents by view if possible.

Some C++ driver methods accept arguments of type document::view_or_value. You can pass either a document::view or document::value object to these methods. You must pass document::value arguments by rvalue reference to transfer ownership of the document to the method.

Important

A document::view must not outlive any document::value that it references. If a document::view uses a document::value after its underlying buffer is freed, the view will contain a dangling pointer. Accessing a dangling pointer can cause application crashes, corrupted data, and other unpredictable behavior.

Build a BSON Document

This section shows how to use the following interfaces to create a BSON document:

List Builder
Basic Builder
Stream Builder

List Builder

The builder::list interface is a JSON-like builder for constructing documents and arrays. To create a BSON document by using the list builder, construct a bsoncxx::builder::list object, passing a list of key-value pairs to the constructor. The list builder creates a BSON document if the key-value list fulfills the following requirements:

The list has an even number of elements.
Each key is a string type and each value is a bson_value::value type or is implicitly convertible to one.

If the preceding requirements are not met, the list builder creates an array.

This example uses the list builder to perform the following actions:

Build a document
Build an array
Convert the builder document to a bsoncxx::document::value object

bsoncxx::builder::list course_doc = { "title", "Poetry",
                                      "department", "English" };
bsoncxx::builder::list courses_array = { "Poetry", "Literature",
                                         "Creative Writing" };
bsoncxx::document::value course{course_doc.view().get_document().value};

Basic Builder

The builder::basic interface is a builder-style interface for constructing a BSON document. To create a BSON document by using the basic builder, specify your document's data in a list of key-value pair objects. You can create these key-value pair objects by passing a key and value to the builder::basic::kvp() method. The key must be a string type, and the value must be a bson_value::value type or implicitly convertible to one.

You can use the basic builder's make_document() method to create a document and convert it to a bsoncxx::document::value in a single statement, as shown in the following code:

using bsoncxx::builder::basic::make_document; 
using bsoncxx::builder::basic::kvp;
bsoncxx::document::value course = make_document(
    kvp("title","Poetry"),
    kvp("department","English"));

Alternatively, you can create a BSON document across multiple statements by appending key-value pairs to a basic builder object. This example uses the basic builder to perform the following actions:

Initialize a builder::basic::document object
Store data in the document by using the append() method
Convert the builder document to a bsoncxx::document::value object

using bsoncxx::builder::basic::kvp;
auto course_builder = bsoncxx::builder::basic::document{};
course_builder.append(kvp("title", "Literature"),
                      kvp("department", "English"));
                      
bsoncxx::document::value course{course_builder.extract()};

Stream Builder

Important

We recommend using the basic builder instead of the stream builder.

To properly append each new value, a stream builder must keep track of the state of the current document. You cannot reuse the initial stream builder after this state changes. As a result, all intermediate values must be stored in new variables if you build a document across multiple statements. Due to this complexity, use of the stream builder is discouraged.

The builder::stream interface is a streaming interface for constructing complex BSON objects. To create a BSON document by using the stream builder, initialize a builder::stream::document object. Then, you can use the << operator to stream keys and values into your builder.

The following code shows how to use the stream builder to perform the following actions:

Build a document
Convert the document to a bsoncxx::document::value object

auto course_builder = bsoncxx::builder::stream::document{};
course_builder << "title" << "Creative Writing" << "credits" << bsoncxx::types::b_int32{4};
bsoncxx::document::value course{course_builder.extract()};

You can also convert the stream to a bsoncxx::document::value by using the builder::stream::finalize token, as shown in the following example:

using bsoncxx::builder::stream::document;
using bsoncxx::builder::stream::finalize;
bsoncxx::document::value doc = document{} << "title" << "Literature" << finalize;

Print a BSON Document

BSON is a binary-encoded serialization of JSON documents that is not human-readable. To preview the contents of a BSON document in a human-readable format, you can use the bsoncxx::to_json() method to convert your document to extended JSON format.

Extended JSON format is an extension of standard JSON that includes string representations of BSON data types. To learn more, see the MongoDB Extended JSON guide in the MongoDB Server manual.

The bsoncxx::to_json() method accepts a bsoncxx::document::view of the BSON document you want to convert. This method returns an std::string object representing your BSON document in extended JSON format.

The following code shows how to convert a BSON document to extended JSON format and print the results:

bsoncxx::document::value course = make_document(
    kvp("title","Screenwriting"),
    kvp("department","English"));
std::cout << bsoncxx::to_json(course.view()) << std::endl;

{ "title" : "Screenwriting", "department" : "English" }

Additional Information

To learn more about the concepts mentioned in this guide, see the following Server manual entries:

To learn more about performing read operations, see Read Data.

To learn more about performing aggregation operations, see the Transform Your Data with Aggregation guide.

API Documentation

To learn more about the types and methods mentioned in this guide, see the following API documentation:

Back

Time Series Data

Advanced Configuration & Installation