db.collection.replaceOne()

項目一覧

定義

互換性
構文
動作
例

MongoDB とドライバー

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

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

定義

db.collection.replaceOne(filter, replacement, options)

フィルターに基づいてコレクション内の単一のドキュメントを置換します。

次の値を返します。

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

acknowledgedtrue操作が書込み保証（ write concern ）付きで実行された場合はとしてブール値false （書込み保証が無効になっている場合は
matchedCount 一致したドキュメントの数を含みます
modifiedCount 変更されたドキュメントの数を含みます
upsertedId 、アップサートされたドキュメントの _id が含まれる

互換性

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

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

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

構文

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

db.collection.replaceOne(
   <filter>,
   <replacement>,
   {
      upsert: <boolean>,
      writeConcern: <document>,
      collation: <document>,
      hint: <document|string>
   }
)

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

Parameter

タイプ

説明

フィルター

ドキュメント

更新の選択基準。find()メソッドと同じクエリセレクターを使用できます。

コレクション内で返される最初のドキュメントを置き換えるには、空のドキュメント { } を指定します。

replacement

ドキュメント

置換ドキュメントです。

アップデート演算子を含めることはできません。

upsert

ブール値

任意。true の場合、replaceOne() によって次のいずれかが実行されます。

filter に一致するドキュメントがない場合は、replacement パラメータからドキュメントを挿入します。
filterに一致するドキュメントをreplacementドキュメントに置き換えます。

MongoDB では、filter または replacement ドキュメントで指定されていない場合、_id フィールドが置換ドキュメントに追加されます。_id が両方に存在する場合、値は等しくなければなりません。

複数のアップサートを回避するため、query フィールドにユニークインデックスが付けられていることを確認します。

デフォルトは false です。

writeConcern

ドキュメント

任意。書込み保証（write concern）を表現するドキュメント。デフォルトの書込み保証を使用する場合は省略します。

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

collation

ドキュメント

任意。

操作に使用する照合を指定します。

照合を指定すると、大文字・小文字やアクセント記号など、文字列を比較するための言語独自のルールを指定できます。

照合オプションの構文は次のとおりです。

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

照合を指定する場合、locale フィールドは必須ですが、その他の照合フィールドはすべて任意です。フィールドの説明については、照合ドキュメントを参照してください。

照合が指定されていなくても、コレクションにデフォルトの照合が設定されている場合（db.createCollection() を参照）には、コレクションの照合が使用されます。

コレクションにも操作にも照合が指定されていない場合、MongoDB では以前のバージョンで使用されていた単純なバイナリ比較によって文字列が比較されます。

1 つの操作に複数の照合は指定できません。たとえば、フィールドごとに異なる照合を指定できません。また、ソートと検索を一度に実行する場合、検索とソートで別の照合を使用できません。

hint

ドキュメント

任意。フィルターをサポートするために使用するインデックスを指定するドキュメントまたは文字列です。

このオプションには、インデックス仕様ドキュメントまたはインデックス名の文字列を指定できます。

存在しないインデックスを指定した場合、操作はエラーになります。

例については、「replaceOne の hint を指定する」を参照してください。

動作

replaceOne()は、 replacementドキュメントを使用して、コレクション内のfilterに一致する最初のドキュメントを更新します。

`upsert`

upsert: trueでfilterに一致するドキュメントがない場合、 db.collection.replaceOne()はreplacementドキュメントに基づいて新しいドキュメントを作成します。

シャーディングされたコレクションで upsert: true を指定する場合、filter には完全なシャードキーを含める必要があります。シャーディングされたコレクションにおける追加のdb.collection.replaceOne()動作については、シャーディングされたコレクションを参照してください。

「アップサートによる置換」を参照してください。

上限付きコレクション

置き換え操作によってドキュメントのサイズが変更されると、操作は失敗します。

時系列コレクション

replaceOne()時系列コレクションではメソッドは使用できません。

シャーディングされたコレクション

db.collection.replaceOne() は、最初にクエリフィルターを使用して、単一のシャードをターゲットにしようとします。クエリフィルターで単一のシャードをターゲットにできない場合は、置き換えドキュメントをターゲットにしようとします。

以前のバージョンでは、この操作では置換ドキュメントを使用するターゲットを試行します。

置き換え用ドキュメントのシャードキー要件

置き換えドキュメントにシャードキーを含める必要はありません。

警告

シャーディングされたコレクション内のドキュメントには、シャードキーフィールドがないことがあります。ドキュメントのシャードキーの値を変更するときに、誤ってシャードキーを削除しないように注意してください。

`upsert` シャーディングされたコレクション

シャーディングされたコレクションの upsert: true を含む db.collection.replaceOne() 操作には、filter に完全なシャードキーを含める必要があります。

ただし、シャーディングされたコレクション内のドキュメントにはシャードキーのフィールドがない場合があります。シャードキーがないドキュメントを対象とするには、null を等価一致のを（_id フィールド上と同じに）別のフィルター条件と組み合わせて使用できます。以下に例を挙げます。

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

シャードキーの変更

シャードキーフィールドが不変の _id フィールドでない限り、ドキュメントのシャードキー値を更新できます。

警告

既存のシャードキー値をdb.collection.replaceOne()で変更するには

