db.collection.insert()

書込み保証 (write concern)

insert() メソッドは、デフォルトの書込み保証（write concern）を使用する insert コマンドを使用します。デフォルト以外の書込み保証を指定するには、オプション パラメーターに書込み保証を含めます。

コレクションを作成

コレクションが存在しない場合、insert() メソッドによってコレクションが作成されます。

_id フィールド

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

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

トランザクション

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

Oplog エントリ

db.collection.insert()操作によってドキュメントが正常に挿入されると、その操作によってoplog （操作ログ）にエントリが追加されます。 操作が失敗した場合、その操作によって oplog にエントリが追加されることはありません。

_id フィールドを指定せずにドキュメントを挿入

次の例では、 insert()メソッドに渡されるドキュメントに_idフィールドが含まれていません。

db.products.insert( { item: "card", qty: 15 } )

挿入中に、mongod は_id フィールドを作成し、挿入されたドキュメントによって検証されたユニークな ObjectId() 値をそのフィールドに割り当てます。

{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }

ObjectId 値は、操作が実行されるマシンと時間に固有であるため、実際の値は例の値と異なる可能性があります。

_idフィールドを指定してドキュメントを挿入

次の例では、insert() メソッドに渡されるドキュメントに _id フィールドが含まれています。重複キー エラーを回避するには、_id の値はコレクション内で一意である必要があります。

db.products.insert( { _id: 10, item: "box", qty: 20 } )

この操作を実行すると、次のドキュメントが products コレクションに挿入されます。

{ "_id" : 10, "item" : "box", "qty" : 20 }

複数のドキュメントの挿入

次の例では、ドキュメントの配列をinsert()メソッドに渡して、3 つのドキュメントの一括挿入を実行します。 デフォルトでは、MongoDB は順序付き挿入を実行します。 順序付き挿入で、いずれかのドキュメントの挿入中にエラーが発生した場合、MongoDB は配列内の残りのドキュメントを処理せず、エラーを返します。

配列内のドキュメントは同じフィールドを持つ必要はありません。たとえば、配列の最初のドキュメントには_id フィールドと type フィールドがあります。2 番目と 3 番目のドキュメントには _id フィールドが含まれていないため、mongod は挿入中に 2 番目と 3 番目のドキュメントに _id フィールドを作成します。

db.products.insert(
   [
     { _id: 11, item: "pencil", qty: 50, type: "no.2" },
     { item: "pen", qty: 20 },
     { item: "eraser", qty: 25 }
   ]
)

この操作により、次の 3 つのドキュメントが挿入されました。

{ "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a0"), "item" : "pen", "qty" : 20 }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a1"), "item" : "eraser", "qty" : 25 }

順序なし挿入の実行

次の例では、3 つのドキュメントを順序なしで挿入しています。順序なし挿入で、いずれかのドキュメントの挿入中にエラーが発生した場合、MongoDB は配列内の残りのドキュメントの挿入を続行します。

db.products.insert(
   [
     { _id: 20, item: "lamp", qty: 50, type: "desk" },
     { _id: 21, item: "lamp", qty: 20, type: "floor" },
     { _id: 22, item: "bulk", qty: 100 }
   ],
   { ordered: false }
)

デフォルトの書込み保証 (write concern) の上書き

次のレプリカセットに対する操作では、w: 2 の書込み保証 (write concern)を指定し、タイムアウトを wtimeout で5000 ミリ秒に設定しています。この操作は、書き込み (write) がプライマリと1つのセカンダリの両方に伝達された後に返すか、5 秒後にタイムアウトします。

db.products.insert(
    { item: "envelopes", qty : 100, type: "Clasp" },
    { writeConcern: { w: 2, wtimeout: 5000 } }
)

正常な結果

insert()は、操作のステータスを含むWriteResult()オブジェクトを返します。 成功すると、 WriteResult()オブジェクトには挿入されたドキュメント数に関する情報が含まれます。

WriteResult({ "nInserted" : 1 })

書込み保証 (write concern) エラー

insert()メソッドで書込み保証 (write concern) が発生した場合、結果にはWriteResult.writeConcernErrorフィールドが含まれます。

WriteResult({
  "nInserted" : 1,
  "writeConcernError"({
     "code" : 64,
     "errmsg" : "waiting for replication timed out",
     "errInfo" : {
       "wtimeout" : true,
       "writeConcern" : {
         "w" : "majority",
         "wtimeout" : 100,
         "provenance" : "getLastErrorDefaults"
       }
     }
})

書込み保証 (write concern) とは関係のないエラー

insert() メソッドで書込み保証（write concern）エラーが発生した場合、結果には WriteResult.writeError フィールドが含まれます。

WriteResult({
   "nInserted" : 0,
   "writeError" : {
      "code" : 11000,
      "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.foo.$_id_  dup key: { : 1.0 }"
   }
})