/ /

insert（データベースコマンド）

定義

insert

コレクションに 1 つ以上のドキュメントを挿入し、ステータスドキュメントを返します。 MongoDBドライバーの挿入メソッドは、内部的にこのコマンドを使用します。

Tip

mongosh では、このコマンドは db.collection.insertOne() および db.collection.insertMany()ヘルパーメソッドを通じても実行できます。

ヘルパーメソッドはmongoshユーザーには便利ですが、データベースコマンドと同じレベルの情報は返されない可能性があります。便宜上必要ない場合、または追加の戻りフィールドが必要な場合は、データベースコマンドを使用します。

次の値を返します。	操作のステータスを含むドキュメント。詳細については、「出力」を参照してください。

互換性

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

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

注意

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

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

構文

このコマンドの構文は、次のとおりです。

db.runCommand(
   {
      insert: <collection>,
      documents: [ <document>, <document>, <document>, ... ],
      ordered: <boolean>,
      maxTimeMS: <integer>,
      writeConcern: { <write concern> },
      bypassDocumentValidation: <boolean>,
      comment: <any>
   }
)

コマンドフィールド

このコマンドは、次のフィールドを使用します。

フィールド	タイプ	説明
`insert`	string	ターゲットコレクションの名前。
`documents`	配列	名前付きコレクションに挿入する 1 つ以上のドキュメントの配列。
`ordered`	ブール値	任意。 `true` の場合、挿入が失敗すると、残りのドキュメントを挿入せずに戻ります。 `false` の場合、挿入が失敗したときに、残りのドキュメントの挿入を続行します。デフォルトは `true` です。
`maxTimeMS`	non-negative integer	任意。時間制限をミリ秒単位で指定します。`maxTimeMS` の値を指定しない場合、操作はタイムアウトしません。値を `0` にすると、デフォルトの無制限動作を明示的に指定します。 MongoDB は、`db.killOp()` と同じメカニズムを使用して、割り当てられた時間制限を超えた操作を終了します。MongoDB は、指定された割り込みポイントのいずれかでのみ操作を終了します。
`writeConcern`	ドキュメント	任意。書込み保証 (write concern)を指定します。省略すると、デフォルトの書込み保証 (write concern)が使用されます。トランザクションで実行される場合、操作の書込み保証 (write concern)を明示的に設定しないでください。トランザクションで書込み保証を使用するには、「トランザクション書込み保証」を参照してください。
`bypassDocumentValidation`	ブール値	任意。操作中に`insert` がスキーマ検証をバイパスできるようにします。
`comment`	any	任意。このコマンドに添付するユーザー指定のコメント。設定すると、このコメントは以下の場所にこのコマンドの記録と合わせて表示されます。 `attr.command.cursor.comment` フィールド内のmongod ログメッセージ。 `command.comment` フィールドのデータベースプロファイラー出力。 `command.comment` フィールドの`currentOp`出力。コメントには、有効な BSON 型（string, integer, object, array など）を使用できます。

動作

サイズ制限

すべての配列要素の合計サイズは、documents BSONドキュメントの最大サイズ以下である必要があります。

documents配列内のドキュメントの合計数は、最大バルクサイズを超えてはなりません。

スキーマ検証

insert コマンドは、bypassDocumentValidation オプションのサポートを追加します。これにより、検証ルールがあるコレクション内でドキュメントを挿入または更新する際に、スキーマ検証をバイパスできます。

トランザクション

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

重要

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

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

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

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

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

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

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

不正確な挿入

挿入中にサーバーエラーが発生した場合でも、一部のドキュメントは挿入されている可能性があります。

挿入が成功すると、システムはコレクションに挿入されたドキュメントの数であるinsert.nを返します。レプリカセットの状態が変化して挿入操作が中断された場合でも、システムはドキュメントの挿入を続行できます。その結果、 insert.nが報告するドキュメント数は実際に挿入された数より少なくなる場合があります。

例

単一ドキュメントのインサート

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

db.runCommand(
   {
      insert: "users",
      documents: [ { _id: 1, user: "abc123", status: "A" } ]
   }
)

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

{ "ok" : 1, "n" : 1 }

Bulk Insert

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

