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

MongoDB とドライバー

このページでは、mongosh メソッドのドキュメントについて記載しています。MongoDB ドライバーで同等のメソッドを確認するには、ご使用のプログラミング言語の対応するページを参照してください。

C#Java Sync Node.js PyMongo C C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Mongoid Rust Scala

定義

db.collection.insertOne()

コレクションに 1 つのドキュメントを挿入します。

次の値を返します。

次の値を返します。	次の要素を含むドキュメント: 書込み保証付きで操作が実行された場合は`acknowledged` のブール値は `true` に、書込み保証が無効の場合は `false` になります。挿入されたドキュメントの`_id`値を含む`insertedId`フィールド。

次の要素を含むドキュメント:

書込み保証付きで操作が実行された場合はacknowledged のブール値は true に、書込み保証が無効の場合は false になります。
挿入されたドキュメントの_id値を含むinsertedIdフィールド。

互換性

このメソッドは、次の環境でホストされている配置で使用できます。

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

注意

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン
MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

構文

db.collection.insertOne() の形式は次のとおりです。

db.collection.insertOne(
    <document>,
    {
      writeConcern: <document>
    }
)

パラメーター

insertOne() は以下のパラメーターを取ります。

Parameter	タイプ	説明
`document`	ドキュメント	コレクションに挿入するドキュメント。
`writeConcern`	ドキュメント	任意。書込み保証（write concern）を表現するドキュメント。デフォルトの書込み保証を使用する場合は省略します。トランザクションで実行される場合、操作の書込み保証 (write concern)を明示的に設定しないでください。トランザクションで書込み保証を使用するには、「トランザクション書込み保証」を参照してください。

動作

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

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

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

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

説明可能性

insertOne() db.collection.explain()はと互換性がありません。

Error Handling

エラーが発生すると、insertOne() によって writeError または writeConcernError のいずれかの例外がスローされます。

スキーマ検証エラー

コレクションでスキーマ検証が使用されており、 validationActionがerrorに設定されている場合、無効なドキュメントを挿入するとMongoServerErrorがスローされ、 insertOne()は失敗します。

トランザクション

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

重要

ほとんどの場合、分散トランザクションでは 1 つのドキュメントの書き込み (write) よりもパフォーマンスコストが高くなります。分散トランザクションの可用性は、効果的なスキーマ設計の代わりにはなりません。多くのシナリオにおいて、非正規化されたデータモデル（埋め込みドキュメントと配列）が引き続きデータやユースケースに最適です。つまり、多くのシナリオにおいて、データを適切にモデリングすることで、分散トランザクションの必要性を最小限に抑えることができます。

トランザクションの使用に関するその他の考慮事項（ランタイム制限や oplog サイズ制限など）については、「本番環境での考慮事項」も参照してください。

トランザクションでのコレクション作成

トランザクションがクロスシャード間書き込みトランザクション（write transaction）でない場合に、分散トランザクション内にコレクションとインデックスを作成できます。

トランザクションにないコレクションに挿入を指定すると、MongoDB は暗黙的にコレクションを作成します。

書込み保証とトランザクション

トランザクションで実行される場合、操作の書込み保証 (write concern)を明示的に設定しないでください。トランザクションで書込み保証を使用するには、「トランザクション書込み保証」を参照してください。

Oplog エントリ

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

例

このページの例では、sample_mflix データセットのデータを使用しています。自己管理型 MongoDB 配置にこのデータセットをロードする方法の詳細については、「サンプルデータセットのロード」を参照してください。サンプルデータベースに何らかの変更を加えた場合は、今ページの例を実行するには、データベースを削除して再作成する必要がある可能性があります。

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

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

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

{
  acknowledged: true,
  insertedId: "..."
}

ドキュメントに_idが含まれていなかったため、mongod で_idフィールドを作成して追加し、それにユニークなObjectId()値を割り当てます。

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

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

ドキュメントを挿入する際に _id を指定する場合、_id の値はコレクション内で一意である必要があります。次の例では、movies コレクションにドキュメントを挿入し、_id を指定します。

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

{ acknowledged: true, insertedId: 10 }

_id など、ユニークインデックスの構成キーに重複値を挿入すると、例外がスローされます。この例外を受け、既存の _id 値を持つドキュメントの挿入を試みます。

try {
   db.movies.insertOne( { _id: 10, title: "Inception", year: 2010 } );
} catch (e) {
   print (e);
}

_id: 10 はすでにあるため、次の例外がスローされます。

WriteError({
   "index" : 0,
   "code" : 11000,
   "errmsg" : "E11000 duplicate key error collection: sample_mflix.movies index: _id_ dup key: { : 10.0 }",
   "op" : {
      "_id" : 10,
      "title" : "Inception",
      "year" : 2010
   }
})

書込み保証を増やす

3 つのノードからなるレプリカセットがある場合、次の操作では majority を w と、100 を wtimeout と指定します。

try {
   db.movies.insertOne(
       { title: "Arrival", year: 2016 },
       { writeConcern: { w : "majority", wtimeout : 100 } }
   );
} catch (e) {
   print (e);
}

承認に wtimeout 制限時間を超える時間がかかると、次の例外が発生します。

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

戻る

db.collection.insertMany

db.collection.isCapped