$project (Projeção)
Última atualização: 2026-10-09
$project (Projeção)
$project é o estágio de projeção: ele seleciona ou exclui campos, ou calcula novos, mapeando cada documento para uma nova forma. Diferente de $addFields, ele produz por padrão apenas _id e os campos explicitamente listados: 1 inclui, 0 exclui, e uma expressão cria um novo campo. Use-o para encolher documentos, renomear campos ou achatar objetos embutidos. Inclusão e exclusão não podem ser misturadas (exceto _id).
| Categoria | Estágios Principais |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $project: { <campo>: <1 ou 0 ou expressão>, ... } }⚙️ Parâmetros
| projeção de campos | Nomes de campo mapeados para 1 (incluir), 0 (excluir) ou uma expressão de agregação (campo calculado). |
|---|
Retorno：Fluxo de documentos projetado
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $project: mantém name, calcula total
db.orders.aggregate([
{ $project: { _id: 0, name: 1, total: { $multiply: ['$price', '$qty'] } } }
])Saída：
// Cada doc agora tem apenas name e total
{ "name": "Pen", "total": 150 }
{ "name": "Book", "total": 30 }📌 Notas
- $project é uma lista de permissões: campos não listados são descartados
- Inclusão e exclusão não podem ser misturadas (exceto _id)
- Caminhos pontilhados como 'detail.price' renomeiam ou achatam campos embutidos
🏷️ Tags Relacionados
💡 Casos Relacionados
Pipelines de agregação avançados: expressões e transformações complexas
Introdução aos pipelines de agregação: o método `aggregate` e o estágio básico
Prática: CRUD para um sistema de comentários de blog
Fluxos de alterações: monitoramento de alterações em tempo real
$facet + $bucket + Pesquisa de texto/geoespacial
$lookup e associações com múltiplos conjuntos
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre $project e $addFields?
A$addFields mantém todos os campos originais e adiciona novos; $project descarta campos não listados por padrão, usado para aparar ou reconstruir a forma do documento.
Q$project pode excluir vários campos de uma vez?
ASim, defina todos como 0, ex.: { $project: { secret: 0, log: 0 } }, o que mantém todos os outros campos.
Q$project muda a ordem dos campos?
AOs campos de saída seguem a ordem escrita na projeção, independentemente da ordem do documento original.