必ず mongos 上で使用します。シャードに直接操作を実行しないでください。
トランザクション内で、または再試行可能な書き込みとして実行する必要があります。
完全なシャードキーに等価フィルターを含める必要があります。

欠落しているシャードキー

シャーディングされたコレクション内のドキュメントには、シャードキーフィールドがない場合があります。db.collection.replaceOne()を使用してドキュメントの欠落しているシャードキーを設定するには、mongosで実行する必要があります。シャードに対して直接操作を実行しないでください。

さらに、次の要件も適用されます。

タスク	要件
設定するには `null`	`upsert: true`が指定されている場合は、完全なシャードキーに等価フィルターが必要です。
`null`以外の値に設定するには	トランザクション内で、または再試行可能な書き込みとして実行する必要があります。次のいずれかの場合、完全なシャードキーに等価フィルターが必要です。 `upsert: true`または、別のシャードに属する新しいシャードキー値

Tip

欠落しているキー値は NULL 等価一致の一部として返されるため、NULL 値のキーが更新されないように、必要に応じて追加のクエリ条件（_id フィールドなど）を追加します。

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

トランザクション

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

重要

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

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

トランザクション内のアップサート

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

db.collection.replaceOne() と upsert: trueは、既存のコレクションまたは存在しないコレクションで実行できます。存在しないコレクションに対して実行すると、操作によってコレクションが作成されます。

Tip

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

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

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

例

置換

restaurant コレクションには次のドキュメントが含まれます。

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan" },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }

次の操作は、name: "Central Perk Cafe" になっている 1 件のドキュメントを置き換えます。

try {
   db.restaurant.replaceOne(
      { "name" : "Central Perk Cafe" },
      { "name" : "Central Pork Cafe", "Borough" : "Manhattan" }
   );
} catch (e){
   print(e);
}

この操作では以下が返されます。

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

一致するものが見つからなかった場合、以下の結果が返されます。

{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }

upsert: trueを設定すると、一致するものが見つからない場合にはドキュメントが挿入されます。「アップサートによる置換」を参照してください。

アップサートによる置き換え

restaurant コレクションには次のドキュメントが含まれます。

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan",  "violations" : 3 },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }

次の操作は、name : "Pizza Rat's Pizzaria" のドキュメントを upsert : true で置き換えようとします。

try {
   db.restaurant.replaceOne(
      { "name" : "Pizza Rat's Pizzaria" },
      { "_id": 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 8 },
      { upsert: true }
   );
} catch (e){
   print(e);
}

upsert : true のため、ドキュメントは replacement ドキュメントに基づいて挿入されます。この操作は以下を返します。

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : 4
}

コレクションには、次のドキュメントが含まれています。

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 },
{ "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 8 }

書込み保証 (write concern) による置き換え

３つのノードから成るレプリカセットにおいて、次の操作は w の majority と wtimeout の 100 を指定します。

try {
   db.restaurant.replaceOne(
       { "name" : "Pizza Rat's Pizzaria" },
       { "name" : "Pizza Rat's Pub", "Borough" : "Manhattan", "violations" : 3 },
       { 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"
     }
   }
})

次の表は、errInfo.writeConcern.provenanceの値について説明したものです。

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

照合の指定

照合を指定すると、大文字・小文字やアクセント記号など、文字列を比較するための言語独自のルールを指定できます。

コレクション myCollは、次のドキュメントを含みます。

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

次の操作には照合オプションが含まれます。

db.myColl.replaceOne(
   { category: "cafe", status: "a" },
   { category: "cafÉ", status: "Replaced" },
   { collation: { locale: "fr", strength: 1 } }
);

にを指定`hintreplaceOne`

次のドキュメントを使用してサンプルmembers コレクションを作成します。

db.members.insertMany([
   { "_id" : 1, "member" : "abc123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" },
   { "_id" : 3, "member" : "lmn123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 4, "member" : "pqr123", "status" : "D", "points" : 20,  "misc1" : "Deactivated", "misc2" : null },
   { "_id" : 5, "member" : "ijk123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 6, "member" : "cde123", "status" : "A", "points" : 86,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }
])

コレクションに次のインデックスを作成します。

db.members.createIndex( { status: 1 } )
db.members.createIndex( { points: 1 } )

次の更新操作は、インデックス{ status: 1 }を使用することを明示的に示しています。

注意

存在しないインデックスを指定した場合、操作はエラーになります。

db.members.replaceOne(
   { "points": { $lte: 20 }, "status": "P" },
   { "misc1": "using index on status", status: "P", member: "replacement", points: "20"},
   { hint: { status: 1 } }
)

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

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

使用されているインデックスを表示するには、$indexStats パイプラインを使用できます。

db.members.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] )

戻る

db.collection.renameCollection

db.collection.stats

定義

互換性

構文

動作

upsert

上限付きコレクション

時系列コレクション

シャーディングされたコレクション

置き換え用ドキュメントのシャードキー要件

警告

upsert シャーディングされたコレクション

シャードキーの変更

警告

欠落しているシャードキー

Tip

トランザクション

重要

トランザクション内のアップサート

Tip

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

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

例

置換

アップサートによる置き換え

書込み保証 (write concern) による置き換え

照合の指定

に を指定hintreplaceOne

注意

`upsert`

`upsert` シャーディングされたコレクション

にを指定`hintreplaceOne`