Data Modeling and Serialization

On this page

Overview

Generic Type Parameter
Custom Data Model
Custom Struct Example
Multiple Parameterizations
Custom Serialization
Serialize a String as an ObjectId
Serialize a DateTime as a String
Serialize a u32 as an f64
Other Attributes and Modules
Additional Information
API Documentation

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 library integrate functionality from the Serde framework. To learn how to install the serde crate, see serde at the crates.io crate registry.

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)]

Custom Struct Example

The following code defines a sample Vegetable struct that implements the serde serialization traits:

#[derive(Serialize, Deserialize)]
struct Vegetable {
    name: String,
    category: String,
    tropical: bool,
}

The following code accesses the vegetables collection with Vegetable as its generic type parameter:

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

Because the Collection instance is parameterized with the Vegetable struct, you can perform CRUD operations with this type. The following code inserts a Vegetable instance into the collection:

let calabash = Vegetable {
    name: "calabash".to_string(),
    category: "gourd".to_string(),
    tropical: true,
};
my_coll.insert_one(calabash).await?;

Multiple Parameterizations

If your collection contains multiple schemas, you can define a custom type to model each data type and create clones of the original Collection instance for each type. You can create clones of a Collection instance by using the clone_with_type() method.

Suppose you originally parameterized a collection with a struct called Square, but you later realize that you want to insert a different type of data, modeled by the Circle struct, into the collection. The following code parameterizes a collection with the Square type, then creates a clone of the collection that is parameterized with the Circle type:

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 functions from the bson library to achieve common serialization tasks. To see a full list of these helper functions, see the serde_helpers API documentation.

Serialize a String as an ObjectId

You might want to represent the _id field in a document as a hexadecimal string in your struct. To convert the hexadecimal string to the ObjectId BSON type, use the serialize_hex_string_as_object_id helper function as the value of the serialize_with attribute. The following example attaches the serialize_with attribute to the _id field so that the driver serializes the hexadecimal string as an ObjectId type:

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

To see how the driver serializes a sample Order struct to BSON, select from the following Struct and BSON tabs:

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

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

Serialize a DateTime as a String

You might want to represent a DateTime field value in a document as an ISO-formatted string in BSON. To specify this conversion, use the serialize_bson_datetime_as_rfc3339_string helper function as the value of the serialize_with attribute attached to the field with a DateTime value. The following example attaches the serialize_with attribute to the delivery_date field so that the driver serializes the DateTime value to a string:

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

To see how the driver serializes a sample Order struct to BSON, select from the following Struct and BSON tabs:

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

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

Serialize a u32 as an f64

You might want to represent a u32 field value in a document as an f64, or Double, type in BSON. To specify this conversion, use the serialize_u32_as_f64 helper function as the value of the serialize_with attribute attached to the field with a u32 value. The following example attaches the serialize_with attribute to the quantity field so that the driver serializes the u32 value to a Double type:

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

Note

The BSON Double representation of a u32 value appears the same as the original value.

Other Attributes and Modules

In addition to helper functions, the bson library provides modules that handle both serialization and deserialization. To select a module to use on a specific field or variant, set the value of the with attribute to the name of the module:

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

For a full list of these modules, see the serde_helpers API documentation.

The serde crate provides many other attributes to customize serialization. The following list describes some common attributes and their functionality:

rename: serialize and deserialize a field with a specified name instead of the Rust struct or variant name
skip: do not serialize or deserialize the specified field
default: if no value is present during deserialization, use the default value from Default::default()

For a full list of serde attributes, see the serde Attributes API Documentation.

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.

API Documentation

To learn more about the methods and types mentioned in this guide, see the following API documentation:

collection()
clone_with_type()
serialize_with Serde attribute
deserialize_with Serde attribute
with Serde attribute

Back

Compound Operations

Databases and Collections