Docs 菜单
Docs 主页
/
客户端库
/
C
Docs 主页
/
客户端库
/
C
Docs 主页
/
客户端库
/
C

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 或二进制 JSON 是 MongoDB 用来组织和存储数据的数据格式。这种数据格式包括所有 JSON 数据结构类型，并增加了对日期、不同大小的整数、ObjectId 和二进制数据等类型的支持。有关支持类型的完整列表，请参阅 BSON 类型服务器手册页面。

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

本指南中的代码示例使用以下 BSON 文档作为示例：

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

创建 BSON 文档

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")
);

注意

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.

将 BSON 写入文件

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);

重要

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

API 文档

要进一步了解本指南所讨论的任何方法或类型，请参阅以下 API 文档：

后退

聚合(Aggregation)

来年

扩展 JSON

在此页面上