BSONデータとの連携

Overview

このガイドでは、 MongoDB Rustドライバーと bson crate がBSONデータを表す方法、 BSONとRust型間の変換方法、およびアプリケーションコードでBSONドキュメントを直接操作する方法を学習できます。

ドライバーは、bson crateを使用してBSONデータをエンコードおよびデコードし、Serverフレームワークを使用してRust型を直列化および逆直列化します。直列化 の詳細については、 データ モデリングと直列化のガイドをご覧ください。

BSONとBSON types の完全なリストについて詳しくは、 MongoDB Serverマニュアルの BSON types を参照してください。

let mut restaurant: Document = doc! {
    "address": {
        "street": "Pizza St",
        "zipcode": "10003",
    },
    "coord": [-73.982_419_f64, 41.579_505_f64],
    "cuisine": "Pizza",
    "name": "Mongo's Pizza",
};

BSONデータ型

MongoDB、 BSON （Binary JSON）と呼ばれるバイナリ形式でドキュメントを保存します。 BSON はすべてのJSONデータ構造タイプをサポートしており、日付、異なるサイズの整数、ObjectId 値、バイナリ データなどの追加のタイプを追加します。

Rust のエコシステムでは、bson crate はbson::Bson列挙とBSONドキュメントを使用してBSON値をモデル化し、bson::Document 構造体を使用します。

RustでのBSON の表現

bson crate は、 BSONデータを操作するための次のコアタイプとマイクロを提供します。

• bson::Bson: string、integer、 ドキュメント 、配列など任意のBSON値を表す列挙型。

• bson::Document: UTF-8string キーから BSON 値への順序付きマップ（ BSONドキュメントを表す）。

• bson! マイクロ: リテラルから Bson 値を構築します。

• doc! マイクロ: リテラルから Document を構築します。

例、doc! マイクロを使用して、このガイドの先頭に表示されているサンプルrestaurant ドキュメントを作成できます。

次の例に示すように、ヘルパーメソッドを使用して、型指定されていない Bson 値または厳密に型指定されたRust値として Document 内のフィールドにアクセスできます。

let value = restaurant.get("cuisine"); // Option<&Bson>
let name = restaurant.get_str("name")?; // &str
let address = restaurant.get_document("address")?; // &Document
let zipcode = address.get_str("zipcode")?; // &str

BSONドキュメントの変更

Document の内容は、次の例に示すように、挿入、置換、削除などの標準的なマップのような操作を使用して変更できます。

restaurant = Document = doc! {
    "address": {
        "street": "Pizza St",
        "zipcode": "10003",
    },
    "coord": [-73.982_419_f64, 41.579_505_f64],
    "cuisine": "Pizza",
    "name": "Mongo's Pizza",
};
// Adds a new field restaurant_id
restaurant.insert("restaurant_id", Bson::Int32(12345));
// Removes the cuisine field
restaurant.remove("cuisine");
// Updates the name field
if let Some(name) = restaurant.get_mut("name") {
    *name = Bson::String("Mongo's Pizza Place".to_string());
}

Rust types を使用したBSONドキュメントのモデル化

Document 値を直接操作する代わりに、カスタムRustタイプを使用してコレクションデータをモデル化できます。ドライバーと bson crate はSRde と統合され、型をBSONに直列化し、 BSON を型に逆直列化します。カスタム型を mongodb::Collection のジェネリック パラメータとして使用するには、構造体から serde::Serialize と serde::Deserialize の特権を生成します。

次の例では、name、cuisine、last_updated フィールドを含む Restaurant 構造体を定義し、この構造体を使用してコレクションをパラメータ化し、現在のタイムスタンプを Restaurantドキュメントとして作成して挿入します。 last_updated 値:

#[derive(Serialize, Deserialize)]
struct Restaurant {
    name: String,
    cuisine: String,
    last_updated: DateTime,
}
async fn use_collection(client: &Client) -> mongodb::error::Result<()> {
    let coll: Collection<Restaurant> = client
        .database("sample_restaurants")
        .collection("restaurants");
    let doc = Restaurant {
        name: "Mongo's Pizza".to_string(),
        cuisine: "Pizza".to_string(),
        last_updated: DateTime::now(),
    };
    coll.insert_one(doc).await?;
    Ok(())
}

カスタム型を使用してコレクションをパラメーター化すると、ドライバーは書き込み時に型を自動的にBSONに直列化し、読み取り時にBSON を型に逆直列化します。

直列化動作をカスタマイズする

bsoncrateは、Serialize と Deserialize を実装する ObjectId や DateTime などのBSON値型を表すRustタイプを提供します。これらの型をドメイン構造体に直接埋め込むと、フィールドをBSONに直列化し、逆直列化する方法を制御できます。

