Overview
このガイドでは、カーソルを使用してデータにアクセスする方法を学びます。
カーソルは、アプリケーションがデータベースの結果を反復処理しながら、特定の時点でメモリ内に結果のサブセットのみを保持できるようにするメカニズムです。複数のドキュメントに一致する読み取り操作では、カーソルを使用して、それらのドキュメントを一度にではなくバッチで返します。
サンプル カーソル
Find() メソッドのような読み取り操作は、操作によって一致したドキュメントを参照する Cursor を返します。カーソルを取得するには、まず配置に接続し、次の例に示すようにコレクションにアクセスします。
var uri stringif uri = os.Getenv("MONGODB_URI"); uri == "" { log.Fatal("You must set your 'MONGODB_URI' environment variable. See\n\t https://www.mongodb.com/ja-jp/docs/drivers/go/current/usage-examples/")}
client, err := mongo.Connect(options.Client().ApplyURI(uri))
if err != nil { panic(err)}defer func() { if err := client.Disconnect(context.TODO()); err != nil { panic(err) }}()
coll := client.Database("db").Collection("sample_data")このガイドの例では、次の MyStruct 構造体を使用して、コレクション内のドキュメントをモデル化します。
type MyStruct struct { MyProperty string}次のコードはコレクションにサンプル ドキュメントを挿入します。
docs := []any{ MyStruct{MyProperty: "Beach House"}, MyStruct{MyProperty: "Office"}, MyStruct{MyProperty: "Bungalow"},}
result, err := coll.InsertMany(context.TODO(), docs)if err != nil { panic(err)}カーソルを取得するには、コレクションで Find() メソッドを呼び出してクエリを実行し、カーソルを返します。次の例では、空のフィルターを渡してコレクション内のすべてのドキュメントに一致させ、結果のカーソルを cursor 変数に割り当てます。
cursor, err := coll.Find(context.TODO(), bson.D{})if err != nil { panic(err)}このガイドの各セクションでは、この cursor 変数を使用します。ドライバーは、カーソルが参照するドキュメントを MyStruct 構造体にアンマーシャルします。
重要
カーソルは、 goroutine セーフではありません。 複数の goroutine で同時に同じカーソルを使用しないでください。
ドキュメントを個別に検索する
現在のゴルーチンをブロックしながらカーソルからドキュメントを個別に検索するには、Next() メソッドを使用します。
このメソッドでは、次の条件がすべて満たされた場合にドキュメントが返されます。
ドキュメントは現在利用可能であるか、または今後利用可能になります。
ドライバーはエラーをスローしませんでした。
コンテキストは期限切れになりませんでした。
for cursor.Next(context.TODO()) { var result MyStruct if err := cursor.Decode(&result); err != nil { log.Fatal(err) } fmt.Printf("%+v\n", result)}if err := cursor.Err(); err != nil { log.Fatal(err)}追尾可能 (tailable) カーソル
現在の goroutine をブロックせずにドキュメントの取得を試みるには、TryNext() メソッドを使用します。追尾可能 (tailable) カーソルを繰り返す場合は、このアプローチを使用します。
このメソッドでは、次の条件がすべて満たされた場合にドキュメントが返されます。
ドキュメントは現在利用可能です。
ドライバーはエラーをスローしませんでした。
コンテキストは期限切れになりませんでした。
for { if cursor.TryNext(context.TODO()) { var result MyStruct if err := cursor.Decode(&result); err != nil { log.Fatal(err) } fmt.Printf("%+v\n", result) continue }
if err := cursor.Err(); err != nil { log.Fatal(err) } if cursor.ID() == 0 { break }}すべてのドキュメントを検索する
すべてのクエリ結果をスライスに取り込むには、All() メソッドを使用します。
var results []MyStructif err := cursor.All(context.TODO(), &results); err != nil { panic(err)}for _, result := range results { fmt.Printf("%+v\n", result)}重要
メモリ
クエリによって返されたドキュメントの数とサイズが利用可能なアプリケーション メモリを超えると、プログラムはクラッシュします。大規模な結果セットが予想される場合は、カーソルを反復的に消費する必要があります。
カーソルを閉じる
アプリケーションでカーソルが不要になったら、Close() メソッドを使用してカーソルを閉じます。このメソッドは、クライアント アプリケーションと MongoDB サーバーの両方でカーソルが消費するリソースを解放します。
defer cursor.Close(context.TODO())注意
Next() または TryNext() メソッドを使用してドキュメントを個別に検索する場合は、カーソルが消費するリソースを解放するため、必ずカーソルを閉じてください。
詳細情報
このガイドで説明した操作の詳細については、次のガイドを参照してください。
API ドキュメント
カーソルとその要素にアクセスする方法について詳しくは、次の API ドキュメントを参照してください。