定義
バージョン8.0の新機能。
MongoDB 8.0以降では、新しい bulkWriteコマンドを使用して、複数のコレクションに対して多くの挿入、アップデート、削除操作を 1 回のリクエストで実行できます。 既存の db.collection.bulkWrite()メソッドでは、1 回のリクエストで 1 つのコレクションのみを変更できます。
bulkWriteコマンドで各コレクションを指定するには、名前空間(データベースとコレクション名)を使用します。
互換性
このコマンドは、次の環境でホストされている配置で使用できます。
MongoDB Atlas はクラウドでの MongoDB 配置のためのフルマネージド サービスです
注意
このコマンドは、すべての MongoDB Atlas クラスターでサポートされています。すべてのコマンドに対する Atlas のサポートについては、「サポートされていないコマンド」を参照してください。
MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン
MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン
構文
コマンドの構文は次のとおりです。
db.adminCommand( { bulkWrite: 1, // Include the insert, update, and delete operations // in the ops array ops: [ { insert: <integer>, // Namespace ID index for insert operation. // Must match a namespace ID index in // ns specified later in the nsInfo array. document: <document> }, { update: <integer>, // Namespace ID index for update operation filter: <document>, updateMods: <document>, arrayFilters: [ <filterDocument0>, <filterDocument1>, ... ], multi: <bolean>, hint: <document>, constants: <document>, collation: <document> }, { delete: <integer>, // Namespace ID index for delete operation filter: <document>, multi: <boolean>, hint: <document>, collation: <document> }, ... // Additional insert, update, and delete operations in any order ... ], // Include the namespaces with collections to modify // in the nsInfo array. You can add multiple namespaces here. nsInfo: [ { ns: <string>, // Namespace (database and collection name) to modify. // Each operation namespace ID index // specified in the earlier ops array must // match a namespace ID index here. collectionUUID: <string>, encryptionInformation: <document> }, ... // Additional namespaces ... ], // Additional fields ordered: <boolean>, bypassDocumentValidation: <boolean>, comment: <string>, let: <document>, errorsOnly: <boolean>, cursor: { batchSize: <integer> }, writeConcern: <string> } )
コマンド構文では、複数の を指定できます。
ops配列内で任意の順序で挿入、アップデート、削除操作が実行できます。nsInfo配列内の操作の名前空間。 操作を名前空間と一致させるには、同じ名前空間IDインデックスを使用します。 インデックスは0から開始されます。 シャーディングされたコレクションを使用できます。
コマンドフィールド
このコマンドは、次のフィールドを使用します。
フィールド | タイプ | 必要性 | 説明 |
|---|---|---|---|
| integer | 必須 | 挿入操作の名前空間IDインデックス。この操作は、 |
| ドキュメント | 必須 | コレクションに挿入するドキュメント 。 |
| integer | 必須 | 更新操作の名前空間IDインデックス。この操作は、 |
| ドキュメント | 任意 | アップデートまたは削除操作のドキュメントを制限するクエリ セレクター。 |
| ドキュメント | 任意 | |
| ドキュメント配列 | 任意 | 配列フィールドの更新操作で変更するドキュメントを指定するフィルター ドキュメントの配列。 詳細については、「 |
| ブール値 | 任意 |
デフォルトは、 |
| ドキュメント | 任意 | ドキュメント |
| ドキュメント | 任意 | 集計パイプラインカスタム更新の制約。 |
| ドキュメント | 任意 | アップデートまたは削除操作の照合。 |
| integer | 必須 | 削除操作の名前空間IDインデックス。この操作は、 |
| string | 必須 | 操作の名前空間(データベースとコレクション)。 |
| string | 任意 | 操作のコレクションを指定するUUIDの 16進値。 |
| ドキュメント | 任意 | 操作の暗号化情報スキーマとトークン。 詳細については、「暗号化スキーマ 」を参照してください。 |
| ブール値 | 任意 |
順序付き操作は連続して実行されます。 エラーが発生した場合、残りの操作はすべてキャンセルされます。 順序付けられていない操作が並列に実行されます。 エラーが発生した場合、残りのステートメントが実行されます。 パフォーマンスを向上させるために、サーバーによって操作の順序が並べ替えられる場合があります。 したがって、アプリケーションは操作の実行順序に依存すべきではありません。 デフォルトは、 |
| ブール値 | 任意 |
デフォルトは、 |
| string | 任意 | 任意。このコマンドに添付するユーザー指定のコメント。設定すると、このコメントは以下の場所にこのコマンドの記録と合わせて表示されます。
コメントには、有効な BSON 型(string, integer, object, array など)を使用できます。 |
| ドキュメント | 任意 | 操作で参照する定数のリストを含むドキュメント。 |
| ブール値 | 任意 |
デフォルトは、 |
| integer | 任意 |
|
| string | 任意 | 操作の書込み保証 ( write concern ) 。 サーバーのデフォルトを使用する場合は省略します。 |
出力
このコマンドは、次のフィールドを含むドキュメントを返します。
フィールド | タイプ | 説明 |
|---|---|---|
| ドキュメント | コマンドの結果を持つカーソル。 |
| integer | カーソル識別子。 |
| ドキュメント配列 | 操作の結果。 |
| integer |
|
| integer |
|
| integer | エラーのコード番号。 |
| string | エラーの説明。 |
| ドキュメント | エラーのドキュメントインデックスキーの指定。 |
| ドキュメント | エラーのドキュメントインデックスキー値。 |
| integer | 操作の影響を受けるドキュメントの合計数。 |
| integer | 更新操作によって変更されたドキュメントの数。 |
| integer |
|
| integer | 挿入されたドキュメントの数。 |
| integer | 一致したドキュメントの数。 |
| integer | 変更されたドキュメントの数。 |
| integer | アップサートされたドキュメントの数。 |
| integer | 削除されたドキュメントの数。 |
| integer |
|
注意
出力フィールドは、 bulkWriteコマンドで実行する操作によって異なる場合があります。
動作
このセクションでは、 bulkWriteコマンドの動作について説明します。
複数のドキュメント フィールドと再試行可能な書込み
multiフィールドがtrueの場合、更新操作または削除操作により、ドキュメントfilterに一致するすべてのドキュメントが更新または削除されます。 falseの場合、操作によってドキュメントfilterと一致する 最初のドキュメントが更新または削除されます。 マルチドキュメントトランザクションの詳細については、「トランザクション 」を参照してください。
再試行可能な書込みを有効にするには、「再試行可能な書込み 」を参照してください。
再試行可能な書き込みと、 multiフィールドをtrueに設定すると、 bulkWrite挿入操作を使用できます。
multiフィールドをtrueに設定すると、 bulkWriteのアップデート操作と削除操作を使用できます。 ただし、 multiがtrueと再試行可能な書き込みの両方でアップデート操作または削除操作を使用することはできません。
シャーディングされたクラスターでの書込み保証 (write concern) エラー
バージョン8.1.2で変更。
bulkWrite がシャーディングされたクラスター内の mongos で実行されると、他のエラーが 1 つ以上発生した場合でも、レスポンスには常に writeConcernError が報告されます。以前のリリースでは、他のエラーによって bulkWrite が書込み保証 (write concern)エラーを報告しないことがあります。
例、ドキュメントが検証に失敗して DocumentValidationFailed エラーが発生し、書込み保証 (write concern)エラーも発生した場合、DocumentValidationFailed エラーと writeConcernError の両方が応答の最上位フィールドに返されます。
操作パフォーマンス
既存の挿入、更新、削除コマンドをbulkWriteコマンドとして書き換え、 errorsOnlyをtrueに設定すると、 bulkWriteコマンドは既存のコマンドと同様のパフォーマンスになります。 errorsOnlyをfalseに設定すると、パフォーマンスは低下します。
さらに、次のような一連のコマンドがある場合は次のようになります。
insert update delete
これらのコマンドを次の例のフラグメントで置き換えると、次のフラグメントを含むコマンドは、他のオプションに関係なく高速になります。
{ bulkWrite: 1, ops: [ insert, update, delete ] }
パフォーマンス向上のほとんどは、 ネットワークレイテンシが原因です。これは実装によって異なりますが、例は常に高速です。
例
このページの例では、 sample_mflixサンプルデータセット のデータを使用します。このデータセットを自己管理型MongoDBデプロイにロードする 方法の詳細については、「サンプルデータセットをロードする 」を参照してください。サンプルデータベースに変更を加えた場合、このページの例を実行するには、データベースを削除して再作成する必要がある場合があります。
単一名前空間一括書込みの例
次のbulkWriteの例では、1 つの名前空間を変更しています。
usersコレクションの変更
次のbulkWriteコマンドを実行して、 usersコレクションに対して挿入、アップデート、削除操作を実行します。
db.adminCommand( { bulkWrite: 1, // The ops array contains the insert, update, and delete // operations. ops: [ // Specify the namespace ID index immediately after // the insert, update, and delete text. // For example, "insert: 0" specifies the 0 namespace ID index, // which is the "sample_mflix.users" namespace in nsInfo at the end // of the example. // Insert a user. { insert: 0, document: { _id: ObjectId("67a1b2c3d4e5f6a7b8c9d0e1"), name: "Tyrion Lannister", email: "tyrion.lannister@example.com", password: "$2b$12$UREFwsRUoyF0CRqGNK0LzO0HM/jLhgUCNNIJ9RJAqMUQ74crlJ1Vu" } }, // Update the email for a user named Ned Stark. { update: 0, filter: { name: "Ned Stark" }, updateMods: { $set: { email: "ned.stark.updated@example.com" } } }, // Delete a user with a specific _id. { delete: 0, filter: { _id: ObjectId("67a1b2c3d4e5f6a7b8c9d0e1") } } ], // The nsInfo array contains the namespace to apply the // previous operations to. nsInfo: [ { ns: "sample_mflix.users" } // Namespace ID index is 0. ] } )
usersコレクションは sample_mflixデータベースにあるため、ns名前空間は "sample_mflix.users" です。名前空間IDインデックスは 0 で、これは ops 配列の挿入、アップデート、削除操作の最初のフィールドに設定されています。
出力を確認します。
さまざまなok: 1フィールドとnErrors: 0を例次のbulkWriteの出力は、すべての操作が成功したことを示しています。
{ cursor: { id: Long('0'), firstBatch: [ { ok: 1, idx: 0, n: 1 }, { ok: 1, idx: 1, n: 1, nModified: 1 }, { ok: 1, idx: 2, n: 1 } ], ns: 'admin.$cmd.bulkWrite' }, nErrors: 0, nInserted: 1, nMatched: 1, nModified: 1, nUpserted: 0, nDeleted: 1, ok: 1 }
出力フィールドの詳細については、以前の出力セクションを参照してください。
複数の名前空間の一括書込みの例
bulkWriteコマンドで複数の名前空間を指定できます。
次のbulkWriteの例には、2 つの名前空間に対する挿入、アップデート、削除操作が含まれています。
コレクションの変更
次の bulkWrite コマンドを実行して、users コレクションと sample_mflix.theaters コレクションに対して挿入、アップデート、削除操作を実行します。
db.adminCommand( { bulkWrite: 1, // The ops array contains the insert, update, and delete // operations. ops: [ // Specify the namespace ID indexes immediately after // the insert, update, and delete. For example, "insert: 0" // specifies the 0 namespace ID index, which is the "sample_mflix.users" // namespace. And, "insert: 1" specifies "sample_mflix.theaters". // Insert users. // Namespace ID is 0 for "sample_mflix.users", which // is specified as "insert: 0". { insert: 0, document: { _id: ObjectId("67a1b2c3d4e5f6a7b8c9d0e7"), name: "Sansa Stark", email: "sansa.stark@example.com", password: "$2b$12$UREFwsRUoyF0CRqGNK0LzO0HM/jLhgUCNNIJ9RJAqMUQ74crlJ1Vu" } }, { insert: 0, document: { _id: ObjectId("67a1b2c3d4e5f6a7b8c9d0e8"), name: "Bran Stark", email: "bran.stark@example.com", password: "$2b$12$UREFwsRUoyF0CRqGNK0LzO0HM/jLhgUCNNIJ9RJAqMUQ74crlJ1Vu" } }, // Update the email for a user. { update: 0, filter: { name: "Ned Stark" }, updateMods: { $set: { email: "lord.stark@example.com" } } }, // Delete users with a specific email pattern. { delete: 0, filter: { email: { $regex: "bran.stark" } } }, // Update theaters. // Namespace ID is 1 for "sample_mflix.theaters". { update: 1, filter: { theaterId: 1000 }, updateMods: { $set: { "location.address.city": "Minneapolis" } } }, // Delete a theater with a specific _id. { delete: 1, filter: { _id: ObjectId("59a47286cfa9a3a73e51e72c") } }, // Delete theaters in a specific state. { delete: 1, filter: { "location.address.state": "VT" }, multi: true } ], // Namespaces nsInfo: [ { ns: "sample_mflix.users" }, // Namespace ID index is 0. { ns: "sample_mflix.theaters" } // Namespace ID index is 1. ] } )
出力を確認します。
次のbulkWriteの出力の例は、操作が成功したことを示しています。
{ cursor: { id: Long('0'), firstBatch: [ { ok: 1, idx: 0, n: 1 }, { ok: 1, idx: 1, n: 1 }, { ok: 1, idx: 2, n: 1, nModified: 1 }, { ok: 1, idx: 3, n: 1 }, { ok: 1, idx: 4, n: 1, nModified: 1 }, { ok: 1, idx: 5, n: 1 }, { ok: 1, idx: 6, n: 2 } ], ns: 'admin.$cmd.bulkWrite' }, nErrors: 0, nInserted: 2, nMatched: 2, nModified: 2, nUpserted: 0, nDeleted: 4, ok: 1 }