Modelado y serialización de datos

Overview

En esta guía, puedes aprender sobre cómo el driver Rust gestiona las conversiones entre BSON y los tipos de 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 conversiones entre tipos Rust y BSON, el driver y el BSON la caja integra funcionalidad 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

• Modelo de datos personalizado describe cómo definir tipos de Rust personalizados para modelar datos en tus 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 la 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.

Recomendamos definir y usar un tipo personalizado para modelar los datos de la colección en lugar de usar 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 utilizando atributos de la caja serde. Los atributos son elementos opcionales de metadatos adjuntos a los campos de las estructuras o variantes de enumeraciones.

La serde caja proporciona los atributos serialize_with y deserialize_with, que toman funciones asistentes como valores. Estas funciones auxiliares personalizan la serialización y deserialización de 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, se encuentran ejemplos que utilizan tipos auxiliares de la librería bson para realizar tareas comunes de serialización.

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 tu aplicación, actívalo como una funcionalidad en el Cargo.toml de tu proyecto, similar a lo siguiente:

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

Al activar BSON 3.0, puedes usar serde_as. Para usar serde_as, debes importarlo en tu 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 más información sobre los BSON types, consulta BSON types en el manual del servidor.

Para ver más ejemplos que demuestren la funcionalidad de serde, consulta el artículo Estructuración de datos con Serde en Rust en el Centro de desarrollo.

Para aprender más sobre el marco Serde, consulta la documentación de Serde.