$replaceRoot (ルートの置換)
最終更新：2026-10-09
$replaceRoot (ルートの置換)
$replaceRoot は、ドキュメント全体を指定した埋め込みドキュメントで置き換えます。detail のようなネストしたオブジェクトをトップレベルに持ち上げるのに一般的に使います。元のフィールドはすべて失われます。対象が存在しない、またはオブジェクトでない場合はエラーになります。$ifNull でガードするか、結果が null の場合に元のドキュメントを保持する $replaceWith を使います。
| カテゴリ | コアステージ |
|---|---|
| MongoDB バージョン | 1.0+ |
| 例の言語 | mongosh（シェル） |
📝 構文
{ $replaceRoot: { newRoot: <document expression> } }⚙️ パラメータ
| newRoot | 新しいドキュメントとなるように評価される式。オブジェクトである必要があります。 |
|---|
戻り値：newRoot をルートとするドキュメントストリーム
▶ 例
以下のコマンドをローカルの mongosh で実行してください（mongod が起動済みである必要があります）：
// $replaceRoot: detail をルートに昇格
db.orders.aggregate([
{ $replaceRoot: { newRoot: '$detail' } }
])出力：
// 元の注文フィールドは消え、detail だけが残る
{ "city": "SH", "zip": "200000" }📌 注意事項
- newRoot がオブジェクトに評価されないとステージはエラーになる
- 元のフィールドは完全に置き換わる。必要なフィールドは先に $set でマージしておく
- $replaceWith は null の結果を許容するバリアント
🏷️ 関連タグ
💡 関連ケース
📚 関連チュートリアル
❓ よくある質問
Q$replaceRoot と $project の違いは？
A$project は元のドキュメントからフィールドを選択・計算します。$replaceRoot はまったく新しいドキュメントに入れ替えます。
QnewRoot のフィールドが存在しない場合は？
Aエラーになります。$ifNull でガードするか、$replaceWith バリアントを使います。
Qすべてを置き換えずに 1 階層だけ持ち上げるには？
A部分的な持ち上げには $project のドットパス式を使います。$replaceRoot はルート全体を置き換えます。
