カーソルからデータにアクセスする

Overview

このガイドでは、カーソルを使用してデータにアクセスする方法を学びます。

カーソルは、アプリケーションがデータベースの結果を反復処理しながら、特定の時点でメモリ内に結果のサブセットのみを保持できるようにするメカニズムです。複数のドキュメントに一致する読み取り操作では、カーソルを使用して、それらのドキュメントを一度にではなくバッチで返します。

サンプルカーソル

Find() メソッドのような読み取り操作は、操作によって一致したドキュメントを参照する Cursor を返します。カーソルを取得するには、まず配置に接続し、次の例に示すようにコレクションにアクセスします。

var uri string
if 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) カーソル

現在のゴルーチンをブロックせずにドキュメントを取得するには、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 []MyStruct
if err := cursor.All(context.TODO(), &results); err != nil {
	panic(err)
}
for _, result := range results {
	fmt.Printf("%+v\n", result)
}

{MyProperty:Beach House}
{MyProperty:Office}
{MyProperty:Bungalow}

重要

メモリ

クエリによって返されたドキュメントの数とサイズが利用可能なアプリケーションメモリを超えると、プログラムはクラッシュします。大規模な結果セットが期待される場合は、カーソルを反復的に消費する必要があります。

カーソルを閉じる

アプリケーションでカーソルが不要になったら、Close() メソッドを使用してカーソルを閉じます。このメソッドは、クライアントアプリケーションと MongoDB サーバーの両方でカーソルが消費するリソースを解放します。

defer cursor.Close(context.TODO())

注意

Next()TryNext()メソッドまたはメソッドを使用してドキュメントを個別に検索する場合は、常にカーソルを閉じて、消費するリソースを解放してください。

詳細情報

このガイドで説明した操作の詳細については、次のガイドを参照してください。

API ドキュメント

カーソルとその要素にアクセスする方法について詳しくは、次の API ドキュメントを参照してください。

戻る

ドキュメントの検索

返すドキュメントを指定する