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.

Implementando la funcionalidad de la caja serde en tu aplicación, puedes utilizar tipos Rust personalizados, como structs y enums (estructuras y enumeraciones) para modelar tus 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.

• Serialización personalizada describe cómo modificar el comportamiento por defecto de serialización y deserialización utilizando 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 de Collection, debe especificar un parámetro de tipo genérico para representar el tipo de datos que modelan los documentos de su colección. Para aprender más sobre cómo especificar un parámetro de tipo genérico, consulta Sección de parametrización de la colección 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

Puedes usar cualquier tipo de dato Rust que implemente los traits Serialize y Deserialize de la caja serde como parámetro de tipo genérico para una instancia de Collection. Para implementar los Serialize y Deserialize, debes incluir el siguiente derive atributo 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 2.x: Utiliza las funciones asistentes tradicionales serialize_with

BSON 2.15 es la versión por defecto. Elige el enfoque que coincida con tu versión de la caja 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 funciones asistentes de Serde, consulta 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.