Overview
このガイドでは、 Node.jsドライバーを使用して 一括操作 を実行する方法を学習できます。一括操作は、サーバーへの呼び出しの回数を減らすのに役立ちます。各操作のリクエストを送信する代わりに、1 つのアクション内で複数の操作を実行できます。
一括操作 を使用して、コレクションに対して複数の書込み (write) 操作を実行できます。クライアントから一括操作を実行することもできます。これにより、複数の名前空間にわたって一括書込みを実行できます。MongoDBでは、名前空間は<database>.<collection>形式のデータベース名とコレクション名で構成されています。
このガイドには、次のセクションが含まれています。
一括挿入操作 では、コレクションまたはクライアントに対して 一括挿入操作 を実行する方法について説明します。
一括置換操作 では、コレクションまたはクライアントに対して一括置換操作を実行する方法について説明します。
一括更新操作 では、コレクションまたはクライアントに対して一括更新操作を実行する方法について説明します。
一括削除操作 では、コレクションまたはクライアントに対して一括削除操作を実行する方法について説明します。
例外の処理 では、一括書込み操作のいずれかの操作が失敗した場合に発生する例外について説明します。
追加情報では、このガイドで言及されている型とメソッドのリソースとAPIドキュメントへのリンクを提供します。
重要
サーバーとドライバーのバージョンの要件
コレクション レベルの一括書き込み操作には、次のバージョンが必要です。
MongoDB Serverバージョン 3.2 以降
Node.jsドライバー バージョン 3.6 以降
クライアントレベルの一括書き込み操作には、次のバージョンが必要です。
MongoDB Serverバージョン 8.0 以降
Node.jsドライバー バージョン 6.10 以降
サンプル データ
このガイドの例では、Atlasサンプルデータセットに含まれる sample_mflixデータベース内の movies コレクションと users コレクションを使用します。MongoDB Atlasクラスターを無料で作成して、サンプルデータセットをロードする方法については、 「Atlas を使い始める」ガイドを参照してください。
一括挿入操作
一括挿入操作を実行するには、挿入するドキュメントごとに 一括操作モデル を作成します。次に、これらのモデルのリストを bulkWrite() メソッドに渡します。
このセクションでは、次のタイプの一括操作を実行する方法について説明します。
コレクションの一括挿入
コレクションに対して 一括挿入操作 を実行するには、 各操作に対して InsertOneModel を作成します。次に、コレクションで bulkWrite() メソッドを呼び出し、モデルの配列をパラメーターとして渡します。InsertOneModel を作成するには、モデルの documentフィールドを指定し、挿入するドキュメントに設定します。
例
この例では、次のアクションを実行します。
配列内の 2 つの
InsertOneModelインスタンスを指定します。各InsertOneModelは、sample_mflixデータベース内のmoviesコレクションに挿入するドキュメントを表します。moviesコレクションでbulkWrite()メソッドを呼び出し、モデルの配列をパラメーターとして渡します。挿入されたドキュメントの数を出力します。
クライアント一括挿入
複数のコレクションまたはデータベースにわたって一括挿入操作を実行するには、 各操作に対して ClientBulkWriteModel を作成します。次に、クライアントで bulkWrite() メソッドを呼び出し、モデルの配列をパラメーターとして渡します。
次の表では、挿入操作を指定するために ClientBulkWriteModel に設定できるフィールドについて説明しています。
フィールド | 説明 |
|---|---|
| The namespace in which to insert a document. Type: String |
| The operation you want to perform. For insert operations,
set this field to "insertOne".Type: String |
| The document to insert. Type: Document |
例
この例では、次のアクションを実行します。
配列内の 3 つの
ClientBulkWriteModelインスタンスを指定します。最初の 2 つのモデルはmoviesコレクションに挿入するドキュメントを表し、最後のモデルはusersコレクションに挿入するドキュメントを表します。クライアントで
bulkWrite()メソッドを呼び出し、モデルの配列をパラメーターとして渡します。挿入されたドキュメントの数を出力します。
一括置換操作
一括置換操作を実行するには、置き換えるドキュメントごとに 一括操作モデル を作成します。次に、これらのモデルのリストを bulkWrite() メソッドに渡します。
このセクションでは、次のタイプの一括操作を実行する方法について説明します。
コレクションの一括置換
コレクションに対して 一括置換操作を実行するには、 各操作に対して ReplaceOneModel を作成します。次に、コレクションで bulkWrite() メソッドを呼び出し、モデルの配列をパラメーターとして渡します。
次の表では、ReplaceOneModel で設定できるフィールドについて説明しています。
フィールド | 説明 |
|---|---|
| The filter that matches the document you want to replace. Type: Document |
| The replacement document. Type: Document |
| (Optional) The collation to use when sorting results. To learn more
about collations, see the Collations guide. Type: String or Object |
| (Optional) The index to use for the operation. To learn more about
indexes, see the Indexes on Collections guide. Type: Bson |
| (Optional) Whether a new document is created if no document matches the filter. By default, this field is set to false.Type: Boolean |
例
この例では、次のアクションを実行します。
配列内の 2 つの
ReplaceOneModelインスタンスを指定します。ReplaceOneModelインスタンスには、moviesコレクション内の映画を表すドキュメントを置き換えるための指示が含まれています。moviesコレクションでbulkWrite()メソッドを呼び出し、モデルの配列をパラメーターとして渡します。変更されたドキュメントの数を出力します。
クライアントの一括置換
複数のコレクションまたはデータベースにわたって一括置換操作を実行するには、 各操作に対して ClientBulkWriteModel を作成します。次に、クライアントで bulkWrite() メソッドを呼び出し、モデルの配列をパラメーターとして渡します。
次の表では、置換操作を指定するために ClientBulkWriteModel に設定できるフィールドについて説明しています。
フィールド | 説明 |
|---|---|
| The namespace in which to replace a document. Type: String |
| The operation you want to perform. For replace operations,
set this field to "replaceOne".Type: String |
| The filter that matches the document you want to replace. Type: Document |
| The replacement document. Type: Document |
| (Optional) The collation to use when sorting results. To learn more
about collations, see the Collations guide. Type: String or Object |
| (Optional) The index to use for the operation. To learn more about
indexes, see the Indexes on Collections guide. Type: Bson |
例
この例では、次のアクションを実行します。
配列内の 3 つの
ClientBulkWriteModelインスタンスを指定します。最初の 2 つのモデルにはmoviesコレクション内のドキュメントの置換手順が含まれ、最後のモデルにはusersコレクション内のドキュメントの置換手順が含まれています。クライアントで
bulkWrite()メソッドを呼び出し、モデルの配列をパラメーターとして渡します。変更されたドキュメントの数を出力します。
一括更新操作
一括更新操作を実行するには、実行する更新ごとに 一括操作モデル を作成します。次に、これらのモデルのリストを bulkWrite() メソッドに渡します。
このセクションでは、次のタイプの一括操作を実行する方法について説明します。
コレクションの一括更新
コレクションに対して 一括更新操作 を実行するには、 各操作に対して UpdateOneModel または UpdateManyModel を作成します。次に、コレクションで bulkWrite() メソッドを呼び出し、モデルの配列をパラメーターとして渡します。UpdateOneModel はフィルターに一致するドキュメントを1 つだけ更新し、UpdateManyModel はフィルターに一致するすべてのドキュメントを更新します。
次の表では、UpdateOneModel または UpdateManyModel で設定できるフィールドについて説明しています。
フィールド | 説明 |
|---|---|
| The filter that matches one or more documents you want to update. When
specified in an UpdateOneModel, only the first matching document will
be updated. When specified in an UpdateManyModel, all matching documents
will be updated.Type: Document |
| The update to perform. Type: Document |
| (Optional) A set of filters specifying which array elements an update
applies to if you are updating an array-valued field. Type: Array |
| (Optional) The collation to use when sorting results. To learn more about
collations, see the Collations guide. Type: Object |
| (Optional) The index to use for the operation. To learn more about
indexes, see the Indexes on Collections guide. Type: String or Object |
| (Optional) Whether a new document is created if no document matches the filter.
By default, this field is set to false.Type: Boolean |
例
この例では、次のアクションを実行します。
配列で
UpdateOneModelインスタンスとUpdateManyModelインスタンスを指定します。 これらのモデルには、moviesコレクション内の映画を表すドキュメントを更新するための指示が含まれています。moviesコレクションでbulkWrite()メソッドを呼び出し、モデルの配列をパラメーターとして渡します。変更されたドキュメントの数を出力します。
クライアントの一括更新
複数のコレクションまたはデータベースにわたって一括更新操作を実行するには、 各操作に対して ClientBulkWriteModel を作成します。次に、クライアントで bulkWrite() メソッドを呼び出し、モデルの配列をパラメーターとして渡します。
次の表では、 更新操作を指定するために ClientBulkWriteModel に設定できるフィールドについて説明しています。
フィールド | 説明 |
|---|---|
| The namespace in which to update a document. Type: String |
| The operation you want to perform. For update operations,
set this field to "updateOne" or "updateMany".Type: String |
| The filter that matches one or more documents you want to update. If
you set the model name to "updateOne", only the first matching
document is updated. If you set name to "updateMany", all
matching documents are updated.Type: Document |
| The updates to perform. Type: Document or Document[] |
| (Optional) A set of filters specifying which array elements an update
applies to if you are updating an array-valued field. Type: Document[] |
| (Optional) The collation to use when sorting results. To learn more about
collations, see the Collations guide. Type: Document |
| (Optional) The index to use for the operation. To learn more about
indexes, see the Indexes on Collections guide. Type: Document or String |
| (Optional) Whether a new document is created if no document matches the filter.
By default, this field is set to false.Type: Boolean |
例
この例では、次のアクションを実行します。
配列内の 2 つの
ClientBulkWriteModelインスタンスを指定します。最初のモデルはmoviesコレクションの更新操作数を指定し、2 番目のモデルはusersコレクションの更新 1 つの操作を指定します。クライアントで
bulkWrite()メソッドを呼び出し、モデルの配列をパラメーターとして渡します。変更されたドキュメントの数を出力します。
一括削除操作
一括削除操作を実行するには、削除操作ごとに 一括操作モデル を作成します。次に、これらのモデルのリストを bulkWrite() メソッドに渡します。
このセクションでは、次のタイプの一括操作を実行する方法について説明します。
コレクションの一括削除
コレクションに対して一括削除操作を実行するには、 各操作に対して DeleteOneModel または DeleteManyModel を作成します。次に、コレクションで bulkWrite() メソッドを呼び出し、モデルの配列をパラメーターとして渡します。DeleteOneModel はフィルターに一致するドキュメントを1 つだけ削除し、DeleteManyModel はフィルターに一致するすべてのドキュメントを削除します。
次の表では、DeleteOneModel または DeleteManyModel で設定できるフィールドについて説明しています。
フィールド | 説明 |
|---|---|
| The filter that matches one or more documents you want to delete. When
specified in a DeleteOneModel, only the first matching document will
be deleted. When specified in a DeleteManyModel, all matching documents
will be deleted.Type: Document |
| (Optional) The collation to use when sorting results. To learn more about
collations, see the Collations guide. Type: Object |
| (Optional) The index to use for the operation. To learn more about
indexes, see the Indexes on Collections guide. Type: String or Object |
例
この例では、次のアクションを実行します。
配列で
DeleteOneModelインスタンスとDeleteManyModelインスタンスを指定します。これらのモデルには、moviesコレクション内のドキュメントを削除するための手順が含まれています。moviesコレクションでbulkWrite()メソッドを呼び出し、モデルの配列をパラメーターとして渡します。削除されたドキュメントの数を出力します。
クライアントの一括削除
複数のコレクションまたはデータベースにわたって一括削除操作を実行するには、 各操作に対して ClientBulkWriteModel を作成します。次に、クライアントで bulkWrite() メソッドを呼び出し、モデルの配列をパラメーターとして渡します。
次の表では、削除操作を指定するために ClientBulkWriteModel に設定できるフィールドについて説明しています。
フィールド | 説明 |
|---|---|
| The namespace in which to delete a document. Type: String |
| The operation you want to perform. For delete operations,
set this field to "deleteOne" or "deleteMany".Type: String |
| The filter that matches one or more documents you want to delete. If
you set the model name to "deleteOne", only the first matching
document is deleted. If you set name to "deleteMany", all
matching documents are deleted.Type: Document |
| (Optional) The index to use for the operation. To learn more about
indexes, see the Indexes on Collections guide. Type: Document or String |
| (Optional) The collation to use when sorting results. To learn more about
collations, see the Collations guide. Type: Document |
例
この例では、次のアクションを実行します。
配列内の 2 つの
ClientBulkWriteModelインスタンスを指定します。最初のモデルはmoviesコレクションに対して多数の削除操作を指定し、2 番目のモデルはusersコレクションに対して 1 つの削除操作を指定します。クライアントで
bulkWrite()メソッドを呼び出し、モデルの配列をパラメーターとして渡します。変更されたドキュメントの数を出力します。
戻り値の型
BulkWriteResult
Collection.bulkWrite() メソッドは BulkWriteResultオブジェクトを返します。これは 一括操作に関する情報を提供します。
次の表は、BulkWriteResultオブジェクトのフィールドを説明します。
フィールド | 説明 |
|---|---|
| 挿入されたドキュメントの数 |
| 一致したドキュメントの数 |
| 更新されたドキュメントの数 |
| アップサートされた文書の数 |
| 削除されたドキュメントの数 |
ClientBulkWriteResult
MongoClient.bulkWrite() メソッドは、クライアントの一括書込み操作に関する情報を含む ClientBulkWriteResultオブジェクトを返します。
次の表は、ClientBulkWriteResultオブジェクトのフィールドを説明します。
フィールド | 説明 |
|---|---|
| 一括書き込みが確認されたかどうかを示すブール値値 |
| 挿入されたドキュメントの数 |
| 一致したドキュメントの数 |
| 更新されたドキュメントの数 |
| アップサートされた文書の数 |
| 削除されたドキュメントの数 |
| 成功した各挿入操作の結果 |
| 成功した各更新操作の結果 |
| 成功した各削除操作の結果 |
例外の処理
コレクションの一括書込みの例外
コレクションで呼び出された一括書き込み操作が失敗した場合、ordered オプションが true に設定されている場合、 Node.jsドライバーは MongoBulkWriteError をスローし、それ以上の操作を実行しません。ordered が false に設定されている場合、後続の操作への続行が試行されます。
MongoBulkWriteErrorオブジェクトには次のプロパティが含まれています。
プロパティ | 説明 |
|---|---|
| The error message. Type: String |
| An array of errors that occurred during the bulk write operation. Type: BulkWriteError[] |
| Write concern errors that occurred during execution of the bulk write operation. Type: WriteConnectionError[] |
| The results of any successful operations performed before the exception was
thrown. Type: BulkWriteResult[] |
| The underlying error object, which may contain more details. Type: Error |
クライアント一括書込みの例外
クライアントで呼び出される一括書き込み操作が失敗した場合、 Node.jsドライバーは MongoClientBulkWriteError を生成します。デフォルトでは 、ドライバーはエラーが発生すると後続の操作を実行しません。ordered オプションを bulkWrite() メソッドに渡し、それを false に設定すると、ドライバーは残りの操作を引き続き試行します。
MongoClientBulkWriteErrorオブジェクトには次のプロパティが含まれています。
プロパティ | 説明 |
|---|---|
| An array of documents specifying each write concern error. Type: Document[] |
| An map of errors that occurred during individual write operations. Type: Map<number, ClientBulkWriteError> |
| The partial result of the client bulk write that reflects the operation's
progress before the error. Type: ClientBulkWriteResult |
詳細情報
一括操作の詳細については、 MongoDB Serverマニュアルの「 一括書込み 」を参照してください。
API ドキュメント
このガイドで説明したメソッドや型の詳細については、次の API ドキュメントを参照してください。