BSON との連携
Overview
このガイドでは、{0 ライブラリを使用して、 C++ドライバーを使用してBSONデータを保存し、操作する方法を学習できます。bsoncxx
BSON データ形式
MongoDBは、 BSON （Binary JSON）データ形式を使用してドキュメントを保存し、リモートプロシージャコールを行います。このデータ形式には、すべてのJSONデータ構造タイプが含まれ、日付、異なるサイズの整数、 値、バイナリObjectId データなどの追加のタイプをサポートします。サポートされているタイプの完全なリストについては、 MongoDB Serverマニュアルの BSON types ページを参照してください。
BSONの値とビュー
多くのC++ドライバー メソッドは、 BSONドキュメントを引数として受け入れます。 bsoncxx ライブラリは、 BSONドキュメントを表すために使用できる 2 つのデータ型（bsoncxx::document::value と bsoncxx:document::view）を提供します。
document::valueオブジェクトは、基礎となるバッファのデータを所有するBSONドキュメントを表します。 document::valueオブジェクトをC++ドライバー メソッドに渡すと、メソッドはBSONドキュメントデータのコピーを受け取ります。 document::valueオブジェクトがスコープの範囲外になると、その基礎となるバッファは解放されます。
Tip
document::valueビルダーでヘルパーメソッドを呼び出すことで、ビルダ型を 型に変換できます。ビルダのタイプの詳細については、このガイドの「 BSONドキュメントのビルド 」セクションを参照してください。
document::viewオブジェクトは、document::value への非所有のビューを提供します。このタイプでは、ドキュメントの基礎となるデータを所有せずに、 BSONドキュメントの内容を読み取って操作できます。 document::viewオブジェクトをC++ドライバー メソッドに渡すと、メソッドは基礎となるドキュメントのデータをコピーせずに使用できます。 document::valueオブジェクトで view() メソッドを呼び出すことでビューを作成できます。
Tip
過剰なコピーを避けるために、可能であればドキュメントを ビュー で渡すことをお勧めします。
一部のC++ドライバー メソッドはdocument::view_or_value 型の引数を受け入れます。これらのメソッドには、document::view document::valueまたはdocument::value オブジェクトのいずれかを渡すことができます。ドキュメントの所有権をメソッドに転送するには、rvalue 参照によって 引数を渡す必要があります。
重要
document::view は、参照する document::value よりも優先されることはできません。基礎のバッファが解放された後に document::view が document::value を使用する場合、ビューにはダンプするポインターが含まれます。ダンプするポインターにアクセスすると、アプリケーションのクラッシュ、データの破損、その他の予測できない動作が発生する可能性があります。
BSONドキュメントの構築
このセクションでは、次のインターフェースを使用してBSONドキュメントを作成する方法を説明します。
リストビルダ
builder::list インターフェースは、ドキュメントと配列を構築するためのJSONのようなビルダです。リスト ビルダを使用してBSONドキュメントを作成するには、キーと値のペアのリストをコンストラクターに渡して bsoncxx::builder::listオブジェクトを構築します。リスト ビルダは、キーと値のリストが次の要件を満たす場合にBSONドキュメントを作成します。
リストには偶数の要素があります。
各キーは
stringタイプで、各値はbson_value::valueタイプであるか、または暗黙的に 1 に変換できます。
上記の要件が満たされない場合、リストビルダは配列を作成します。
この例では、リスト ビルダを使用して次のアクションを実行しています。
ドキュメントを構築する
配列を構築する
ビルダードキュメントを
bsoncxx::document::valueオブジェクトに変換する
bsoncxx::builder::list course_doc = { "title", "Poetry", "department", "English" }; bsoncxx::builder::list courses_array = { "Poetry", "Literature", "Creative Writing" }; bsoncxx::document::value course{course_doc.view().get_document().value};
基本ビルダ
builder::basic インターフェースは、 BSONドキュメントを構築するためのビルダ スタイルのインターフェースです。基本ビルダを使用してBSONドキュメントを作成するには、キーと値のペア オブジェクトのリストでドキュメントのデータを指定します。キーと値を builder::basic::kvp() メソッドに渡すことで、これらのキーと値のペア オブジェクトを作成できます。キーは string 型で、値は bson_value::value 型であるか、または暗黙的に 1 に変換可能なものである必要があります。
基本ビルダーの make_document() メソッドを使用してドキュメントを作成し、次のコードに示すように、単一のステートメントで bsoncxx::document::value に変換することができます。
using bsoncxx::builder::basic::make_document; using bsoncxx::builder::basic::kvp; bsoncxx::document::value course = make_document( kvp("title","Poetry"), kvp("department","English"));
あるいは、 基本的なビルダオブジェクトにキーと値のペアを追加することで、複数のステートメントにわたってBSONドキュメントを作成することもできます。この例では、基本ビルダを使用して次のアクションを実行しています。
builder::basic::documentオブジェクトを初期化append()メソッドを使用してドキュメントにデータを保存するビルダードキュメントを
bsoncxx::document::valueオブジェクトに変換する
using bsoncxx::builder::basic::kvp; auto course_builder = bsoncxx::builder::basic::document{}; course_builder.append(kvp("title", "Literature"), kvp("department", "English")); bsoncxx::document::value course{course_builder.extract()};
ストリームビルダ
重要
ストリーム ビルダではなく、基本ビルダを使用することをお勧めします。
新しい各値を適切に追加するには、ストリーム ビルダが現在のドキュメントの状態を追跡する必要があります。この状態が変化した後は、初期ストリーム ビルダを再利用することはできません。その結果、複数のステートメントにまたがってドキュメントを構築する場合は、すべての中間値を新しい変数に保存する必要があります。こうした複雑さのため、ストリーム ビルダの使用は推奨されません。
builder::stream インターフェースは、複雑なBSONオブジェクトを構築するためのストリーミングインターフェースです。ストリーム ビルダを使用してBSONドキュメントを作成するには、builder::stream::documentオブジェクトを初期化します。次に、<< 演算子を使用して、キーと値をビルダにストリーミングできます。
次のコードは、ストリーム ビルダを使用して次のアクションを実行する方法を示しています。
ドキュメントを構築する
ドキュメントを
bsoncxx::document::valueオブジェクトに変換する
auto course_builder = bsoncxx::builder::stream::document{}; course_builder << "title" << "Creative Writing" << "credits" << bsoncxx::types::b_int32{4}; bsoncxx::document::value course{course_builder.extract()};
次の例に示すように、builder::stream::finalize トークンを使用してストリームを bsoncxx::document::value に変換することもできます。
using bsoncxx::builder::stream::document; using bsoncxx::builder::stream::finalize; bsoncxx::document::value doc = document{} << "title" << "Literature" << finalize;
BSONドキュメントの出力
BSONは、人間が判読できないJSONドキュメントのバイナリ エンコードされた直列化化です。 BSONドキュメントの内容を人間が判読できる形式でプレビューするには、bsoncxx::to_json() メソッドを使用してドキュメントを拡張JSON形式に変換します。
拡張JSON形式は、 BSONデータ型の string 表現を含む標準JSONの拡張機能です。詳細については、 MongoDB Serverマニュアルの「 MongoDB拡張JSON 」ガイドを参照してください。
bsoncxx::to_json() メソッドは、変換するBSONドキュメントの bsoncxx::document::view を受け入れます。このメソッドは、 BSONドキュメントを 拡張JSON形式で表す std::stringオブジェクトを返します。
次のコードは、 BSONドキュメントを拡張JSON形式に変換して結果を出力する方法を示しています。
bsoncxx::document::value course = make_document( kvp("title","Screenwriting"), kvp("department","English")); std::cout << bsoncxx::to_json(course.view()) << std::endl;
{ "title" : "Screenwriting", "department" : "English" }
詳細情報
このガイドで言及されている概念の詳細については、次のサーバー マニュアル エントリを参照してください。
読み取り操作の実行の詳細については、「 MongoDBからのデータの読み取り 」を参照してください。
集計操作の実行の詳細については、「集計によるデータの変換 」ガイドを参照してください。
API ドキュメント
このガイドで言及されている型とメソッドの詳細については、次のAPIドキュメントを参照してください。