BSON との連携
Overview
このガイドでは、Go ドライバーが BSON 値と Go 値の間の変換を処理する方法について学習できます。 Go 値を BSON に変換するプロセスはマーシャリングと呼ばれ、その逆のプロセスはアン マーシャリングと呼ばれます。
Go ドライバーが BSON データを表す方法について詳しく知りたい場合、またはデフォルトのマーシャリングおよびアン マーシャリング動作を調整する必要がある場合は、このガイドをお読みください。
データ型
MongoDB では、BSON と呼ばれるバイナリ形式でドキュメントを保存することで、簡単かつ柔軟なデータ処理を可能にしています。
Go ドライバーは、BSON データを操作するための 4 つの主要なタイプを提供します。
D：BSON ドキュメント（スライス）の順序付けられた表現M：BSON ドキュメント（マップ）の順序付けられていない表現A：BSON 配列の順序付けられた表現E：D 型内部の 1 つの要素
次の例では、 bson.Dタイプを使用してクエリフィルターを作成し、 quantityフィールドの値が100より大きいドキュメントに一致させる方法を示しています。
filter := bson.D{{"quantity", bson.D{{"$gt", 100}}}}
GoDriver がBSON データを処理する方法の詳細については、「BSON パッケージAPI ドキュメント 」を参照してください。
構造タグ
Go では、構造体はデータ型が宣言されたデータフィールドの集まりです。 Go Driver は、 構成可能なコーデック システム を使用して、構造体やその他のネイティブ Go 型を BSON との間でマーシャリング/アンマーシャリングできます 。
Go ドライバーのデフォルトのマーシャリングおよびアン マーシャリング動作は、構造体フィールドに添付される任意のメタデータである構造体タグを使用して変更できます。 構造体タグの最も一般的な用途は、構造体フィールドに対応する BSON ドキュメント内のフィールド名を指定することです。 次の表では、Go ドライバーで使用できる追加の構造体タグについて説明しています。
構造体タグ | 説明 |
|---|---|
omitempty | フィールドタイプに対応するゼロ値が設定されている場合、フィールドはマーシャリングされません。 |
minsize | フィールドタイプが int64、uint、uint32、または uint64 で、フィールドの値が符号付き int32 に収まる場合、フィールドは BSON int64 ではなく BSON int32 としてシリアル化されます。 値が符号付き int32 に収まらない場合、このタグは無視されます。 |
truncate | フィールドタイプが float 数値型でない場合、そのフィールドにマーシャリングされていない BSON 倍数は小数点で切り捨てられます。 |
inline | フィールドタイプが構造体フィールドまたはマップ フィールドの場合、フィールドはマーシャリング時にフラット化され、アンマーシャリング時にフラット化が解除されます。 |
struct タグからの追加指示がない場合、Go ドライバーは次のルールを使用して構造体をマーシャリングします。
Go Driver はエクスポートされたフィールドのみをマーシャリングおよびアンマーシャリングします。
Go Driver は、対応する構造体フィールドの小文字を使用して BSON キーを生成します。
Go Driver は埋め込まれた構造体フィールドをサブドキュメントとしてマーシャリングします。 各キーは、フィールドタイプの小文字です。
Go ドライバーは、ポインターが nil 以外の場合、ポインターフィールドを基礎の型としてマーシャリングします。 ポインターが nil の場合、ドライバーは BSON null 値としてマーシャリングします。
Go ドライバーはマーシャリング時に、 これらの D/M 型マッピング に従います
interface{}型のフィールドの場合このドライバーでは、interface{}フィールドにアンマーシャルされた BSON ドキュメントをDタイプとしてアンマーシャリングします。
アン マーシャリング
BSON ドキュメントのマーシャリングを解除するには、FindOneメソッドの結果または任意の *mongo.Cursor インスタンスに対して Decode() メソッドを使用します。
Decode()メソッドは、以下のいずれかの値を含むerror型を返します。
nilドキュメントがクエリと一致し、ドキュメントの取得およびアン マーシャリングでエラーが発生しなかった場合。ドライバーがドキュメントを取得したのに結果をアン マーシャリングできなかった場合、
Decode()メソッドはアン マーシャリング エラーを返します。FindOne()メソッドの実行中にドキュメントを取得する際にエラーが発生した場合、エラーはDecode()メソッドに伝わり、Decode()メソッドはエラーを返します。
FindOne()メソッドによって返される SingleResult型で使用すると、クエリフィルターに一致するドキュメントがない場合、Decode() は ErrNoDocuments エラーを返すこともできます。
次の例では、Decode() メソッドを使用して単純な FindOne() 操作の結果をアン マーシャリングして読み取る方法を示しています。
coll := client.Database("school").Collection("students") filter := bson.D{{"age", 8}} var result bson.D err := coll.FindOne(context.TODO(), filter).Decode(&result) fmt.Println(result)
Cursor タイプは All() メソッドも使用します。これは、カーソルに格納されているすべてのドキュメントを同時に配列にアン マーシャリングします。
bson パッケージには、[]byte タイプの BSON エンコード データを操作する Marshal() メソッドと Unmarshal() メソッドのファミリーが含まれています。
次のコードは、bsonパッケージのメソッドを使用して、BSON をユーザー定義の構造体にアン マーシャリングする方法を示しています。
type Item struct { Category string Quantity int32 } doc, err := bson.Marshal(bson.D{{"category", "plate"}, {"quantity", 6}}) var test Item err = bson.Unmarshal(doc, &test) fmt.Printf("Unmarshalled Struct:\n%+v\n", test)
注意
Raw型を使用すると、BSON ドキュメントのバイト スライスを Go 値にアンマーシャリングせずに要素を取得できます。 これは、BSON ドキュメント全体をアンマーシャリングせずに個々の要素を検索する必要がある場合に役立ちます。
型で使用されるマーシャリングとアンマーシャリングCursor メソッドの詳細については、 カーソル API ドキュメント を参照してください。
パッケージでのマーシャリングとアンマーシャリングbson メソッドの詳細については、BSONAPI ドキュメント を参照してください。