$merge (Mesclar)
Última atualização: 2026-10-09
$merge (Mesclar)
$merge grava os resultados do pipeline em uma coleção de destino (possivelmente em outro banco de dados ou cluster), atualizando documentos existentes ou inserindo novos por uma chave de correspondência. Um superconjunto de $out, ele deve ser o estágio final. Opções principais: into, on (campo de correspondência), whenMatched e whenNotMatched. Adequado para ETL, visões materializadas e sincronização entre coleções.
| Categoria | Avançado e Diagnóstico |
|---|---|
| Versão do MongoDB | 4.2+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $merge: { into: "<collection>", on: "<matchField>", whenMatched: "merge", whenNotMatched: "insert" } }⚙️ Parâmetros
| into | Coleção de destino, uma string ou objeto { db, coll }. |
|---|---|
| on | Campo usado para corresponder documentos existentes; o padrão é _id. |
| whenMatched | Comportamento em caso de correspondência: merge, replace, keepExisting ou um pipeline personalizado. |
| whenNotMatched | Comportamento quando não há correspondência: insert ou discard. |
Retorno：Nenhum documento continua; os resultados são gravados na coleção de destino
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $merge: grava totais de clientes em cust_stats
db.orders.aggregate([
{ $group: { _id: '$cust_id', total: { $sum: '$amount' } } },
{ $merge: {
into: 'cust_stats',
on: '_id',
whenMatched: 'replace',
whenNotMatched: 'insert'
} }
])Saída：
// cust_stats é atualizada ou recebe inserções📌 Notas
- Deve ser o estágio final do pipeline
- Uma string em into cria automaticamente a coleção de destino
- Padrões: whenMatched merge, whenNotMatched insert
🏷️ Tags Relacionados
💡 Casos Relacionados
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre $merge e $out?
A$out substitui a coleção inteira; $merge atualiza por chave, anexa incrementalmente e suporta destinos em outros bancos de dados.
QEle pode gravar em outro banco de dados?
ASim, por meio de uma string 'db.coll' ou de um objeto { db, coll }.
QComo chaves duplicadas são tratadas?
AwhenMatched decide: merge mescla campos, replace substitui o documento e keepExisting mantém o original.
