Docs Menu
Docs Home
/
MongoDB マニュアル
/
参照
/
mongosh メソッド
/
コレクション

db.collection.insertOne()

項目一覧

  • 定義
  • 互換性
  • 構文
  • 動作
  • 例

定義

db.collection.insertOne()

重要

mongosh メソッド

このページでは、mongosh メソッドについて説明します。ただし、データベースコマンドや Node.js などの言語固有のドライバーのドキュメントには該当しません。

データベースコマンドについては、 insertコマンドを参照してください。

MongoDB API ドライバーについては、各言語の MongoDB ドライバー ドキュメントを参照してください。

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

次の値を返します。次の要素を含むドキュメント:

  • 書込み保証付きで操作が実行された場合はacknowledged のブール値は true に、書込み保証が無効の場合は false になります。

  • 挿入されたドキュメントの_id値を含むinsertedIdフィールド。

互換性

次の環境でホストされる配置には db.collection.insertOne() を使用できます。

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

  • MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン

  • MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

構文

insertOne() メソッドの形式は次のとおりです。

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

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

Parameter
タイプ
説明
document
ドキュメント
コレクションに挿入するドキュメント。
writeConcern
ドキュメント
任意。書込み保証を表現するドキュメントです。デフォルトの書込み保証を使用する場合は省略します。.. include:: /includes/extracts/transactions-operations-write-concern.rst

動作

コレクションの作成

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

_id フィールド

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

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

説明可能性

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

Error Handling

エラーが発生すると、 db.collection.insertOne() により writeError または writeConcernError 例外がスローされます。

スキーマ検証エラー

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

トランザクション

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

重要

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

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

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

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

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

Tip

以下も参照してください。

トランザクション内でのコレクションとインデックスの作成

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

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

Oplog エントリ

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

例

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

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

try {
   db.products.insertOne( { item: "card", qty: 15 } );
} catch (e) {
   print (e);
};

この操作を実行すると次のドキュメントが返されます。

{
   "acknowledged" : true,
   "insertedId" : ObjectId("56fc40f9d735c28df206d078")
}

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

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

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

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

try {
   db.products.insertOne( { _id: 10, item: "box", qty: 20 } );
} catch (e) {
   print (e);
}

この操作では、以下を返します。

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

_idなど、 一意なインデックスの一部であるキーに重複した値を挿入すると、例外がスローされます。次の例では、すでに存在する_id値を持つドキュメントを挿入しようとしています。

try {
   db.products.insertOne( { _id: 10, "item" : "packing peanuts", "qty" : 200 } );
} catch (e) {
   print (e);
}

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

WriteError({
   "index" : 0,
   "code" : 11000,
   "errmsg" : "E11000 duplicate key error collection: inventory.products index: _id_ dup key: { : 10.0 }",
   "op" : {
      "_id" : 10,
      "item" : "packing peanuts",
      "qty" : 200
   }
})

書込み保証を増やす

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

try {
   db.products.insertOne(
       { "item": "envelopes", "qty": 100, type: "Self-Sealing" },
       { 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"
     }
   }
})

Tip

以下も参照してください。

戻る

db.collection.insertMany