Trabajar con BSON

Overview

En esta guía, puede aprender a utilizar el controlador C++ para almacenar e interactuar con datos BSON mediante el uso de bsoncxx librería.

Formato de datos BSON

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

Nota

Evite agregar claves duplicadas a los documentos BSON. Aunque la especificación BSON permite claves duplicadas, estas pueden causar un comportamiento inesperado en 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 Puede pasar un document::view document::value objeto o a estos métodos. Debe pasar document::value argumentos por referencia rvalue 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
Generador de transmisiones

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 generador de listas crea una matriz.

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

Compila un documento
Construir una matriz
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 tipo constructor para crear un documento BSON. Para crear un documento BSON con el constructor básico, especifique los datos del documento en una lista de objetos de pares clave-valor. Puede crear estos objetos de pares clave-valor pasando una clave y un valor al método builder::basic::kvp(). La clave debe ser de tipo string y el valor de tipo bson_value::value o convertible 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
Almacenar 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()};

Generador de transmisiones

Importante

Recomendamos utilizar el generador básico en lugar del generador de transmisiones.

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 la transmisión 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 JSON extendido es una extensión del JSON estándar que incluye representaciones de cadenas de tipos de datos BSON. Para obtener más información, consulte la guía JSON extendido de MongoDB en el manual del servidor MongoDB.

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 cómo realizar operaciones de agregación, consulte la 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