$setField (Definir Campo pelo Nome)
Última atualização: 2026-10-09
$setField (Definir Campo pelo Nome)
$setField adiciona ou atualiza um campo nomeado em um documento e retorna um documento novo sem alterar a entrada. A sintaxe é { $setField: { field: nome-do-campo, input: documento, value: expressão } }, e field aceita uma expressão dinâmica. Um valor null remove o campo. É usado quando nomes de campos contêm caracteres especiais ou precisam ser calculados dinamicamente. Uma entrada null ou ausente retorna null. Diferente do estágio $set, $setField funciona dentro de expressões aninhadas e suporta nomes de campos dinâmicos.
| Categoria | Literal, Variável e Objeto |
|---|---|
| Versão do MongoDB | 5.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $setField: { field: <nome-do-campo>, input: <expressão de documento>, value: <expressão> } }⚙️ Parâmetros
| field | O nome do campo como string ou uma expressão que resolva para uma string. |
|---|---|
| input | Documento de destino; uma entrada null ou ausente resulta em null. |
| value | O valor a definir; null remove o campo. |
Retorno：Um novo documento com o campo definido; null quando a entrada é null ou está ausente
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $setField: adicionar um campo de taxa de imposto a cada pedido
db.orders.aggregate([
{ $project: {
doc: { $setField: { field: 'taxRate', input: '$$CURRENT', value: 0.08 } }
} }
])Saída：
{ '_id': 1, 'doc': { '_id': 1, 'price': 100, 'taxRate': 0.08 } }
{ '_id': 2, 'doc': { '_id': 2, 'price': 50, 'taxRate': 0.08 } }📌 Notas
- Retorna um documento novo; a entrada não é alterada
- Um valor null remove o campo
- Vem em pares com $getField para nomes de campos dinâmicos
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QO $setField modifica o documento original?
ANão — documentos são imutáveis em pipelines; $setField retorna um documento novo.
QComo removo um campo com $setField?
ADefina value como null e o campo é removido.
QComo $setField e o estágio $set diferem?
A$set lida apenas com nomes de campos estáticos, enquanto $setField suporta nomes dinâmicos e expressões aninhadas.
