Data Modeling and Serialization

Custom Struct Example

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

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

The following code accesses the articles collection with the Article struct as its generic type parameter:

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

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

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?;

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

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,
}

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.

API Documentation

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

• collection()

• Vector

• clone_with_type()

• serialize_with Serde attribute

• deserialize_with Serde attribute

• with Serde attribute