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

パラメーター

書込み保証 (write concern)

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

コレクションと _id フィールドの作成

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

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

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

トランザクション

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

Oplog エントリ

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

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

次の例は、_id フィールドのないドキュメントを movies コレクションに挿入します。

db.movies.insert( { title: "Inception", year: 2010, genres: [ "Action", "Sci-Fi" ] } )

{
  acknowledged: true,
  insertedIds: { '0': "..." }
}

挿入されたドキュメントに _id が含まれていないため、mongod は _id フィールドを作成して追加し、それに一意の ObjectId() 値を割り当てます。

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

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

次の例では、movies コレクションに挿入されたドキュメントの _id フィールドを指定しています。重複キー エラーを回避するには、_id の値はコレクション内で一意である必要があります。

db.movies.insert( { _id: 10, title: "Inception", year: 2010 } )

{
  acknowledged: true,
  insertedIds: { '0': 10 }
}

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

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

最初のドキュメントでは、_id フィールドが指定されています。2 番目と 3 番目のドキュメントには _id フィールドが含まれていないため、mongod は挿入時にこれらのドキュメントに対して _id フィールドを作成して追加します。

db.movies.insert(
   [
     { _id: 11, title: "Inception", year: 2010, genres: [ "Action", "Sci-Fi" ] },
     { title: "The Matrix", year: 1999 },
     { title: "Interstellar", year: 2014 }
   ]
)

{
  acknowledged: true,
  insertedIds: {
    '0': 11,
    '1': "...",
    '2': "..."
  }
}

順序なし挿入の実行

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

db.movies.insert(
   [
     { _id: 20, title: "2001: A Space Odyssey", year: 1968 },
     { _id: 21, title: "A Clockwork Orange", year: 1971 },
     { _id: 22, title: "The Shining", year: 1980 }
   ],
   { ordered: false }
)

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

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

db.movies.insert(
    { title: "The Revenant", year: 2015 },
    { writeConcern: { w: 2, j: true, wtimeout: 5000 } }
)

正常な結果

成功すると、返された 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() に書込み保証以外のエラーが発生した場合、結果には 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 }"
   }
})