replaceOne() (ドキュメントの置換)
最終更新：2026-10-09
replaceOne() (ドキュメントの置換)
replaceOne() はフィルタに一致する最初のドキュメントを、まったく新しいドキュメントに置き換えます。第2引数に更新演算子を使う updateOne() とは異なり、ここでは第2引数が置換ドキュメントそのものであり、_id 以外のすべてのフィールドが上書きされます。結果には matchedCount と modifiedCount が含まれます。ドキュメントの構造を丸ごと書き換える必要がある場合に適したツールです。
| カテゴリ | 書き込み |
|---|---|
| MongoDB バージョン | 1.0+ |
| 例の言語 | mongosh（シェル） |
📝 構文
db.<collection>.replaceOne(<filter>, <replacement>, { upsert: <bool> })⚙️ パラメータ
| フィルター条件 | 置き換えるドキュメントにマッチする述語。 |
|---|---|
| 新しいドキュメント | 完全な置換ドキュメント。_id 以外のすべてのフィールドを上書きします。 |
| upsert | 任意。マッチしない場合に挿入します。既定は false。 |
戻り値：UpdateResult: { acknowledged, matchedCount, modifiedCount, upsertedId }。
▶ 例
以下のコマンドをローカルの mongosh で実行してください（mongod が起動済みである必要があります）：
// replaceOne: Bob のドキュメントを丸ごと置換する
db.users.replaceOne(
{ name: 'Bob' },
{ name: 'Bob', age: 26, city: 'Shanghai', vip: true }
)出力：
{ acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: null }📌 注意事項
- 置換ドキュメントは _id を保持する必要がある（省略すると元の _id が残る）。保持しない場合はエラーになる
- 更新演算子（{$set: ...} など）はここでは解釈されない。リテラルフィールドとして保存される
- 最初の一致のみが置換される。バッチ処理にはループか updateMany() を使う
🏷️ 関連タグ
💡 関連ケース
さらなる実践ケースを近日公開予定。
📚 関連チュートリアル
❓ よくある質問
QreplaceOne と updateOne の違いは何ですか？
AupdateOne() は演算子でフィールドを部分的に変更します。replaceOne() は _id 以外のすべてのフィールドを上書きする新しいドキュメントを丸ごと入れ替えます。
QreplaceOne で _id を変更できますか？
Aできません。_id は不変です。置換ドキュメントは元の _id を保持する必要があり、保持しない場合はエラーになります。
QreplaceOne の第2引数に更新演算子を入れられますか？
A入れられません。第2引数は置換ドキュメントです。{$set: ...} はリテラルフィールドとしてそのまま保存されます。
