$replaceWith (Substituir Com)
Última atualização: 2026-10-09
$replaceWith (Substituir Com)
$replaceWith é como $replaceRoot, mas tolera resultados null ou ausentes, mantendo o documento original em vez de falhar. Ele se encaixa em cenários de promover-se-possível. Todo o resto segue a semântica de $replaceRoot.
| Categoria | Estágios Principais |
|---|---|
| Versão do MongoDB | 4.2+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $replaceWith: <expressão de documento> }⚙️ Parâmetros
| expressão de documento | Expressão cujo resultado substitui o documento; pode ser null ou ausente. |
|---|
Retorno：Fluxo de documentos substituído (o original é mantido quando o resultado é null)
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $replaceWith: promove detail quando presente
db.orders.aggregate([
{ $replaceWith: '$detail' }
])Saída：
// Pedidos com detail o emitem; os outros passam inalterados📌 Notas
- Resultados null ou ausentes mantêm o documento original; $replaceRoot geraria erro
- Recebe uma expressão diretamente, enquanto $replaceRoot a envolve em newRoot
- Frequentemente combinado com $mergeObjects para mesclar objetos embutidos em uma nova raiz
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre $replaceWith e $replaceRoot?
A$replaceWith emite o documento original quando o resultado é null; $replaceRoot gera erro.
QComo mesclo vários campos em um novo documento?
ACombine com $mergeObjects, ex.: { $replaceWith: { $mergeObjects: ['$a', '$b'] } }.
Q$replaceWith mantém _id?
ANão, a menos que a expressão inclua _id explicitamente.
