BSON

Overview

In this guide, you can learn how to create BSON documents, write BSON documents to a file, and read BSON data from a file by using the C driver.

BSON, or Binary JSON, is the data format that MongoDB uses to organize and store data. This data format includes all JSON data structure types and adds support for types including dates, different size integers, ObjectIds, and binary data. For a complete list of supported types, see the BSON Types server manual page.

You can use BSON documents in your C application by including the libbson package.

The code samples in this guide use the following BSON document as an example:

{
    "address" : {
        "street" : "Pizza St",
        "zipcode" : "10003"
    },
    "coord" : [-73.982419, 41.579505]
    "cuisine" : "Pizza",
    "name" : "Mongo's Pizza"
}

Create a BSON Document

BSON documents are represented by the bson_t type in the C driver. You can use the BCON_NEW() function to create a bson_t instance. The following example creates a bson_t representation of the sample BSON document:

bson_t *doc = BCON_NEW( "address", "{",
    "street", BCON_UTF8("Pizza St"),
    "zipcode", BCON_UTF8("10003"), "}",
    "coord", "[", BCON_DOUBLE(-73.982419), BCON_DOUBLE(41.579505), "]",
    "cuisine", BCON_UTF8("Pizza"),
    "name", BCON_UTF8("Mongo's Pizza")
);

Note

BSON Field Values

When creating or appending fields to a BSON document, ensure that you use the appropriate BCON_* function to represent the field values correctly. For a complete list of BCON_* functions, see the bson-bcon.h file in the C driver GitHub repository.

Append to a BSON Document

You can append field-value pairs to an existing bson_t instance by using the BCON_APPEND() function. The following example appends a new yearEstablished field and value to the sample BSON document:

BCON_APPEND(doc, "yearEstablished", BCON_INT32(1996));

You can also use the bson_append_* function that corresponds to the data type of the value to be appended. The following example adds the same field-value pair as the preceding example by using the bson_append_int32() function:

bson_append_int32(doc, "yearEstablished", -1, 1996);

For a complete list of bson_append_* functions, see bson_t in the libbson API documentation.

Write BSON to a File

You can use the bson_get_data() function with the standard C file I/O library to write BSON data to a file. The following example writes the sample BSON document to a file named output.bson:

FILE *fp;
if ((fp = fopen("output.bson", "wb"))) {
    fwrite(bson_get_data(doc), 1, doc->len, fp);
    fclose(fp);
} else {
    fprintf(stderr, "Failed to open file for writing.\n");
    return EXIT_FAILURE;
}

Read BSON From a File

You can use the bson_reader_t type to read a sequence of BSON documents from a file, memory region, or a custom callback. The following example reads BSON documents from a file named example.bson and prints the JSON representation of each document:

bson_reader_t *reader;
bson_error_t error;
const bson_t *b;
char *str;
if (!((reader = bson_reader_new_from_file("example.json", &error)))) {
    fprintf(stderr, "Failed to open file: %s\n", error.message);
    return EXIT_FAILURE;
}
while ((b = bson_reader_read(reader, NULL))) {
    str = bson_as_canonical_extended_json(b, NULL);
    fprintf(stdout, "%s\n", str);
    bson_free(str);
}
bson_reader_destroy(reader);

Reading JSON From a File

You can use the bson_json_reader_t type to read a sequence of JSON documents and convert them to bson_t documents. The following example reads JSON documents from a file named example.json, converts each document to BSON format, and prints the documents:

bson_json_reader_t *reader;
int b;
bson_error_t error;
bson_t doc = BSON_INITIALIZER;
if (!((reader = bson_json_reader_new_from_file("example.json", &error)))) {
    fprintf(stderr, "Failed to open file: %s\n", error.message);
    return EXIT_FAILURE;
}
while ((b = bson_json_reader_read(reader, &doc, &error))) {
    if (b < 0) {
        fprintf(stderr, "Failed to parse JSON: %s\n", error.message);
        abort();
    }
    if (fwrite(bson_get_data(&doc), 1, doc.len, stdout) != doc.len) {
        fprintf(stderr, "Failed to write BSON to stdout, exiting.\n");
        exit(1);
    }
    bson_reinit(&doc);
}
bson_json_reader_destroy(reader);
bson_destroy(&doc);

Cleanup

You can free the memory allocated for a BSON document by using the bson_destroy() function, as shown in the following example:

bson_t *doc = BCON_NEW("test", BCON_UTF8("example"));
// Operations using doc
bson_destroy(doc);

Important

Always call bson_destroy() on a bson_t instance when you are finished with it to avoid memory leaks in your application.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

Back

Aggregation

Extended JSON