$replaceRoot (Substituir a Raiz)
Última atualização: 2026-10-09
$replaceRoot (Substituir a Raiz)
$replaceRoot substitui o documento inteiro por um documento embutido especificado, comumente usado para promover um objeto aninhado como detail ao nível superior. Todos os campos originais são perdidos. Ele gera erro quando o alvo está ausente ou não é um objeto; proteja com $ifNull ou use $replaceWith, que mantém o documento quando o resultado é null.
| Categoria | Estágios Principais |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $replaceRoot: { newRoot: <expressão de documento> } }⚙️ Parâmetros
| newRoot | Expressão avaliada para se tornar o novo documento; deve ser um objeto. |
|---|
Retorno：Fluxo de documentos enraizado em newRoot
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $replaceRoot: promove detail à raiz
db.orders.aggregate([
{ $replaceRoot: { newRoot: '$detail' } }
])Saída：
// Campos do pedido original sumiram; apenas detail permanece
{ "city": "SH", "zip": "200000" }📌 Notas
- newRoot deve avaliar para um objeto ou o estágio gera erro
- Os campos originais são totalmente substituídos; mescle o que precisar com $set antes
- $replaceWith é a variante que tolera resultados null
🏷️ Tags Relacionados
💡 Casos Relacionados
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre $replaceRoot e $project?
A$project seleciona ou calcula campos do original; $replaceRoot troca por um documento inteiramente novo.
QE se o campo newRoot não existir?
AEle gera erro. Proteja com $ifNull ou use a variante $replaceWith.
QComo elevo um nível de aninhamento em vez de substituir tudo?
APara elevação parcial use expressões de caminho pontilhado em $project; $replaceRoot substitui a raiz inteira.
