n8n Loop Over Items: батчинг и автоматический цикл

n8n обычно обрабатывает несколько записей полностью самостоятельно: node принимает список items, выполняет свою логику для каждого отдельного item и возвращает результаты снова в виде списка. Для большинства workflow тебе, таким образом, вообще не нужен явный цикл. Но как только внешний сервис разрешает лишь немного запросов в секунду, node обрабатывает только первый item, или нужно запросить пагинированный API с неизвестным числом страниц, автоматической обработки уже недостаточно. Именно для этого в n8n существует node Loop Over Items, ранее известный под названием Split in Batches.

В этой статье мы покажем тебе, как работает автоматический цикл в n8n, как подробно работает node Loop Over Items и на что тебе следует обращать внимание в отношении размера батча и производительности, чтобы твои workflow работали стабильно и без ошибок лимита запросов.

Как n8n автоматически перебирает items

Согласно официальной документации n8n о циклах , node в n8n в принципе принимают любое количество items, обрабатывают их и снова возвращают результаты. Если ты, например, соединишь node хранилища данных с пятью записями клиентов с node Slack, n8n автоматически отправит пять отдельных сообщений, по одному на запись. Строить собственный цикл для этого не нужно, этим занимается движок в фоновом режиме.

Если ты вместо этого хочешь обработать только первый item входящей записи, ты активируешь в настройках node на вкладке Settings опцию Execute Once. При этом node игнорирует все остальные items и обрабатывает только первую запись, что подходит, например, для разовых уведомлений.

Node Loop Over Items подробно

Для всех случаев, когда автоматической обработки недостаточно, n8n предоставляет node Loop Over Items . Node сохраняет исходные входные данные и при каждом проходе возвращает фиксированное количество items через выход loop . Когда все батчи обработаны, он объединяет обработанные данные и возвращает их через выход done .

Здесь важны две настройки:

• Batch Size: определяет, сколько items node возвращает за один проход. Если установить значение на 1, n8n обрабатывает каждый item по отдельности, один за другим.
• Reset: заново инициализирует node при каждом проходе свежими входными данными. Это полезно для пагинированных запросов API, при которых заранее неизвестно общее число страниц. Важно согласно документации: при включённом Reset обязательно нужно предусмотреть корректное условие остановки, иначе цикл будет выполняться бесконечно.

На практике для этого используются выражения вроде `{{$("Loop Over Items").context["noItemsLeft"]}}`, чтобы проверить, остались ли ещё items, или `{{$("Loop Over Items").context["currentRunIndex"]}}`, чтобы считать индекс текущего прохода и использовать его как условие остановки в node IF.

Когда нужно строить цикл вручную

Согласно документации, некоторые node в принципе обрабатывают только первый item или все items сразу, вместо того чтобы корректно итерировать. К ним относятся, среди прочего, CrateDB, Microsoft SQL, MongoDB и TimescaleDB при операциях вставки и обновления, node Code, а также node Execute Workflow в режиме "Run Once for All Items", node HTTP Request при ручной пагинации, операция Redis Info и node RSS Read. Для этих исключений цикл строится вручную: ты снова соединяешь выход node с предыдущим node и добавляешь node IF, который проверяет чёткое условие остановки.

Размер батча и производительность на практике

Размер батча напрямую определяет, насколько стабильно и быстро выполняется workflow. Небольшой размер батча, например от 1 до 5 items за проход, щадит внешние API со строгими лимитами запросов, но увеличивает общее время выполнения, потому что n8n приходится обрабатывать больше отдельных проходов. Большой размер батча ускоряет workflow, но повышает риск того, что сервис ответит ошибкой 429 или что workflow будет труднее отследить при ошибке в середине большого батча. На практике лучше всего тестировать с умеренным размером батча и наблюдать за временем выполнения, а также возможными ответами об ошибках целевого сервиса, прежде чем дальше увеличивать значение.

Особенно для продуктивных workflow с большим числом внешних вызовов стоит целенаправленно комбинировать Loop Over Items с паузами между батчами, чтобы API не перегружались и ты сохранял контроль над выполнением. Если ты хочешь не только строить свои workflow n8n, но и стабильно эксплуатировать их долгосрочно, мы поддерживаем тебя в NordFlux в рамках нашей автоматизации n8n именно в вопросах производительности и лимитов запросов, чтобы твои цифровые сотрудники работали надёжно.

Часто задаваемые вопросы

В чём разница между автоматическим циклом и node Loop Over Items?

Автоматический цикл происходит сам по себе почти для каждого node n8n: node обрабатывает каждый входящий item по отдельности и передаёт список результатов дальше, без того чтобы тебе нужно было что-то настраивать для этого. Node Loop Over Items вступает в игру только тогда, когда ты хочешь явно разбить обработку на контролируемые части, например, чтобы соблюдать лимиты запросов или обслуживать node, которые могут обрабатывать только один item за раз.

Как предотвратить бесконечный цикл с node Loop Over Items?

Бесконечный цикл возникает обычно тогда, когда опция Reset включена, но не проверяется никакое условие остановки. В этом случае добавь node IF, который проверяет, например, выражение `{{$("Loop Over Items").context["noItemsLeft"]}}`, и направляй workflow при достижении конца в ветку done вместо возврата обратно в цикл.

Какой размер батча выбрать для запросов к API?

Универсального числа не существует, потому что у каждого сервиса свои лимиты запросов. В качестве отправной точки подходят небольшие значения от 1 до 10 items на батч, которые затем ты постепенно корректируешь на основе фактического времени ответа и возможных сообщений об ошибках целевого сервиса.

Нужно ли мне самому строить цикл для каждого node?

Нет, большинство node n8n обрабатывают несколько items автоматически без дополнительной настройки. Только для ограниченного числа node-исключений, например определённых node баз данных или node HTTP Request при ручной пагинации, тебе нужно строить цикл самому с помощью node Loop Over Items или обратно соединённого node IF.

Могу ли я внутри цикла обращаться к данным из предыдущих проходов?

Да, через свойства context node Loop Over Items, такие как currentRunIndex, ты можешь определить текущий проход, а через ссылки на более ранние node в workflow можно также включать данные из предыдущих шагов. Для более сложного промежуточного хранения на протяжении нескольких проходов дополнительно рекомендуется node Set или Code, который собирает промежуточные результаты.