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 つのドキュメントを挿入します。

次の値を返します。	次の要素を含むドキュメント: ブール値は、書込み保証（write concern）が有効化されて操作が実行された場合は `true` として、無効化されていた場合は `false` として `acknowledged` されます。挿入されたドキュメントの`_id`値を含む`insertedId`フィールド。

互換性

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

MongoDB Atlas はクラウドでの MongoDB 配置のためのフルマネージドサービスです

注意

このコマンドは、すべての MongoDB Atlas クラスターでサポートされています。すべてのコマンドに対する Atlas のサポートについては、「サポートされていないコマンド」を参照してください。

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

定義

互換性

注意

構文