BSON

Overview

En esta guía, puede aprender cómo crear documentos BSON, escribir documentos BSON en un archivo y leer datos BSON desde un archivo utilizando el controlador C.

BSON, o JSON binario, es el formato de datos que MongoDB utiliza para organizar y almacenar datos. Este formato incluye todos los tipos de estructuras de datos JSON y admite tipos como fechas, enteros de diferentes tamaños, ObjectIds y datos binarios. Para obtener una lista completa de los tipos admitidos, consulte Página del manual del servidorde tipos BSON.

Puede utilizar documentos BSON en su aplicación C incluyendo el paquete libbson.

Los ejemplos de código de esta guía utilizan el siguiente documento BSON como ejemplo:

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

Crear un documento BSON

Los documentos BSON están representados por el bson_t Escriba el controlador C. Puede usar la función BCON_NEW() para crear una instancia bson_t. El siguiente ejemplo crea una representación bson_t del documento BSON de ejemplo:

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

Anexar a un documento BSON

Puede añadir pares campo-valor a una instancia bson_t existente mediante la función BCON_APPEND(). El siguiente ejemplo añade un nuevo campo y valor yearEstablished al documento BSON de ejemplo:

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

También puede usar la función bson_append_* que corresponde al tipo de dato del valor que se va a añadir. El siguiente ejemplo añade el mismo par campo-valor que el ejemplo anterior mediante la función bson_append_int32():

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

Para obtener una lista completa de las bson_append_* funciones, consulte bson_t en la libbson documentación de la API.

Construir matrices BSON

Puede usar el constructor bson_array_builder_t para construir matrices BSON con claves secuenciales administradas automáticamente. El siguiente ejemplo crea una matriz de enteros usando el constructor bson_array_builder_t:

bson_t parent = BSON_INITIALIZER;
bson_array_builder_t *bab;
// Creates an array field using the array builder
BSON_APPEND_ARRAY_BUILDER_BEGIN(&parent, "numbers", &bab);
bson_array_builder_append_int32(bab, 9);
bson_array_builder_append_int32(bab, 8);
bson_array_builder_append_int32(bab, 7);
bson_append_array_builder_end(&parent, bab);
// Adds other fields to the document
BSON_APPEND_UTF8(&parent, "name", "Example Document");
char *str = bson_as_relaxed_extended_json(&parent, NULL);
printf("Document with array: %s\n", str);
bson_free(str);
bson_destroy(&parent);

Document with array: { "numbers" : [ 9, 8, 7 ], "name" : "Example Document" }

Escribir BSON en un archivo

Puede usar la función bson_get_data() con la biblioteca estándar de E/S de archivos de C para escribir datos BSON en un archivo. El siguiente ejemplo escribe el documento BSON de ejemplo en un archivo llamado 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;
}

Leer BSON desde un archivo

Puede usar el tipo bson_reader_t para leer una secuencia de documentos BSON desde un archivo, una región de memoria o una devolución de llamada personalizada. El siguiente ejemplo lee documentos BSON desde un archivo llamado example.bson e imprime la representación JSON de cada documento:

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

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

Limpiar

Puede liberar la memoria asignada para un documento BSON utilizando la función bson_destroy(), como se muestra en el siguiente ejemplo:

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

Documentación de la API

Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API:

• Libbson

• bson_t

• constructor de matrices bson_t

• bson_get_data()

• lector bson_t

• lector bson_json_t

• bson_destroy()