Módulo 3: Loops e Iteraciones

SplitInBatches: El Nodo Principal de Loops

Siguiente →

Descripción de la cápsula

SplitInBatches es el nodo central para iteración explícita en n8n. Su trabajo es simple en concepto: toma N items de entrada y los divide en lotes del tamaño que tú elijas. Cada lote se procesa por una rama del workflow, y SplitInBatches espera a que termine antes de mandar el siguiente lote. El resultado: control fino sobre velocidad, paralelismo y orden.

Es el nodo que más confunde al inicio porque tiene un modelo de ejecución diferente al resto. La mayoría de los nodos hacen "input → procesar → output". SplitInBatches hace "input → procesar lote 1, esperar, procesar lote 2, esperar...". Es más cercano a un for loop que a una transformación.

En esta cápsula vas a aprender cómo funciona, los parámetros clave, los 3 modos de uso, y los errores comunes al implementarlo.

Lo que vas a aprender

Al terminar esta cápsula serás capaz de:

  • ✅ Entender el modelo de ejecución de SplitInBatches
  • ✅ Configurar batch size correctamente para el caso
  • ✅ Aplicar los 3 modos de uso comunes
  • ✅ Conectar SplitInBatches al loop correctamente
  • ✅ Saber cuándo NO usarlo (iteración implícita es suficiente)

El modelo: how it works

SplitInBatches funciona como un cajero en banco. Llegan 100 clientes (items). El cajero atiende de a 10 (batch size). Mientras atiende los 10, los otros 90 esperan en cola. Cuando termina con esos 10, los siguientes 10 pasan. Hasta procesar los 100.

Diferencia clave con iteración implícita: los 10 del batch sí se procesan en paralelo (relativamente). Pero los lotes son secuenciales — el batch 2 espera a que termine el batch 1.

Pseudocódigo equivalente

para cada batch de 10 items:
    procesa los 10 items (pueden ser en paralelo)
    espera a que terminen
    pasa al siguiente batch

Conexión visual: el loop

SplitInBatches se conecta de manera distinta a otros nodos. Tiene 2 salidas distintas:

[Trigger] → [SplitInBatches]
              │
              ├─→ [Loop output] ──→ [proceso del batch] ──┐
              │                                            │
              │  ←─────────────────────────────────────────┘
              │  (vuelve al SplitInBatches)
              │
              └─→ [Done output] ──→ [acción post-loop]
  • Loop output: se conecta a los nodos que procesan cada batch
  • El último nodo del procesamiento vuelve a conectar al SplitInBatches (el loop)
  • Done output: se conecta a lo que ejecutas después de procesar todos los batches

Esta estructura "circular" es lo que confunde al principio. Vas a verlo dibujado más abajo.

Configuración: parámetros

Batch Size

Tamaño de cada lote. El parámetro más importante.

Cómo elegir:

  • Si llamas API con rate limit: batch size = items por unidad de tiempo permitidos (ej. 10/segundo → batch de 10 + Wait 1s)
  • Si timeout es el concern: batch size = items que procesas dentro del timeout
  • Si memoria es el concern: batch size pequeño (10-50)
  • Por default razonable: 10-50 para casos típicos

Options → "Reset" (importante)

Reset controla si SplitInBatches recuerda el estado entre ejecuciones del workflow.

  • OFF (default): cada ejecución del workflow inicia con batch 1
  • ON: mantiene estado — útil para loops que pausan/reanudan

Para la mayoría de casos, OFF está bien.

La conexión correcta del loop

Esto es lo que más confunde. La conexión es:

                    ┌─────────────────────────────────────┐
                    │                                     │
   [Trigger] → [SplitInBatches] → [proceso del batch]    │
                       │                                  │
                       │                       loop back  │
                       │                                  │
                       └─→ [Done] → [post-loop]           │
                                                          │
                                                          ▼
                              último nodo del proceso ←───┘
                              vuelve a SplitInBatches

Pasos:

  1. Agregas SplitInBatches después del nodo que produce N items
  2. De la salida principal (Loop), conectas el procesamiento de cada batch (1 o N nodos)
  3. El último nodo del procesamiento se conecta de vuelta a SplitInBatches (input!)
  4. La salida Done (segunda salida) se conecta a lo post-loop

n8n detecta el loop y sabe que el último nodo "alimenta" SplitInBatches para el siguiente batch.

Los 3 modos de uso

Modo 1: Rate limiting (más común)

Caso: llamar una API con rate limit.

[Lista 1000 items] → [SplitInBatches batch=10] → [HTTP Request] → [Wait 1s] → loop back
                            │
                            └─→ Done → [resumen]

Procesas de a 10 items. Wait 1 segundo entre batches. Total 100 segundos para 1000 items.

Modo 2: Procesamiento secuencial estricto

Caso: procesar items en orden, esperando que cada uno termine antes del siguiente.

[SplitInBatches batch=1] → [proceso] → loop back
                                │
                                └─→ Done → fin

Batch de 1 = procesa de a uno, secuencialmente. Más lento pero garantizado en orden.

Modo 3: Lotes grandes con timeout management

Caso: procesas 10,000 items. Cada batch toma 30s. Workflow no puede tardar más de 5min.

[SplitInBatches batch=100] → [proceso del batch] → loop back
                                │
                                └─→ Done

Batch de 100 = 100 batches × 30s = 50 min total. Aún largo, pero manejable. Para más, considera dividir en varios workflows con Schedule encadenado.

Cuándo usar SplitInBatches

