insert

定義

insert

insertコマンドは、1 つ以上のドキュメントを挿入し、すべての挿入のステータスを含むドキュメントを返します。MongoDB ドライバーが提供する insert メソッドは、内部的にこのコマンドを使います。

Tip

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

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

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

互換性

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

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

• 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>
   }
)

コマンドフィールド

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

動作

例

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

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

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 }

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
}

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

出力

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

insert.ok

コマンドのステータスです。

insert.n

挿入されたドキュメントの数。

insert.writeErrors

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

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

insert.writeErrors.index

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

insert.writeErrors.code

エラーを識別する整数値です。

insert.writeErrors.errmsg

エラーの説明です。

insert.writeConcernError

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

バージョン7.1での変更: insertがmongosで実行される場合、1 つ以上の書込みエラーが発生しても、書込み保証エラーが常に報告されます。

以前のリリースでは、書込みエラーが発生すると、 insertは書込み保証エラーを報告しないことがありました。

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）が一切指定されていない状態で、サーバーから発生した書き込み保証。

以下は、単一のドキュメントのinsertが成功した場合に返されるドキュメントの例です。

{ ok: 1, n: 1 }

以下は、1 つのドキュメントが正常に挿入されたが、もう 1 つのドキュメントではエラーが発生した 2 つのドキュメントのうちのinsertに対して返されるドキュメントの例です。

{
   "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 }"
      }
   ]
}