MongoDB
Explica cómo MongoDB entrega resultados por batches mediante cursores, cómo iterarlos, cerrarlos y evitar cargar colecciones completas en memoria.
Un cursor representa una consulta cuyos resultados se obtienen y consumen por batches. Permite procesar conjuntos mayores que la memoria disponible y separa la definición de la query de su consumo.
find / aggregate
↓
cursor en cliente
↓
primer batch
↓
getMore según consumo
↓
cierre o agotamientoUn cursor no contiene inmediatamente todos los documentos. El driver solicita más resultados al servidor conforme la aplicación avanza.
Cargar un millón de documentos con toArray() puede:
El cursor permite iterar y liberar cada documento después de procesarlo.
const cursor = orders.find(
{
businessId,
status: 'confirmed'
},
{
projection: {
total: 1,
createdAt: 1
}
}
).sort({ createdAt: 1, _id: 1 });En muchos drivers la query todavía no se ejecuta completamente al crear el cursor. La ejecución comienza cuando se solicita el primer resultado.
for await (const order of cursor) {
await processOrder(order);
}El flujo procesa un documento, espera al consumidor y continúa. Es apropiado para exports, migraciones y jobs.
La función processOrder debe manejar errores e idempotencia. Si falla después de aplicar un efecto externo, reanudar podría repetirlo.
const orders = await cursor.toArray();Es adecuado cuando el resultado está estrictamente acotado, por ejemplo una página de 20 elementos. No es apropiado para colecciones o exports sin límite.
El problema no es el método en sí, sino utilizarlo sin conocer cardinalidad y tamaño de documentos.
El servidor devuelve resultados por batches. batchSize controla una preferencia sobre cuántos documentos viajan por lote:
const cursor = orders.find(filter).batchSize(500);El tamaño debe medirse con documentos reales. Quinientos documentos de 1 KiB no equivalen a quinientos de 500 KiB.
limit(1000) limita el total. batchSize(100) orienta cómo se entrega.
limit = máximo total
batchSize = tamaño aproximado de cada entregaNo confundas batch size con paginación pública. Los batches son un detalle de consumo entre driver y servidor.
El servidor puede mantener estado para cursores no agotados. Cursores abandonados consumen recursos hasta cerrarse o expirar según comportamiento y opciones.
Cuando interrumpes antes de agotar:
const cursor = orders.find(filter);
try {
for await (const order of cursor) {
if (shouldStop(order)) break;
}
} finally {
await cursor.close();
}Cursores inactivos pueden expirar. Opciones como noCursorTimeout existen para casos administrativos, pero aumentan riesgo de recursos olvidados.
Un job largo debe:
Si MongoDB produce más rápido que el destino, la aplicación debe frenar.
for await (const order of cursor) {
await output.write(transform(order));
}Esperar a output.write evita acumular miles de elementos.
En streams, conecta manejo de drain, errores y cancelación. Un cursor no resuelve automáticamente la velocidad del consumidor.
Para jobs reanudables, combina sort estable y checkpoint:
{ createdAt: 1, _id: 1 }Después de procesar y confirmar efectos:
checkpoint = último createdAt + _id confirmadoAl reiniciar, consulta desde la frontera. El checkpoint debe guardarse después del efecto, o utilizar una operación idempotente que tolere repetición.
Un cursor normal no siempre representa una snapshot inmutable de horas. Inserts, updates y deletes concurrentes pueden afectar lo que se observa según operación, read concern y topología.
Si necesitas un export consistente:
asOf;Un cursor abierto en un secondary puede observar lag. Si ocurre failover o error, la capacidad de continuar depende de driver y tipo de operación. No asumas que cualquier cursor se reanuda automáticamente.
Change Streams sí tienen resume tokens y semántica específica; un cursor de find no es un Change Stream.
Capped collections permiten tailable cursors para observar documentos nuevos en escenarios específicos.
cursor llega al final
→ espera nuevos inserts
→ continúaNo ofrecen todas las garantías de un broker ni sustituyen Change Streams. Deben utilizarse solo cuando el workload y las limitaciones encajan.
aggregate() también devuelve cursor:
const cursor = orders.aggregate(pipeline, {
allowDiskUse: true
});Aunque el resultado se entregue por batches, stages como $sort o $group pueden necesitar procesar gran parte del input antes de producir resultados. Streaming de salida no significa que toda la pipeline use memoria constante.
Evita acumular resultados transformados:
for await (const document of cursor) {
const row = mapToCsvRow(document);
await writer.write(row);
}Maneja tipos BSON:
Una conversión incorrecta puede perder precisión durante export.
Un cursor puede fallar por:
Utiliza try/finally, AbortSignal cuando la API lo soporte y manejo diferenciado de errores.
Cancelar en cliente no garantiza siempre que todo el trabajo del servidor desaparezca instantáneamente; observa operaciones largas y utiliza límites como maxTimeMS donde corresponda.
La memoria total incluye:
Aunque iteres, guardar cada resultado en otra lista anula el beneficio.
La iteración no entra; no es error.
Un batch pequeño todavía puede consumir mucha memoria.
El checkpoint puede causar repetición o pérdida según orden de confirmación.
El job debe reanudar por rango, no confiar únicamente en el objeto vivo.
La reanudación puede repetir u omitir documentos.
Puede moverse durante el recorrido.
Carga todo en memoria.
Deja recursos hasta cleanup.
Son niveles diferentes.
Acumula buffers.
Puede perder documentos.
Los datos pueden cambiar durante el recorrido.
Es menos robusto que una estrategia reanudable por rangos.
Un cursor es una estrategia de consumo incremental, no una snapshot automática ni una cola. Su confiabilidad depende de límites, backpressure, cierre, orden estable, checkpoints e idempotencia. toArray() es seguro solo cuando el conjunto está acotado.
limit y batchSize?Aggregation Pipeline.