Modelado y serialización de datos

Overview

En esta guía, aprenderá cómo el controlador de Rust gestiona las conversiones entre tipos BSON y Rust. El proceso de convertir un tipo de Rust a BSON se denomina serialización, mientras que el proceso inverso se denomina deserialización.

El lenguaje Rust utiliza un sistema de tipos estático, pero BSON tiene un esquema dinámico. Para gestionar las conversiones entre los tipos de Rust y BSON, el controlador y el... BSONLa caja integra funcionalidades del marco Serde.

Al implementar la funcionalidad del paquete serde en su aplicación, puede usar tipos de Rust personalizados, como estructuras y enumeraciones, para modelar sus datos.

Esta guía incluye las siguientes secciones:

• Parámetro Genérico de Tipo describe la parametrización de colecciones y el modelado de datos

• Elmodelo de datos personalizado describe cómo definir tipos de Rust personalizados para modelar datos en sus colecciones

• La serialización personalizada describe cómo modificar el comportamiento de serialización y deserialización predeterminado mediante el uso de atributos y proporciona ejemplos.

• Información adicional proporciona enlaces a recursos y documentación de API para los tipos y métodos mencionados en esta guía.

Parámetro de tipo genérico

Al crear una instancia Collection, debe especificar un parámetro de tipo genérico para representar el tipo de datos que modela los documentos de su colección. Para obtener más información sobre cómo especificar un parámetro de tipo genérico, consulte Sección de Parametrización de Colecciones de la guía sobre Bases de Datos y Colecciones.

Le recomendamos que defina y utilice un tipo personalizado para modelar los datos de su colección en lugar de utilizar el tipo Document.

Modelo de datos personalizado

Puede usar cualquier tipo de datos de Rust que implemente los atributos Serialize y Deserialize del paquete serde como parámetro de tipo genérico para una instancia Collection. Para implementar los atributos Serialize y Deserialize, debe incluir el siguiente atributo derive antes de definir un tipo de Rust:

#[derive(Serialize, Deserialize)]

#[derive(Serialize, Deserialize)]
struct Article {
    title: String,
    date: DateTime,
    content: String,
    content_embeddings: Vector,
}

let my_coll: Collection<Article> = client
    .database("db")
    .collection("articles");

let article = Article {
    title: "Maintaining Your Garden in Winter".to_string(),
    date: DateTime::now(),
    content: "As fall winds down, you might be wondering what you should be doing in your garden in the coming months ...".to_string(),
    content_embeddings: Vector::Float32(vec! [0.01020927,-0.011224265,0.015686288,-0.018586276,-0.023160344])
};
my_coll.insert_one(article).await?;

let shapes_coll: Collection<Square> = client
    .database("db")
    .collection("shapes");
// ... perform some operations with Square
let shapes_coll: Collection<Circle> = shapes_coll.clone_with_type();
// ... perform some operations with Circle

Serialización personalizada

Puedes modificar el comportamiento predeterminado de serialización y deserialización del controlador de Rust mediante atributos del serde paquete. Los atributos son metadatos opcionales que se adjuntan a campos de estructuras o variantes de enumeraciones.

El contenedor serde proporciona los atributos serialize_with y deserialize_with, que toman funciones auxiliares como valores. Estas funciones auxiliares personalizan la serialización y deserialización en campos y variantes específicos. Para especificar un atributo en un campo, incluya el atributo antes de la definición del campo:

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(serialize_with = "<helper function>")]
    field1: String,
    // ... other fields
}

En las siguientes secciones, puede encontrar ejemplos que utilizan tipos auxiliares de la biblioteca bson para lograr tareas de serialización comunes.

Los ejemplos muestran los siguientes enfoques:

• BSON 3.0: Utiliza la anotación serde_as proporcionada por la caja serde_with, que ofrece mayor flexibilidad y capacidades de composición.

• BSON.x:2 utiliza las serialize_with funciones auxiliares tradicionales

BSON 2.15 es la versión predeterminada. Elija el enfoque que coincida con la versión de su contenedor BSON.

Para utilizar BSON 3.0 en su aplicación, habilítelo como una característica en el Cargo.toml de su proyecto, de manera similar a lo siguiente:

[dependencies.mongodb]
version = "3.3.0"
features = ["bson-3"]

Al habilitar BSON 3.0, puede usar serde_as. Para usar serde_as, debe importarlo en su aplicación, como se muestra en el siguiente código:

use serde_with::serde_as;

Para ver una lista completa de las funciones auxiliares de Serde, consulte la documentación de la API serde_helpers.

#[serde_as]
#[derive(Serialize, Deserialize)]
struct Order {
    #[serde_as(as = "object_id::FromHexString")]
    _id: String,
    item: String,
}

#[derive(Serialize, Deserialize)]
struct Order {
    #[serde(serialize_with = "serialize_hex_string_as_object_id")]
    _id: String,
    item: String,
}

let order = Order {
    _id: "6348acd2e1a47ca32e79f46f".to_string(),
    item: "lima beans".to_string(),
};

{
  "_id": { "$oid": "6348acd2e1a47ca32e79f46f" },
  "item": "lima beans"
}

#[serde_as]
#[derive(Serialize, Deserialize)]
struct Order {
    item: String,
    #[serde_as(as = "datetime::AsRfc3339String")]
    delivery_date: DateTime,
}

#[derive(Serialize, Deserialize)]
struct Order {
    item: String,
    #[serde(serialize_with = "serialize_bson_datetime_as_rfc3339_string")]
    delivery_date: DateTime,
}

let order = Order {
    item: "lima beans".to_string(),
    delivery_date: DateTime::now(),
};

{
  "_id": { ... },
  "item": "lima beans",
  "delivery_date": "2023-09-26T17:30:18.181Z"
}

#[serde_as]
#[derive(Serialize, Deserialize)]
struct Order {
    item: String,
    #[serde_as(as = "u32::AsF64")]
    quantity: u32,
}

#[derive(Serialize, Deserialize)]
struct Order {
    item: String,
    #[serde(serialize_with = "serialize_u32_as_f64")]
    quantity: u32,
}

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(with = "<module>")]
    field1: u32,
    // ... other fields
}

Información Adicional

Para obtener más información sobre los tipos BSON, consulte Tipos BSON en el manual del servidor.

Para obtener más ejemplos que demuestran serde la funcionalidad, consulte el artículo Estructuración de datos con Serde en el Centro para desarrolladores de Rust.

Para obtener más información sobre el marco Serde, consulte la documentación de Serde.