db.runCommand(
   {
      insert: "users",
      documents: [
         { _id: 2, user: "ijk123", status: "A" },
         { _id: 3, user: "xyz123", status: "P" },
         { _id: 4, user: "mop123", status: "P" }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

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

{ "ok" : 1, "n" : 3 }

Insert with の使用 `bypassDocumentValidation`

スキーマ検証validationActions がerror に設定されている場合、挿入コマンドは検証に失敗したドキュメントに対してエラーを返します。検証ルールに違反するドキュメントを挿入するには、を設定します。bypassDocumentValidation: true

statusフィールドの検証ルールを使用してuserコレクションを作成します。

検証ルールは、ステータスが "Unknown" または "Incompleted" でなければならないことを検証します。

db.createCollection("users", {
   validator:
      {
         status: {
            $in: [ "Unknown", "Incomplete" ]
         }
      }
})

検証ルールに違反するドキュメントを挿入します。

db.runCommand({
      insert: "users",
      documents: [ {user: "123", status: "Active" } ]
})

挿入は書き込みエラーメッセージを返します。

{
   n: 0,
   writeErrors: [
      {
         index: 0,
         code: 121,
         errInfo: {
            failingDocumentId: ObjectId('6197a7f2d84e85d1cc90d270'),
            details: {
               operatorName: '$in',
               specifiedAs: { status: { '$in': [Array] } },
               reason: 'no matching value found in array',
               consideredValue: 'Active'
            }
         },
         errmsg: 'Document failed validation'
      }
   ],
   ok: 1
}

bypassDocumentValidation: trueを設定して挿入を再実行します。

db.runCommand({
   insert: "users",
   documents: [ {user: "123", status: "Active" } ],
   bypassDocumentValidation: true
})

操作は成功しました。

スキーマの検証ルールに違反するドキュメントを確認するには、validate コマンドを使用します。

出力

返されるドキュメントには、次のフィールドのサブセットが含まれます。

insert.ok: コマンドのステータスです。

insert.n: 挿入されたドキュメントの数。

insert.writeErrors

挿入操作中に発生したエラーに関する情報を含むドキュメントの配列。writeErrors配列には、エラーが発生した挿入ごとにエラードキュメントが含まれています。

各エラードキュメントには以下のフィールドが含まれます。

insert.writeErrors.index: documents配列内のドキュメントを識別する整数。0 から始まるインデックスを使用します。

insert.writeErrors.code: エラーを識別する整数値です。

insert.writeErrors.errmsg: エラーの説明です。

insert.writeConcernError

書込み保証 (write concern) に関連するエラーを説明するドキュメント。

バージョンでの変更7.0.6 :（ およびでも利用可能6.0.145.0.30 ）:がで実行される場合、1 つ以上の書込みエラーが発生しても、書込み保証 (writeinsert mongosconcern)エラーが常に報告されます。以前のリリースでは、書込みエラーが発生すると、は書込み保証 (writeinsert concern)エラーを報告しないことがありました。

writeConcernErrorドキュメントには次のフィールドが含まれています。

insert.writeConcernError.code: 書込み保証 (write concern) エラーの原因を示す整数値です。

insert.writeConcernError.errmsg: 書込み保証 (write concern) エラーの原因の説明です。

insert.writeConcernError.errInfo.writeConcern

対応する操作に使用される書込み保証 (write concern) オブジェクトです。書込み保証 (write concern) オブジェクトフィールドの詳細については、「書込み保証 (write concern) の仕様」を参照してください。

書込み保証 (write concern) オブジェクトには、書込み保証 (write concern) のソースを示す以下のフィールドも含むことができます。

insert.writeConcernError.errInfo.writeConcern.provenance

書込み保証 (write concern) が発生した場所を示す文字列値です（書込み保証 (write concern) provenance と呼ばれます）。次の表は、このフィールドに指定できる値とその意味を示しています。

出所	説明
`clientSupplied`	書き込み保証（write concern）がアプリケーションで指定されました。
`customDefault`	書込み保証 (write concern) は、カスタム定義されたデフォルト値に基づきます。`setDefaultRWConcern` を参照してください。
`getLastErrorDefaults`	書込み保証 (write concern) は、レプリカセットの `settings.getLastErrorDefaults` のフィールドに基づきます。
`implicitDefault`	他の書き込み保証（write concern）が一切指定されていない状態で、サーバーから発生した書き込み保証。

以下は、単一ドキュメントの挿入が成功した場合の出力の例です。

{ ok: 1, n: 1 }

以下は、1 つのドキュメントが正常に挿入され、2 番目のドキュメントが失敗した場合の出力の例です。

{
   "ok" : 1,
   "n" : 1,
   "writeErrors" : [
      {
         "index" : 1,
         "code" : 11000,
         "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.users.$_id_  dup key: { : 1.0 }"
      }
   ]
}

戻る

getMore

mapReduce

定義

Tip

互換性

注意

構文

コマンドフィールド

動作

サイズ制限

スキーマ検証

トランザクション

重要

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

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

不正確な挿入

例

単一ドキュメントのインサート

Bulk Insert

Insert with の使用 bypassDocumentValidation

出力

Insert with の使用 `bypassDocumentValidation`