MongoDB
Explica cómo $unwind descompone arrays en documentos individuales, conserva vacíos, añade índices y cambia cardinalidad dentro del pipeline.
$unwind descompone un array y produce un documento de salida por cada elemento. El resto de los campos se repite en cada salida.
{
_id: orderId,
items: [
{ productId: A, quantity: 2 },
{ productId: B, quantity: 1 }
]
}Después de:
{ $unwind: '$items' }se convierte conceptualmente en:
{ _id: orderId, items: { productId: A, quantity: 2 } }
{ _id: orderId, items: { productId: B, quantity: 1 } }Mientras un array permanece embebido, cada documento representa la unidad completa. Para agrupar, ordenar o filtrar cada elemento como una fila lógica, puede ser necesario expandirlo.
Casos frecuentes:
orders.items;N documentos
× promedio de elementos por array
≈ documentos después de $unwindSi 100.000 órdenes tienen 20 items promedio, el siguiente stage procesa cerca de 2 millones de documentos lógicos. La cardinalidad debe estimarse antes de usarlo.
{
$unwind: '$items'
}Sintaxis completa:
{
$unwind: {
path: '$items',
includeArrayIndex: 'itemIndex',
preserveNullAndEmptyArrays: true
}
}Por defecto, documentos con array missing, null o vacío pueden no producir salida.
Con:
preserveNullAndEmptyArrays: trueel documento continúa en la pipeline, lo que permite conservar entidades sin elementos relacionados.
Ejemplo: un reporte que debe mostrar productos con cero ventas necesita conservar productos sin coincidencias después de un lookup y unwind.
Añade la posición original:
{
$unwind: {
path: '$items',
includeArrayIndex: 'itemIndex'
}
}Es útil cuando el orden tiene significado, por ejemplo pasos de una receta. No debe utilizarse como identidad estable si el array puede reordenarse.
El comportamiento con valores escalares, null y missing debe probarse según versión y forma. Un schema coherente evita depender de conversiones implícitas.
Antes de unwind, puede validarse:
{
$match: {
items: { $type: 'array' }
}
}En auditorías, separa documentos inválidos en vez de descartarlos silenciosamente.
[
{ $match: { businessId, status: 'confirmed' } },
{ $unwind: '$items' }
]Reduce órdenes antes de expandir.
[
{ $unwind: '$items' },
{ $match: { 'items.quantity': { $gte: 5 } } }
]Filtra elementos individuales.
Cuando sea semánticamente posible, también puedes filtrar el array con $filter antes de unwind para reducir expansión:
{
$set: {
items: {
$filter: {
input: '$items',
as: 'item',
cond: { $gte: ['$$item.quantity', 5] }
}
}
}
}Cambia cardinalidad: una salida por elemento.
Transforma elementos y conserva un documento y un array.
Conserva algunos elementos y mantiene el array.
Usa unwind cuando stages posteriores necesitan tratar elementos como documentos. Usa map/filter cuando la unidad de salida debe seguir siendo el documento padre.
db.orders.aggregate([
{
$match: {
businessId,
status: 'confirmed',
confirmedAt: { $gte: start, $lt: end }
}
},
{ $unwind: '$items' },
{
$group: {
_id: '$items.productId',
units: { $sum: '$items.quantity' },
revenue: {
$sum: {
$multiply: ['$items.quantity', '$items.unitPrice']
}
}
}
},
{ $sort: { revenue: -1 } }
]);El input de $group es el número de líneas vendidas. Si cada orden contiene muchos items, ese volumen puede ser mucho mayor que la cantidad de órdenes.
A veces se expande, transforma y reconstruye:
[
{ $unwind: '$items' },
{
$set: {
'items.subtotal': {
$multiply: ['$items.quantity', '$items.unitPrice']
}
}
},
{
$group: {
_id: '$_id',
items: { $push: '$items' },
total: { $sum: '$items.subtotal' }
}
}
]Esto puede ser correcto, pero pierde campos si no se acumulan explícitamente y puede crear arrays grandes. Una expression $map suele ser mejor cuando no necesitas cambiar cardinalidad global.
orders
→ unwind items
→ unwind item.discountsLa cardinalidad se multiplica. Si hay 20 items y 5 descuentos por item, cada orden puede producir 100 salidas.
Unwind de dos arrays independientes puede crear producto cartesiano accidental:
3 items × 4 payments = 12 combinacionesEso puede duplicar sumas. Debes entender la relación entre arrays antes de expandir ambos.
$lookup devuelve un array. Para convertir un resultado one-to-one esperado:
[
{
$lookup: {
from: 'customers',
localField: 'customerId',
foreignField: '_id',
as: 'customer'
}
},
{
$unwind: {
path: '$customer',
preserveNullAndEmptyArrays: true
}
}
]Si aparecen varios clientes, quizá la supuesta unicidad no está protegida. Si no aparece ninguno, existe referencia colgante o filtro incompatible.
$unwind normalmente no usa un índice para la expansión misma. Los índices ayudan a stages anteriores como $match.
Optimiza:
Puede desaparecer de la salida.
Puede representar versión antigua; decide si conservar o auditar.
No equivale a array vacío.
Sí genera una salida correspondiente al elemento.
Produce explosión de cardinalidad.
includeArrayIndex captura posición original, pero grouping posterior puede no preservar orden sin sort.
Se procesan como elementos separados y pueden duplicar conteos.
Una pipeline pequeña consume millones de filas lógicas.
Crea producto cartesiano.
Falta preserveNullAndEmptyArrays cuando el reporte los necesita.
Los datos del padre desaparecen.
$map puede ser más simple.
Métricas infladas por joins o múltiples unwinds.
$unwind convierte elementos de array en documentos lógicos y cambia cardinalidad. Su poder está en permitir grouping y filtering por elemento; su riesgo es multiplicar trabajo y resultados. Toda pipeline con unwind debe estimar crecimiento y comprobar duplicaciones.
preserveNullAndEmptyArrays?$filter en vez de unwind?$push?$lookup.