Usa cuando:

  • Procesando 100+ items
  • API tiene rate limit que la iteración implícita viola
  • Necesitas pausa entre procesamientos
  • Quieres orden estricto (batch=1)
  • Memoria es problema con todos los items a la vez

NO uses cuando:

  • Procesas <50 items (overhead innecesario)
  • Cada item es independiente y no hay rate limit (implícita es más rápida y simple)
  • El workflow ya funciona bien con implícita

Pattern: SplitInBatches + Wait + HTTP

El más común. Ejemplo:

Caso: enriquecer 200 leads con API de Clearbit

Clearbit tiene rate limit 600/min = 10/segundo. Si pasas 200 leads con iteración implícita, n8n manda 200 requests "lo más rápido posible" → algunos timeout o son rate-limited.

Solución:

[Sheets: 200 leads]
   │
[SplitInBatches batch=10]
   │ (loop)
   ▼
[HTTP Request: Clearbit API por cada lead del batch]
   │
[Wait: 1 second]
   │
   └──→ loop back to SplitInBatches
   │
[Done]
   │
[Set: agregar timestamp]
   │
[Sheets: append resultados]

Cálculo:

  • 200 leads / 10 por batch = 20 batches
  • Cada batch: 10 HTTP en paralelo (~1-2s) + Wait 1s
  • Total: ~40-60 segundos
  • Sin exceder rate limit

Errores comunes

Error 1: No conectar el loop back

Qué pasa: Conectas SplitInBatches → procesamiento → siguiente nodo. No conectas back a SplitInBatches. Solo se procesa el primer batch.

Cómo evitar: El último nodo del procesamiento del batch debe conectarse al input de SplitInBatches. Verifica visualmente que el loop se cierra.

Error 2: Batch size muy chico

Qué pasa: Batch=1 con 1000 items y operaciones rápidas. Cada batch tiene overhead. Total más lento que iteración implícita.

Cómo evitar: Usar batch size más grande cuando no hay rate limit que justifique el 1. Default razonable: 10-50.

Error 3: Batch size muy grande

Qué pasa: Batch=500 con API de rate limit 100/min. 500 requests en paralelo en cada batch → rate limit.

Cómo evitar: Batch size ≤ requests por unidad de tiempo del rate limit.

Error 4: Done output conectado al procesamiento del batch

Qué pasa: Por confusión, conectas Done a un nodo que debería ser parte del loop. Done solo se ejecuta cuando termina todo — los datos del último batch no fluyen por ahí.

Cómo evitar: Recordar las 2 salidas:

  • Loop output → procesamiento del batch
  • Done output → post-loop

Error 5: Olvidar Aggregate al final

Qué pasa: Procesas 1000 items con SplitInBatches. Cada batch produce resultados. Esperabas que el final tuviera "todos los resultados juntos", pero solo tiene los del último batch.

Cómo evitar: Si necesitas todos los resultados juntos al final, usar Aggregate o guardar en Sheet/DB durante el loop.

Diferencia clave con loops de programación

Si vienes de programación, hay una diferencia importante:

En código:

for (let i = 0; i < items.length; i++) {
  process(items[i]);
}

Procesa de a uno, en orden.

En SplitInBatches:

batch_size = 10
Procesa 10 a la vez (paralelo dentro del batch)
Espera
Siguiente 10

Implicación: dentro de un batch, n8n procesa los items paralelamente. Si necesitas estricto orden, batch_size = 1.

Ejercicio: configurar SplitInBatches

Objetivo: practicar la conexión correcta.

Tu tarea

Construye este workflow:

  1. Manual Trigger
  2. Code node (o Function): produce un array de 50 items con id: 1, 2, 3, ...50
  3. SplitInBatches batch=5
  4. Set node: agrega processed_at: $now
  5. Wait 2 segundos
  6. Sheet Append (a un sheet de log) — agrega el item
  7. Conecta el último nodo (Sheet) de vuelta a SplitInBatches
  8. Conecta Done a un Slack que diga "Proceso completo"

Esperado

  • 50 items / 5 = 10 batches
  • Cada batch tarda ~3 segundos (2s Wait + procesamiento)
  • Total ~30 segundos
  • Al final: 50 filas en el Sheet log + 1 mensaje de "completo" en Slack

Resumen y siguiente paso

  • SplitInBatches divide N items en lotes de tamaño configurable, procesa secuencialmente
  • 2 salidas: Loop (procesar batch) y Done (post-loop)
  • Conectar loop back: último nodo del procesamiento → input de SplitInBatches
  • 3 modos: rate limiting, secuencial estricto (batch=1), lotes grandes
  • Cuándo usar: 100+ items, rate limits, orden estricto, memoria
  • 5 errores: no conectar loop, batch muy chico, batch muy grande, Done conectado al batch, olvidar Aggregate

Antes de avanzar deberías poder:

  • Configurar SplitInBatches con batch size apropiado
  • Conectar el loop back correctamente
  • Distinguir Loop output de Done output

Lo que sigue (cápsula 04):

Profundizamos patrones de loop comunes con SplitInBatches: procesar todos los items (la más común), loops con condición de stop, paginación de APIs, retry de items que fallaron.

Recursos adicionales

  1. SplitInBatches Documentation - Referencia.
  2. Looping in n8n (Blog) - Patrones con ejemplos.

Creado: Mayo 11, 2026 Versión: 1.0

← AnteriorIteración Implícita en n8nSiguiente →Patrones de Loop con SplitInBatches