Trabajar con BSON

Overview

En esta guía, puedes aprender a usar el driver de C++ para almacenar e interactuar con datos BSON utilizando el bsoncxx librería.

Formato de datos BSON

MongoDB utiliza el formato de datos BSON, o Binary JSON, para almacenar documentos y realizar llamadas a procedimientos remotos. Este formato de datos incluye todos los tipos de estructura de datos JSON y admite tipos adicionales, incluidos fechas, enteros de diferentes tamaños, valores de ObjectId y datos binarios. Para obtener una lista completa de los tipos admitidos, consulta el BSON types página en el manual de MongoDB Server.

Nota

Evita agregar claves duplicadas a los documentos BSON. Aunque la especificación BSON permite claves duplicadas, estas pueden causar un comportamiento inesperado en el MongoDB Server.

Valores y vistas BSON

Muchos métodos del controlador de C++ aceptan un documento BSON como argumento. La biblioteca bsoncxx proporciona dos tipos de datos que pueden ser utilizados para representar un documento BSON: bsoncxx::document::value y bsoncxx:document::view.

Un objeto document::value representa un documento BSON que posee su propio buffer subyacente de datos. Cuando se pasa un objeto document::value a un método controlador de C++, el método recibe una copia de los datos del documento BSON. Cuando un objeto document::value sale del ámbito, su búfer subyacente se libera.

Tip

Puede convertir los tipos builder a tipos document::value llamando a métodos asistente en el builder. Para más información sobre los tipos de builder, consulta la sección Compilar un Documento BSON en esta guía.

Un objeto document::view proporciona una vista no propietaria de un document::value. Este tipo te permite leer e interactuar con el contenido de un documento BSON sin poseer los datos subyacentes del documento. Cuando se pasa un objeto document::view a un método de controlador en C++, el método puede utilizar los datos del documento subyacente sin copiarlos. Puede crear una vista llamando al método view() en un objeto document::value.

Tip

Para evitar copias excesivas, recomendamos pasar documentos por visualización, si es posible.

Algunos métodos de controlador de C++ aceptan argumentos de tipo document::view_or_value. Puedes pasar un objeto document::view o document::value a estos métodos. Debes pasar document::value argumentos por rvalue referencia para transferir la propiedad del documento al método.

Importante

Un document::view no debe sobrevivir a ningún document::value al que haga referencia. Si una document::view utiliza una document::value después de que se haya liberado su búfer subyacente, la vista contendrá un puntero colgante. El acceso a un puntero colgante puede causar fallos en la aplicación, corrupción de datos y otros comportamientos impredecibles.

Compilar un Documento BSON

Esta sección muestra cómo utilizar las siguientes interfaces para crear un documento BSON:

Constructor de listas
Constructor básico
Stream Builder

Constructor de listas

La interfaz builder::list es un generador similar a JSON para construir documentos y arreglos. Para crear un documento BSON mediante el generador de listas, crea un objeto bsoncxx::builder::list y pasa una lista de pares clave-valor al constructor. El generador de listas crea un documento BSON si la lista de claves y valores cumple con los siguientes requisitos:

La lista tiene un número par de elementos.
Cada clave es de tipo string y cada valor es de tipo bson_value::value o es implícitamente convertible a uno.

Si no se cumplen los requisitos anteriores, el creador de listas crea un arreglo.

Este ejemplo utiliza el generador de listas para realizar las siguientes acciones:

Compila un documento
Compilar un arreglo
Convertir el documento del generador en un objeto bsoncxx::document::value

bsoncxx::builder::list course_doc = { "title", "Poetry",
                                      "department", "English" };
bsoncxx::builder::list courses_array = { "Poetry", "Literature",
                                         "Creative Writing" };
bsoncxx::document::value course{course_doc.view().get_document().value};

Constructor básico

La interfaz builder::basic es una interfaz de estilo constructor para construir un documento BSON. Para crear un documento BSON utilizando el generador básico, especifica los datos de tu documento en una lista de objetos de pares clave-valor. Puedes crear estos objetos de pares clave-valor pasando una clave y un valor al método builder::basic::kvp(). La clave debe tener un tipo string, y el valor debe tener un tipo bson_value::value o poder convertirse implícitamente a uno.

