BSON

Overview

En esta guía, aprenderás a crear documentos BSON, a guardar documentos BSON en un archivo y a leer datos BSON de un archivo usando el driver C.

BSON, o JSON binario, es el formato de datos que MongoDB usa para organizar y almacenar datos. Este formato de datos incluye todos los tipos de estructura de datos JSON y añade soporte para tipos como fechas, enteros de diferentes tamaños, ObjectIds y datos binarios. Para ver una lista completa de los tipos compatibles, consulta la BSON Types página del manual del servidor.

Puedes usar documentos BSON en tu aplicación en C incluyendo el paquete libbson.

Los ejemplos de código en esta guía usan 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")
);

Añadir a un documento BSON

Puedes agregar pares de campo-valor a una instancia de bson_t existente usando la función BCON_APPEND(). El siguiente ejemplo anexa un nuevo campo yearEstablished y valor al documento BSON de ejemplo:

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

También se puede usar la función bson_append_* que corresponde al tipo de datos del valor que debe añadirse. El siguiente ejemplo añade el mismo par campo-valor que el ejemplo anterior utilizando 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.

Compilar arreglos/arrays BSON

Puedes usar el builder de bson_array_builder_t para construir arreglos BSON con claves secuenciales administradas automáticamente. El siguiente ejemplo crea un arreglo de enteros utilizando el generador 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" }

Guardar BSON en un archivo

Puedes usar la función bson_get_data() con la librería estándar de entrada/salida de archivos de C para guardar datos BSON en un archivo. El siguiente ejemplo escribe el documento BSON de muestra 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

Puedes usar el tipo bson_reader_t para leer una secuencia de documentos BSON desde un archivo, una región de memoria o una función de retorno personalizada. El siguiente ejemplo lee documentos BSON de 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);

Optimización

Puedes 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

• bson_json_reader_t

• bson_destroy()