db.コレクション.bulkWrite()（mongoshメソッド）

パラメーター

bulkWrite() メソッドは次のパラメータを取ります。

書込み操作

db.collection.bulkWrite( [
   { insertOne : { "document" : <document> } }
] )

db.collection.bulkWrite( [
   { updateOne :
      {
         "filter": <document>,
         "update": <document or pipeline>,
         "upsert": <boolean>,
         "collation": <document>,
         "arrayFilters": [ <filterdocument1>, ... ],
         "hint": <document|string>
      }
   }
] )

db.collection.bulkWrite( [
   { updateMany :
      {
         "filter" : <document>,
         "update" : <document or pipeline>,
         "upsert" : <boolean>,
         "collation": <document>,
         "arrayFilters": [ <filterdocument1>, ... ],
         "hint": <document|string>
      }
   }
] )

db.collection.bulkWrite([
   { replaceOne :
      {
         "filter" : <document>,
         "replacement" : <document>,
         "upsert" : <boolean>,
         "collation": <document>,
         "hint": <document|string>
      }
   }
] )

db.collection.bulkWrite([
   { deleteOne : {
      "filter" : <document>,
      "collation" : <document>                   // Available starting in 3.4
   } }
] )

db.collection.bulkWrite([
   { deleteMany: {
      "filter" : <document>,
      "collation" : <document>                    // Available starting in 3.4
   } }
] )

_id フィールド

ドキュメントで _id フィールドが指定されていない場合は、 mongod で _id フィールドが追加され、ドキュメントの挿入またはアップサートの前にユニークな ObjectId() が割り当てられます。ほとんどのドライバーでは ObjectId が作成され、 _id フィールドが挿入されますが、ドライバーやアプリケーションでこの処理が行われない場合は、 mongod で_id の作成と入力が行われます。

ドキュメントに _id フィールドが含まれる場合に重複キー エラーを回避するには、_id 値がコレクション内で一意になるようにする必要があります。

更新操作または置換操作では、元のドキュメントと異なる _id 値を指定することはできません。

操作の実行

ordered パラメーターは、操作が連続して実行されるか、任意の順序で実行されるかを制御します。

ordered : true（デフォルトでは ）の場合、操作は連続して実行されます。エラーが発生すると、後続の操作は実行されません。

ordered : false を使用すると、 操作は並行して実行される可能性があります。一部の操作が失敗した場合でも、エラーのないすべての操作が完了します。

各グループ内の操作の数は、データベースの maxWriteBatchSize の値を超えることはできません。maxWriteBatchSize のデフォルト値は 100,000 です。この値は hello.maxWriteBatchSize フィールドに表示されます。

この制限により、エラー メッセージの肥大化の問題が回避されます。この制限を超えるグループがある場合、クライアント ドライバーによって、操作数が制限値以下となる小さなグループに分割されます。たとえば、maxWriteBatchSize の値が 100,000 の場合、キューに 200,000 回の操作が含まれていると、ドライバによってそれぞれの操作回数が 100,000 回となるグループが 2 個作成されます。

1 つのバッチのエラーレポートが大きくなりすぎた場合、MongoDB では残りのすべてのエラーメッセージを切り捨てて空の文字列にします。少なくとも 2 つのエラーメッセージがあり、合計サイズが 1MB を超える場合、これらは切り捨てられます。

サイズとグループ化の仕組みは内部的パフォーマンスの細部に該当し、今後のバージョンで変更される可能性があります。

シャーディングされたコレクションで ordered 操作リストを実行すると、通常、 unordered リストの実行よりも時間がかかります。これは、ordered リストでは毎回の操作で前の操作の完了を待機する必要があるためです。

上限付きコレクション

bulkWrite() 上限付きコレクションには制限があります。

• updateOne 更新によってドキュメントサイズが増加する場合には、 updateMany と により WriteError がスローされます。

• replaceOne では、置き換えドキュメントが元のドキュメントよりも大きい場合は WriteError がスローされます。

• deleteOne と deleteMany は、上限付きコレクションに対して WriteError をスローします。

Error Handling

