MongoDB
Explica cómo ejecutar subpipelines paralelos con $facet, clasificar valores con $bucket y construir respuestas con varias métricas desde una sola entrada.
$facet ejecuta varias subpipelines sobre el mismo conjunto de entrada y devuelve sus resultados dentro de un único documento. $bucket y $bucketAuto agrupan valores en rangos. Juntos permiten construir páginas con datos y metadata, histogramas y reportes multidimensionales.
entrada filtrada
↓
$facet
/ \
data summaryEjemplo de página con resultados y total:
db.orders.aggregate([
{
$match: {
businessId,
status: 'confirmed'
}
},
{
$facet: {
data: [
{ $sort: { createdAt: -1, _id: -1 } },
{ $limit: 20 },
{
$project: {
customer: 1,
total: 1,
createdAt: 1
}
}
],
metadata: [
{ $count: 'total' }
]
}
}
]);El $match se ejecuta una vez y ambas ramas reciben el resultado.
Sin facet, la aplicación puede ejecutar una query para datos y otra para total. Eso permite optimizar y escalar cada operación por separado, pero son dos viajes y pueden observar estados distintos.
$facet produce ambas salidas desde la misma pipeline, aunque añade trabajo y memoria. No siempre es mejor: un count exacto puede ser mucho más costoso que obtener veinte documentos.
{
data: [/* documentos */],
metadata: [
{ total: 1842 }
]
}Si no hay resultados, metadata puede quedar vacío. La aplicación debe normalizar:
const total = result.metadata[0]?.total ?? 0;Un $facet como primer stage puede impedir uso eficiente de índices y hacer que cada rama reciba toda la colección. Coloca filtros selectivos y, cuando corresponda, un sort respaldado por índice antes.
$match indexado
→ 5.000 documentos
→ $facetCada subpipeline procesa la entrada. Si tres ramas repiten un $unwind costoso, ese trabajo ocurre tres veces.
Puedes mover transformaciones comunes antes del facet, siempre que no aumenten innecesariamente la entrada y sean semánticamente compartidas.
Las subpipelines tienen límites de memoria y el documento final sigue sujeto al máximo BSON. allowDiskUse no elimina todos los límites específicos de facet. Verifica documentación de la versión objetivo.
No intentes devolver miles de resultados dentro de múltiples arrays en un solo documento.
Agrupa por límites definidos:
db.products.aggregate([
{
$match: {
businessId,
active: true
}
},
{
$bucket: {
groupBy: '$price',
boundaries: [
Decimal128('0'),
Decimal128('10000'),
Decimal128('50000'),
Decimal128('100000')
],
default: 'other',
output: {
count: { $sum: 1 },
averagePrice: { $avg: '$price' }
}
}
}
]);Cada boundary define rangos. Deben estar ordenados y usar tipos compatibles con groupBy.
Recibe valores fuera de los boundaries o que no encajan. Si no existe default, esos valores pueden provocar error según el stage.
No mezcles silenciosamente tipos inválidos con un rango “other” sin observarlos: podrían indicar schema drift.
Solicita un número aproximado de buckets:
{
$bucketAuto: {
groupBy: '$total',
buckets: 5,
output: {
count: { $sum: 1 }
}
}
}Los límites dependen de la distribución. Es útil para exploración, pero no ofrece categorías de negocio estables entre ejecuciones.
Para filtros de interfaz como “0–50k, 50k–100k”, usa $bucket con límites explícitos.
Un histograma puede ocultar outliers si los rangos son demasiado amplios. $bucketAuto puede producir rangos poco intuitivos cuando hay muchos valores repetidos o distribuciones sesgadas.
Verifica:
Una interfaz puede necesitar productos y conteos por categoría y rango:
{
$facet: {
products: [
{ $sort: { relevance: -1 } },
{ $limit: 20 }
],
categories: [
{
$group: {
_id: '$categoryId',
count: { $sum: 1 }
}
}
],
priceRanges: [
{
$bucket: {
groupBy: '$price',
boundaries: [0, 50000, 100000, 500000],
default: 'other'
}
}
]
}
}Esta capacidad no sustituye automáticamente un motor de búsqueda especializado. Relevancia, análisis lingüístico y faceting a gran escala pueden pertenecer a MongoDB Search u otra herramienta.
Facet con count exacto obliga a recorrer todas las coincidencias para calcular total, aunque solo devuelva veinte items. En colecciones grandes considera:
hasNextPage con limit + 1;La experiencia de usuario rara vez necesita un count exacto en cada request.
Nombra ramas según responsabilidad:
data
summary
qualityIssuesEvita devolver una estructura gigantesca difícil de versionar. Cada rama debe tener propósito, límites y pruebas.
db.orders.aggregate([
{
$match: {
businessId,
confirmedAt: { $gte: start, $lt: end },
status: 'confirmed'
}
},
{
$facet: {
totals: [
{
$group: {
_id: null,
orders: { $sum: 1 },
revenue: { $sum: '$total' },
averageTicket: { $avg: '$total' }
}
}
],
byPaymentMethod: [
{
$group: {
_id: '$payment.method',
count: { $sum: 1 },
revenue: { $sum: '$total' }
}
},
{ $sort: { revenue: -1 } }
],
latestOrders: [
{ $sort: { confirmedAt: -1, _id: -1 } },
{ $limit: 5 },
{ $project: { customer: 1, total: 1, confirmedAt: 1 } }
]
}
}
]);Todas las ramas comparten tenant, periodo y estado. Si este dashboard se consulta constantemente, puede ser mejor materializar métricas.
Cada rama puede devolver array vacío.
Múltiples ramas con muchos resultados pueden superar 16 MiB.
Los límites dejan de representar categorías coherentes.
Debes conocer si el límite inferior es inclusivo y el superior exclusivo según la semántica del stage.
La rama metadata domina la latencia.
Falla la pipeline completa; no hay éxito parcial por facet.
Procesa toda la colección.
Hace costosa cada página.
Multiplica trabajo.
Los límites cambian con los datos.
Valores fuera de rango fallan o desaparecen.
Supera memoria o BSON.
$facet comparte una entrada entre múltiples análisis, pero duplica el trabajo específico de cada rama y concentra las salidas en un documento. $bucket ofrece rangos estables; $bucketAuto, exploración adaptativa. Úsalos con filtros tempranos, cardinalidad controlada y una necesidad real de resultados paralelos.
$facet frente a dos queries?$match antes?$bucket y $bucketAuto?Window functions.