$unwind (Desestruturar Array)
Última atualização: 2026-10-09
$unwind (Desestruturar Array)
$unwind desestrutura um campo de array, emitindo um documento por elemento enquanto copia todos os outros campos. Use-o para achatar arrays antes de agrupamentos, estatísticas ou lookups. Documentos com arrays vazios, ausentes ou null são descartados por padrão; preserveNullAndEmptyArrays os mantém e includeArrayIndex expõe o índice do elemento. Desestruturar multiplica a contagem de documentos, então orce os estágios seguintes de acordo.
| Categoria | Estágios Principais |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $unwind: { path: "$arrayField", preserveNullAndEmptyArrays: <bool>, includeArrayIndex: "<campoDeIndice>" } }⚙️ Parâmetros
| path | Caminho do campo de matriz a desconstruir, prefixado com $. |
|---|---|
| preserveNullAndEmptyArrays | Quando true, mantém documentos com matrizes vazias, ausentes ou null. |
| includeArrayIndex | Gera o índice de cada elemento na matriz original para este campo. |
Retorno：Fluxo de documentos achatado (um documento por elemento de matriz)
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $unwind: desestrutura o array tags
db.inventory.aggregate([
{ $unwind: { path: '$tags', includeArrayIndex: 'idx' } }
])Saída：
{ "_id": 1, "item": "Pen", "tags": "A", "idx": 0 }
{ "_id": 1, "item": "Pen", "tags": "B", "idx": 1 }📌 Notas
- Documentos com arrays vazios, ausentes ou null são descartados a menos que preserveNullAndEmptyArrays esteja definido
- includeArrayIndex expõe o índice original do elemento
- Combine $unwind com $group ou $lookup para estatísticas ou junções por elemento
🏷️ Tags Relacionados
💡 Casos Relacionados
Pipelines de agregação avançados: expressões e transformações complexas
Prática: CRUD para um sistema de comentários de blog
$lookup e associações com múltiplos conjuntos
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QOs documentos produzidos por $unwind compartilham o mesmo _id?
ASim. _id e todos os outros campos são copiados literalmente; apenas o campo de array vira um único elemento.
QO que acontece quando $unwind encontra um array vazio?
AO documento é descartado por padrão; defina preserveNullAndEmptyArrays como true para mantê-lo.
QVários campos de array podem ser desestruturados de uma vez?
AUm $unwind lida com um array. Encadeie vários estágios $unwind para vários arrays, o que produz um produto cartesiano.
