---
name: "bson_creating"
section: "3"
platform: "linux"
package: "libbson-doc"
version: "1.23.1-1+deb12u3"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/bson_creating"
---

# bson\_creating(3)

Creating a BSON Document

## 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