bulkWrite() は、エラー時に BulkWriteError の例外をスローします。「 トランザクション内でのエラー処理 」を参照してください。

書込み保証（ write concern ） エラーを除き、順序付き操作はエラーの発生後に停止します。一方、順序なし操作は、トランザクション内で実行されない限り、キューにある残りの書込み操作の処理を続行します。 「トランザクション内でのエラー処理 」を参照してください。

書込み保証エラーは writeConcernErrors フィールドに表示され、その他すべてのエラーは writeErrors フィールドに表示されます。エラーが発生した場合、挿入された_id 値の代わりに、成功した書き込み操作の数が表示されます。実行順序の決まった操作では、発生したエラーが 1 つだけ表示され、実行順序のない操作では 1 つの配列内のそれぞれのエラーが表示されます。

トランザクション

bulkWrite() は分散トランザクション内で使用できます。

順序付き一括書込みの例

bulkWrite() の操作順序とエラー処理を理解することが重要です。デフォルトでは 、bulkWrite() は順序が付いたリストの操作を実行します。

• 操作は連続して実行されます。

• 操作にエラーがある場合、その操作および後続の操作は実行されません。

• エラー操作が完了する前に一覧表示された操作。

bulkWrite() の例では、 pizzasコレクションを使用します。

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

The following bulkWrite() example runs these operations on the pizzas collection:

• insertOne を使用して 2 つのドキュメントを追加します。

• updateOne を使用してドキュメントをアップデートします。

• deleteOne を使用してドキュメントを削除します。

• replaceOne を使用してドキュメントを置換します。

try {
   db.pizzas.bulkWrite( [
      { insertOne: { document: { _id: 3, type: "beef", size: "medium", price: 6 } } },
      { insertOne: { document: { _id: 4, type: "sausage", size: "large", price: 10 } } },
      { updateOne: {
         filter: { type: "cheese" },
         update: { $set: { price: 8 } }
      } },
      { deleteOne: { filter: { type: "pepperoni"} } },
      { replaceOne: {
         filter: { type: "vegan" },
         replacement: { type: "tofu", size: "small", price: 4 }
      } }
   ] )
} catch( error ) {
   print( error )
}

完了した操作の概要を含む出力例を示します。

{
   acknowledged: true,
   insertedCount: 2,
   insertedIds: { '0': 3, '1': 4 },
   matchedCount: 2,
   modifiedCount: 2,
   deletedCount: 1,
   upsertedCount: 0,
   upsertedIds: {}
}

前の bulkWrite() の例を実行中前に、コレクションに _id が 4 のドキュメントがすでに含まれていた場合、2 番目の insertOne操作に対して次の重複キー例外が返されます。

writeErrors: [
   WriteError {
      err: {
         index: 1,
         code: 11000,
         errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 4 }',
         op: { _id: 4, type: 'sausage', size: 'large', price: 10 }
      }
   }
],
result: BulkWriteResult {
   result: {
      ok: 1,
      writeErrors: [
         WriteError {
            err: {
               index: 1,
               code: 11000,
               errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 4 }',
               op: { _id: 4, type: 'sausage', size: 'large', price: 10 }
            }
         }
      ],
      writeConcernErrors: [],
      insertedIds: [ { index: 0, _id: 3 }, { index: 1, _id: 4 } ],
      nInserted: 1,
      nUpserted: 0,
      nMatched: 0,
      nModified: 0,
      nRemoved: 0,
      upserted: []
   }
}

bulkWrite() の例は順序付けられているため、最初の insertOne操作のみが完了します。

エラーのないすべての操作を完了するには、ordered を false に設定して bulkWrite() を実行します。の例については、次のセクションを参照してください。

順序付けなし一括書込みの例

順序付けられていない bulkWrite() を指定するには、ordered を false に設定します。

順序付けられていない bulkWrite() の操作リストでは次のようになります。

• 操作は並行して実行可能です（保証はされません）。詳細については順序付き操作と順序なし操作を参照してください。

• エラーのある操作は完了しません。

• エラーのないすべての操作が完了します。

pizzas コレクションの例を引き続き使用し、コレクションの削除と再作成を行います。

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

次の例を参照してください。