Puedes usar el método make_document() del generador básico para crear un documento y convertirlo en un bsoncxx::document::value en una sola instrucción, como se muestra en el siguiente código:

using bsoncxx::builder::basic::make_document; 
using bsoncxx::builder::basic::kvp;
bsoncxx::document::value course = make_document(
    kvp("title","Poetry"),
    kvp("department","English"));

Alternativamente, puedes crear un documento BSON a través de múltiples instrucciones añadiendo pares clave-valor a un objeto constructor básico. Este ejemplo utiliza el constructor básico para realizar las siguientes acciones:

Inicializar un objeto builder::basic::document
Almacena datos en el documento utilizando el método append()
Convertir el documento del generador en un objeto bsoncxx::document::value

using bsoncxx::builder::basic::kvp;
auto course_builder = bsoncxx::builder::basic::document{};
course_builder.append(kvp("title", "Literature"),
                      kvp("department", "English"));
                      
bsoncxx::document::value course{course_builder.extract()};

Stream Builder

Importante

Recomendamos que uses el Constructor básico en lugar del constructor de flujos.

Para agregar correctamente cada nuevo valor, un generador de flujos debe rastrear el estado del documento actual. No se puede reutilizar el constructor de secuencias inicial después de que este estado cambie. En consecuencia, todos los valores intermedios deben almacenarse en nuevas variables si se compila un documento a través de varias instrucciones. Debido a esta complejidad, se desaconseja el uso del generador de transmisiones.

La interfaz de builder::stream es una interfaz de transmisión para construir objetos BSON complejos. Para crear un documento BSON utilizando el generador de flujos, inicializa un objeto builder::stream::document. Luego, puedes usar el operador << para transmitir claves y valores en tu generador.

El siguiente código muestra cómo usar el generador de stream para realizar las siguientes acciones:

Compila un documento
Convertir el documento en un objeto bsoncxx::document::value

auto course_builder = bsoncxx::builder::stream::document{};
course_builder << "title" << "Creative Writing" << "credits" << bsoncxx::types::b_int32{4};
bsoncxx::document::value course{course_builder.extract()};

También puedes convertir el stream a un bsoncxx::document::value utilizando el token builder::stream::finalize, como se muestra en el siguiente ejemplo:

using bsoncxx::builder::stream::document;
using bsoncxx::builder::stream::finalize;
bsoncxx::document::value doc = document{} << "title" << "Literature" << finalize;

Imprimir un Documento BSON

BSON es una serialización de documentos JSON codificada en binario que no es legible para los humanos. Para previsualizar el contenido de un documento BSON en un formato legible por humanos, puedes usar el método bsoncxx::to_json() para convertir tu documento al formato extendido JSON.

El formato Extended JSON es una extensión del JSON estándar que incluye representaciones en string de los tipos de datos BSON. Para obtener más información, consulta la guía MongoDB Extended JSON en el manual de MongoDB Server.

El método bsoncxx::to_json() acepta un bsoncxx::document::view del documento BSON que deseas convertir. Este método devuelve un objeto std::string que representa tu documento BSON en formato JSON extendido.

El siguiente código muestra cómo convertir un documento BSON al formato JSON extendido e imprimir los resultados:

bsoncxx::document::value course = make_document(
    kvp("title","Screenwriting"),
    kvp("department","English"));
std::cout << bsoncxx::to_json(course.view()) << std::endl;

{ "title" : "Screenwriting", "department" : "English" }

Información Adicional

Para aprender más sobre los conceptos mencionados en esta guía, consulta las siguientes entradas del manual del servidor:

Para obtener más información sobre la realización de operaciones de agregación, consulta el agregación guide.

Documentación de la API

Para obtener más información sobre los tipos y métodos mencionados en esta guía, consulta la siguiente documentación de la API:

Volver

Datos de Time Series

JSON extendido