BSON_CREATING(3)

NAME
bson_creating - Creating a BSON Document

THE BSON_T STRUCTURE

BSON documents are created using the bson_t structure. This structure encapsulates the necessary logic for encoding using the BSON Specification. At the core, bson_t is a buffer manager and set of encoding routines.

TIP:
        BSON documents can live on the stack or the heap based on the performance needs or preference of the consumer.

Let's start by creating a new BSON document on the stack. Whenever using libbson, make sure you #include <bson/bson.h>.

        bson_t b;

        bson_init (&b);

This creates an empty document. In JSON, this would be the same as {}.

We can now proceed to adding items to the BSON document. A variety of functions prefixed with bson_append_ can be used based on the type of field you want to append. Let's append a UTF-8 encoded string.

        bson_append_utf8 (&b, "key", -1, "value", -1);

Notice the two -1 parameters. The first indicates that the length of key in bytes should be determined with strlen(). Alternatively, we could have passed the number 3. The same goes for the second -1, but for value.

Libbson provides macros to make this less tedious when using string literals. The following two appends are identical.

        bson_append_utf8 (&b, "key", -1, "value", -1);
        BSON_APPEND_UTF8 (&b, "key", "value");

Now let's take a look at an example that adds a few different field types to a BSON document.

        bson_t b = BSON_INITIALIZER;

        BSON_APPEND_INT32 (&b, "a", 1);
        BSON_APPEND_UTF8 (&b, "hello", "world");
        BSON_APPEND_BOOL (&b, "bool", true);

Notice that we omitted the call to bson_init(). By specifying BSON_INITIALIZER we can remove the need to initialize the structure to a base state.

SUB-DOCUMENTS AND SUB-ARRAYS

To simplify the creation of sub-documents and arrays, bson_append_document_begin() and bson_append_array_begin() exist. These can be used to build a sub-document using the parent documents memory region as the destination buffer.

        bson_t parent;
        bson_t child;
        char *str;

        bson_init (&parent);
        bson_append_document_begin (&parent, "foo", 3, &child);
        bson_append_int32 (&child, "baz", 3, 1);
        bson_append_document_end (&parent, &child);

        str = bson_as_canonical_extended_json (&parent, NULL);
        printf ("%s\n", str);
        bson_free (str);

        bson_destroy (&parent);

        { "foo" : { "baz" : 1 } }

SIMPLIFIED BSON C OBJECT NOTATION

Creating BSON documents by hand can be tedious and time consuming. BCON, or BSON C Object Notation, was added to allow for the creation of BSON documents in a format that looks closer to the destination format.

The following example shows the use of BCON. Notice that values for fields are wrapped in the BCON_* macros. These are required for the variadic processor to determine the parameter type.

        bson_t *doc;

        doc = BCON_NEW ("foo",
                        "{",
                        "int",
                        BCON_INT32 (1),
                        "array",
                        "[",
                        BCON_INT32 (100),
                        "{",
                        "sub",
                        BCON_UTF8 ("value"),
                        "}",
                        "]",
                        "}");

Creates the following document

        { "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } }

AUTHOR
MongoDB, Inc

COPYRIGHT
2017-present, MongoDB, Inc