Data Modeling and Serialization

Overview

In this guide, you can learn about how the Rust driver handles conversions between BSON and Rust types. The process of converting a Rust type to BSON is called serialization, while the reverse process is called deserialization.

The Rust language uses a static type system, but BSON has a dynamic schema. To handle conversions between Rust types and BSON, the driver and the bson crate integrate functionality from the Serde framework.

By implementing functionality from the serde crate into your application, you can use custom Rust types such as structs and enums to model your data.

This guide includes the following sections:

• Generic Type Parameter describes collection parameterization and data modeling

• Custom Data Model describes how to define custom Rust types to model data in your collections

• Custom Serialization describes how to modify default serialization and deserialization behavior by using attributes and provides examples

• Additional Information provides links to resources and API documentation for types and methods mentioned in this guide

Generic Type Parameter

When you create a Collection instance, you must specify a generic type parameter to represent the type of data that models the documents in your collection. To learn more about specifying a generic type parameter, see the Collection Parameterization section of the guide on Databases and Collections.

We recommend that you define and use a custom type to model your collection's data instead of using the Document type.

Custom Data Model

You can use any Rust data type that implements the Serialize and Deserialize traits from the serde crate as the generic type parameter for a Collection instance. To implement the Serialize and Deserialize traits, you must include the following derive attribute before defining a Rust type:

#[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

Custom Serialization

You can modify the default serialization and deserialization behavior of the Rust driver by using attributes from the serde crate. Attributes are optional pieces of metadata attached to fields of structs or variants of enums.

The serde crate provides the serialize_with and deserialize_with attributes, which take helper functions as values. These helper functions customize serialization and deserialization on specific fields and variants. To specify an attribute on a field, include the attribute before the field definition:

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

In the following sections, you can find examples that use helper types from the bson library to achieve common serialization tasks.

The examples show the following approaches:

• BSON 3.0: Uses the serde_as annotation provided by the serde_with crate, which offers additional flexibility and composition capabilities

• BSON 2.x: Uses the traditional serialize_with helper functions

BSON 2.15 is the default version. Choose the approach that matches your BSON crate version.

To use BSON 3.0 in your application, enable it as a feature in your project's Cargo.toml, similar to the following:

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

When you enable BSON 3.0, you can use serde_as. To use serde_as, you must import it in your application, as shown in the following code:

use serde_with::serde_as;

To see a full list of Serde helper functions, see the serde_helpers API documentation.

#[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
}

Additional Information

To learn more about BSON types, see BSON Types in the Server manual.

For more examples that demonstrate serde functionality, see the Structuring Data with Serde in Rust Developer Center article.

To learn more about the Serde framework, see the Serde documentation.