次の例では、 _idフィールドに ObjectId 型を使用し、delivery_dateフィールドに DateTime 型を使用する Order 構造体を定義し、これらのフィールドが対応するBSON型として保存および取得されるようにします。

#[derive(Serialize, Deserialize)]
struct Order {
    _id: ObjectId,
    item: String,
    delivery_date: DateTime,
}

フィールドの名前変更、フィールドのスキップ、ヘルパー関数の使用方法などの追加のカスタマイズ オプションについては、「 データ モデリングと直列化のガイド 」を参照してください。

UUID 値の操作

bsoncrate は、サブタイプ0 x04 （UUID）のBSONバイナリ値に対応する UUID 型で UUID 値をモデル化します。適切な機能フラグを使用すると、uuid bson::uuid モジュールを介して crateと統合することもできます。

次の例に示すように、UUID 値をドメイン タイプに直接埋め込むことができます。

#[derive(Serialize, Deserialize)]
struct Session {
    id: Uuid,
    user_id: Uuid,
    created_at: DateTime,
}

ドライバーと bson は Serde と統合されているため、UUID 値は自動的にBSONバイナリ UUID としてシリアル化され、適切なRust型に逆シリアル化されます。

未加工のBSONデータとの連携

パフォーマンスを重視するワークロードの場合は、厳密に型指定されたRust構造体に完全に逆シリアル化せずにBSONドキュメントを検査または検証することをお勧めします。 bson crate は、この目的のために次の未加工の型を公開します。

• RawDocument - BSONドキュメントの希望するスライス（ と同様）str

• RawDocumentBUf - 所有型BSONドキュメント（ と同様）String

• RawBsonRef - 単一の未加工BSON値への参照

次の例に示すように、バイト スライスまたは Vec<u8> から RawDocumentBuf を作成し、キーでフィールドを検索できます。

fn inspect_raw(bytes: Vec<u8>) -> Result<(), mongodb::bson::error::Error> {
    let raw = RawDocumentBuf::from_bytes(bytes)?;
    if let Some(name) = raw.get_str("name").ok() {
        println!("Restaurant name: {name}");
    }
    Ok(())
}

これらの未加工 API を使用すると、ドキュメント全体を高レベルのRustタイプに割り当てたり逆直列化したりせずに、特定のフィールドにアクセスしたり、ドキュメント構造を検証したりできます。

BSON をファイルに書き込む

Documentまたは任意の Serde シリアル化可能なタイプをBSONワイヤ形式表現にシリアル化し、ディスクに書込むことができます。bson crate は、ドキュメントをBSONバイト表現にエンコードするための Document::to_VEc() メソッドを提供します。

次の例では、サンプルレストランのドキュメントをファイルに書き込みます。

fn write_bson_to_file(path: &str) -> std::io::Result<()> {
    let restaurant: Document = doc! {
        "address": {
            "street": "Pizza St",
            "zipcode": "10003",
        },
        "coord": [-73.982_419_f64, 41.579_505_f64],
        "cuisine": "Pizza",
        "name": "Mongo's Pizza",
    };
    // Encodes the document as BSON bytes
    let bytes = restaurant.to_vec()
        .expect("failed to encode document to BSON");
    fs::write(path, &bytes)
}

ファイルからの BSON を読み込む

ファイルからBSONデータを読み取るには、未加工バイトをロードして、Document または別のシリアル化可能なタイプにデコードします。 bson crate は、メモリ内バッファまたは リーダーからドキュメントを直接読み取ることをサポートしています。

次の例では、ディスクからBSONドキュメントを読み取り、デバッグ用に拡張JSONとして出力します。

fn read_bson_from_file(path: &str) -> Result<(), Box<dyn std::error::Error>> {
    let bytes = fs::read(path)?;
    let mut cursor = Cursor::new(bytes);
    // Decodes a single document from the reader
    let doc = Document::from_reader(&mut cursor)?;
    // Converts to relaxed Extended JSON for logging
    let bson_value = Bson::Document(doc);
    let json = bson_value.into_relaxed_extjson(); // serde_json::Value
    println!("{}", json);
    Ok(())
}

bsoncrateのエンコードおよびデコード ヘルパーは、 MongoDBドライバーやその他のBSONライブラリと相互運用するように設計されています。そのため、ディスク上とネットワーク上の両方で同じBSON表現を使用できます。

追加リソース

このガイドで説明されているタイプとメソッドの詳細については、次のドキュメントを参照してください。

• データ モデリングと直列化のガイド

• 、 、raw 型、UUID、拡張JSONヘルパーの bson crate APIドキュメントBsonDocument

• MongoDB Serverマニュアルの「 BSON types 」