1BSON_CREATING(3)                    libbson                   BSON_CREATING(3)
2
3
4

NAME

6       bson_creating - Creating a BSON Document
7

THE BSON_T STRUCTURE

9       BSON  documents  are created using the bson_t structure. This structure
10       encapsulates the necessary logic for encoding using the BSON Specifica‐
11       tion.  At the core, bson_t is a buffer manager and set of encoding rou‐
12       tines.
13
14       TIP:
15          BSON documents can live on the stack or the heap based on  the  per‐
16          formance needs or preference of the consumer.
17
18       Let's  start by creating a new BSON document on the stack. Whenever us‐
19       ing libbson, make sure you #include <bson/bson.h>.
20
21          bson_t b;
22
23          bson_init (&b);
24
25       This creates an empty document. In JSON, this would be the same as {}.
26
27       We can now proceed to adding items to the BSON document. A  variety  of
28       functions  prefixed  with bson_append_ can be used based on the type of
29       field you want to append. Let's append a UTF-8 encoded string.
30
31          bson_append_utf8 (&b, "key", -1, "value", -1);
32
33       Notice the two -1 parameters. The first indicates that  the  length  of
34       key  in  bytes  should  be  determined with strlen(). Alternatively, we
35       could have passed the number 3. The same goes for the  second  -1,  but
36       for value.
37
38       Libbson  provides  macros  to  make this less tedious when using string
39       literals. The following two appends are identical.
40
41          bson_append_utf8 (&b, "key", -1, "value", -1);
42          BSON_APPEND_UTF8 (&b, "key", "value");
43
44       Now let's take a look at an example that adds  a  few  different  field
45       types to a BSON document.
46
47          bson_t b = BSON_INITIALIZER;
48
49          BSON_APPEND_INT32 (&b, "a", 1);
50          BSON_APPEND_UTF8 (&b, "hello", "world");
51          BSON_APPEND_BOOL (&b, "bool", true);
52
53       Notice that we omitted the call to bson_init(). By specifying BSON_INI‐
54       TIALIZER we can remove the need to initialize the structure to  a  base
55       state.
56

SUB-DOCUMENTS AND SUB-ARRAYS

58       To    simplify    the    creation    of   sub-documents   and   arrays,
59       bson_append_document_begin() and bson_append_array_begin() exist. These
60       can  be  used to build a sub-document using the parent documents memory
61       region as the destination buffer.
62
63          bson_t parent;
64          bson_t child;
65          char *str;
66
67          bson_init (&parent);
68          bson_append_document_begin (&parent, "foo", 3, &child);
69          bson_append_int32 (&child, "baz", 3, 1);
70          bson_append_document_end (&parent, &child);
71
72          str = bson_as_canonical_extended_json (&parent, NULL);
73          printf ("%s\n", str);
74          bson_free (str);
75
76          bson_destroy (&parent);
77
78          { "foo" : { "baz" : 1 } }
79

SIMPLIFIED BSON C OBJECT NOTATION

81       Creating BSON documents by hand can  be  tedious  and  time  consuming.
82       BCON, or BSON C Object Notation, was added to allow for the creation of
83       BSON documents in a format that looks closer to the destination format.
84
85       The following example shows the use of BCON.  Notice  that  values  for
86       fields  are  wrapped  in  the BCON_* macros. These are required for the
87       variadic processor to determine the parameter type.
88
89          bson_t *doc;
90
91          doc = BCON_NEW ("foo",
92                          "{",
93                          "int",
94                          BCON_INT32 (1),
95                          "array",
96                          "[",
97                          BCON_INT32 (100),
98                          "{",
99                          "sub",
100                          BCON_UTF8 ("value"),
101                          "}",
102                          "]",
103                          "}");
104
105       Creates the following document
106
107          { "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } }
108

AUTHOR

110       MongoDB, Inc
111

113       2017-present, MongoDB, Inc
114
115
116
117
1181.23.1                           Oct 20, 2022                 BSON_CREATING(3)
Impressum