findOneAndReplace() (置換してドキュメントを返す)
最終更新：2026-10-09
findOneAndReplace() (置換してドキュメントを返す)
findOneAndReplace() はフィルタに一致する最初のドキュメントを置換ドキュメントに入れ替え、置換前または置換後のドキュメントを返します。例: `db.users.findOneAndReplace({ name: 'Bob' }, { name: 'Bob', age: 26 }, { returnDocument: 'after' })`。置換結果を必要とするフローに適した、ドキュメントを読み戻す replaceOne() です。_id 以外のすべてのフィールドが上書きされます。
| カテゴリ | 書き込み |
|---|---|
| MongoDB バージョン | 1.0+ |
| 例の言語 | mongosh（シェル） |
📝 構文
db.<collection>.findOneAndReplace(<filter>, <replacement>, { returnDocument: 'after', upsert: <bool> })⚙️ パラメータ
| フィルター条件 | 置き換えるドキュメントにマッチする述語。 |
|---|---|
| 新しいドキュメント | 完全な置換。_id 以外のすべてのフィールドを上書きします。 |
| returnDocument | 任意。'before' または 'after'。既定は 'before'。 |
戻り値：置き換え前（または置き換え後）のドキュメント。何もマッチせず upsert が無効の場合は null。
▶ 例
以下のコマンドをローカルの mongosh で実行してください（mongod が起動済みである必要があります）：
// findOneAndReplace: Bob のドキュメントを入れ替え、新しいものを返す
const doc = db.users.findOneAndReplace(
{ name: 'Bob' }, { name: 'Bob', age: 26, vip: true },
{ returnDocument: 'after' }
)
doc出力：
{
_id: ObjectId('64c8a1b20000000000000002'),
name: 'Bob',
age: 26,
vip: true
}📌 注意事項
- 置換ドキュメントは元の _id を保持する必要がある。保持しない場合はエラーになる
- 返される _id は常に元のもの（upsert で挿入される場合でも）
- 置換は丸ごと上書きする。必要なフィールドをすべて新しいドキュメントに含めること
🏷️ 関連タグ
💡 関連ケース
さらなる実践ケースを近日公開予定。
📚 関連チュートリアル
❓ よくある質問
QfindOneAndReplace と replaceOne の違いは何ですか？
AreplaceOne() はカウンタを返します。findOneAndReplace() は入れ替え前後のドキュメントを返します。
QfindOneAndReplace で _id を変更できますか？
Aできません。置換ドキュメントは元の _id を保持する必要があり、保持しないと操作がエラーになります。
Qupsert オンの場合、findOneAndReplace は何を返しますか？
A一致するものが無い場合、新しいドキュメントが挿入されて返され、新しく生成された _id を持ちます。
