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 en el controlador C. Puede usar la función BCON_NEW() para crear una instancia de bson_t. El siguiente ejemplo crea una representación bson_t del documento BSON de muestra:

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

Nota

Valores de campo BSON

Al crear o agregar campos a un documento BSON, asegúrate de usar la función BCON_* adecuada para representar correctamente los valores de los campos. Para obtener una lista completa de funciones BCON_*, consulta el archivo bson-bcon.h en el repositorio de GitHub del driver C.

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 funciones de bson_append_*, consulte bson_t en la documentación API de libbson.

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

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

Leyendo JSON de un archivo

Puedes usar el tipo bson_json_reader_t para leer una secuencia de documentos JSON y convertirlos en documentos bson_t. El siguiente ejemplo lee documentos JSON de un archivo denominado example.json, convierte cada documento a formato BSON e imprime los documentos:

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

Importante

Siempre llama a bson_destroy() en una instancia de bson_t cuando hayas terminado de usarla para evitar fugas de memoria en tu aplicación.

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:

Volver

Agregación

JSON extendido