• bulkWrite() は、pizzasコレクションに対して順序のない操作を実行します。

• 2番目の insertOne 操作の _id は 1 番目の insertOneと同じであるため、重複キー エラーが発生します。

try {
   db.pizzas.bulkWrite( [
      { insertOne: { document: { _id: 3, type: "beef", size: "medium", price: 6 } } },
      { insertOne: { document: { _id: 3, type: "sausage", size: "large", price: 10 } } },
      { updateOne: {
         filter: { type: "cheese" },
         update: { $set: { price: 8 } }
      } },
      { deleteOne: { filter: { type: "pepperoni"} } },
      { replaceOne: {
         filter: { type: "vegan" },
         replacement: { type: "tofu", size: "small", price: 4 }
      } }
   ],
   { ordered: false } )
} catch( error ) {
   print( error )
}

出力例には、重複キー エラーと完了した操作の概要が含まれています。

writeErrors: [
   WriteError {
      err: {
         index: 1,
         code: 11000,
         errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 3 }',
         op: { _id: 3, type: 'sausage', size: 'large', price: 10 }
      }
   }
],
result: BulkWriteResult {
   result: {
      ok: 1,
      writeErrors: [
         WriteError {
            err: {
               index: 1,
               code: 11000,
               errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 3 }',
               op: { _id: 3, type: 'sausage', size: 'large', price: 10 }
            }
         }
      ],
      writeConcernErrors: [],
      insertedIds: [ { index: 0, _id: 3 }, { index: 1, _id: 3 } ],
      nInserted: 1,
      nUpserted: 0,
      nMatched: 2,
      nModified: 2,
      nRemoved: 1,
      upserted: []
   }
}

重複キー エラーのため、2 番目の insertOne操作は正常に実行されません。順序付けられていない bulkWrite() では、エラーのないすべての操作が完了します。

シャーディングされたクラスターでの書込み保証 (write concern) エラー

bulkWrite() がシャーディングされたクラスター内の mongos で実行されると、他のエラーが 1 つ以上発生した場合でも、レスポンスには常に writeConcernError が報告されます。以前のリリースでは、他のエラーによって bulkWrite() が書込み保証 (write concern)エラーを報告しないことがあります。

例、ドキュメントが検証に失敗して DocumentValidationFailed エラーが発生し、書込み保証 (write concern)エラーも発生した場合、DocumentValidationFailed エラーと writeConcernError の両方が応答の最上位フィールドに返されます。

書込み保証を使用した一括書込みの例

pizzas コレクションの例を引き続き使用し、コレクションの削除と再作成を行います。

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

次の bulkWrite() の例では、pizzasコレクションに対して操作を実行し、"majority"書込み保証 (write concern)を100 ミリ秒のタイムアウトで設定します。

try {
   db.pizzas.bulkWrite( [
      { updateMany: {
         filter: { size: "medium" },
         update: { $inc: { price: 0.1 } }
      } },
      { updateMany: {
         filter: { size: "small" },
         update: { $inc: { price: -0.25 } }
      } },
      { deleteMany: { filter: { size: "large" } } },
      { insertOne: {
         document: { _id: 4, type: "sausage", size: "small", price: 12 }
      } } ],
      { writeConcern: { w: "majority", wtimeout: 100 } }
   )
} catch( error ) {
   print( error )
}

レプリカ セット ノードの大半が操作を確認するまでの時間が wtimeout を超えると、この例では書込み保証エラーと完了した操作の概要が返されます。

result: BulkWriteResult {
   result: {
      ok: 1,
      writeErrors: [],
      writeConcernErrors: [
         WriteConcernError {
            err: {
               code: 64,
               codeName: 'WriteConcernTimeout',
               errmsg: 'waiting for replication timed out',
               errInfo: { wtimeout: true, writeConcern: [Object] }
            }
         }
      ],
      insertedIds: [ { index: 3, _id: 4 } ],
      nInserted: 0,
      nUpserted: 0,
      nMatched: 2,
      nModified: 2,
      nRemoved: 0,
      upserted: [],
      opTime: { ts: Timestamp({ t: 1660329086, i: 2 }), t: Long("1") }
   }
}