db.コレクション.replaceOne()（mongoshメソッド）

MongoDB とドライバー

This page documents a mongosh method. To see the equivalent method in a MongoDB driver, see the corresponding page for your programming language:

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)

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

次の値を返します。

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

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

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

互換性

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

MongoDB Atlas はクラウドでの MongoDB 配置のための完全管理サービスです

注意

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

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

構文

The replaceOne() method has the following form:

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

The replaceOne() method takes the following parameters:

Parameter

タイプ

説明

フィルター

ドキュメント

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

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

replacement

ドキュメント

置換ドキュメントです。

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

upsert

ブール値

Optional. When true, replaceOne() either:

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

ドキュメント

Optional. A document or string that specifies the index to use to support the filter.

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

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

For an example, see Specify hint for replaceOne.

動作

replaceOne() replaces the first matching document in the collection that matches the filter, using the replacement document.

`upsert`

If upsert: true and no documents match the filter, db.collection.replaceOne() creates a new document based on the replacement document.

If you specify upsert: true on a sharded collection, you must include the full shard key in the filter. For additional db.collection.replaceOne() behavior on a sharded collection, see Sharded Collections.

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

上限付きコレクション

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

時系列コレクション

You cannot use the replaceOne() method on a time series collection.

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

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

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

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

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

警告

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

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

A db.collection.replaceOne() operation that includes upsert: true on a sharded collection must include the full shard key in the filter.

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

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

シャードキーの変更

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

警告

To modify the existing shard key value with db.collection.replaceOne():

必ず mongos 上で使用します。シャードに直接操作を実行しないでください。
トランザクション内で、または再試行可能な書き込みとして実行する必要があります。
You must include an equality filter on the full shard key.

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

Documents in a sharded collection can be missing the shard key fields. To use db.collection.replaceOne() to set the document's missing shard key, you must run on a mongos. Do not issue the operation directly on the shard.

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

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

Tip

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

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

トランザクション

db.collection.replaceOne() can be used inside distributed transactions.

重要

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

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

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

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

db.collection.replaceOne() with upsert: true can be run on an existing collection or a non-existing collection. If run on a non-existing collection, the operation creates the collection.

Tip

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

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

例

置換

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

db.restaurant.insertMany ( [
   { _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 コレクションには次のドキュメントが含まれます。

db.restaurant.insertMany( [
   { _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は、次のドキュメントを含みます。

db.myColl.insertMany( [
   { _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 } }
);

`replaceOne` に `hint` を指定

次のドキュメントを使用してサンプル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

db.コレクション.replaceOne()（mongoshメソッド）

定義

互換性

構文

動作

upsert

上限付きコレクション

時系列コレクション

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

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

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

シャードキーの変更

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

トランザクション

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

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

例

置換

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

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

照合の指定

replaceOne に hint を指定

`upsert`

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

`replaceOne` に `hint` を指定