> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Использование итератора

> Перебирайте массивы записей и выполняйте действия для каждого элемента.

Итератор позволяет перебирать массив записей и выполнять действия для каждой из них. Он необходим для рабочих процессов, которым нужно обрабатывать несколько записей, возвращённых действием Search Records или полученных через вебхуки.

## Когда использовать итератор

| Сценарий                         | Пример                                                |
| -------------------------------- | ----------------------------------------------------- |
| **Обработка результатов поиска** | Отправить письмо каждому найденному человеку          |
| **Обработка массивов вебхуков**  | Создать записи для каждого элемента по порядку        |
| **Массовые обновления**          | Обновить несколько записей с рассчитанными значениями |
| **Уведомления**                  | Оповестить нескольких людей о событии                 |

## Понимание итератора

Итератор ожидает на входе **массив**. Затем он:

1. Берёт первый элемент массива
2. Выполняет все действия внутри итератора с этим элементом
3. Переходит к следующему элементу
4. Повторяет, пока все элементы не будут обработаны

### Выбор массива для перебора

Большинство источников массивов (Search Records, поле массива вебхука, ручной триггер Bulk) можно выбрать непосредственно в селекторе переменных.

Когда шаг **Code** или **Logic Function** возвращает *массив верхнего уровня*, его вывод отображается в селекторе переменных как индексированные элементы (`0`, `1`, `2`, …). Чтобы перебирать массив целиком, выберите для этого шага параметр **Whole list** — тогда Iterator автоматически определит структуру каждого элемента списка.

## Базовая настройка

### Пример: отправка письма всем из результатов поиска

**Цель**: найти всех контактов в определённой компании и отправить каждому персонализированное письмо.

### Шаг 1: Поиск записей

1. Добавьте действие **Search Records**
2. Объект: **Люди**
3. Фильтр: Company равно "Acme Inc"
4. Это возвращает массив людей

### Шаг 2: Проверка наличия результатов

1. Добавьте действие **Фильтр**
2. Условие: `{{searchRecords.length}}` больше 0
3. Это предотвращает ошибки итератора при пустых результатах

### Шаг 3: Добавьте итератор

1. Добавьте действие **Iterator**
2. Входной массив: выберите `{{searchRecords}}`
3. Это создаёт цикл

### Шаг 4: Добавьте действия внутри итератора

Действия, добавленные после итератора, выполняются для каждого элемента:

1. Добавьте действие **Send Email** (внутри итератора)
2. Кому: `{{iterator.currentItem.email}}`
3. Тема: Привет, `{{iterator.currentItem.firstName}}`!
4. Текст письма: персонализированное сообщение с использованием полей текущего элемента

### Результат

Если Search Records возвращает 5 человек, то итератор:

* Отправляет письмо первому человеку
* Отправляет письмо второму человеку
* ... и так для всех 5

## Доступ к данным текущего элемента

Внутри итератора используйте `{{iterator.currentItem}}`, чтобы обратиться к текущей записи:

| Переменная                              | Описание                           |
| --------------------------------------- | ---------------------------------- |
| `{{iterator.currentItem}}`              | Весь объект текущей записи         |
| `{{iterator.currentItem.id}}`           | ID записи                          |
| `{{iterator.currentItem.email}}`        | Поле электронной почты             |
| `{{iterator.currentItem.company.name}}` | Название связанной компании        |
| `{{iterator.index}}`                    | Текущая позиция в массиве (с нуля) |

В селекторе переменных вы можете либо перейти к конкретному полю текущего элемента, либо выбрать **Use the whole item**, чтобы сослаться на весь текущий элемент (`{{iterator.currentItem}}`). Выбор всего элемента удобен, когда вы хотите передать полную запись непосредственно в следующий шаг по цепочке, вместо того чтобы заново собирать ее по полям.

## Типовые шаблоны

### Обновление нескольких записей

**Цель**: пометить все просроченные задачи как "Late"

```
1. Search Records (Tasks, Due Date < Today, Status ≠ Completed)
2. Filter (length > 0)
3. Iterator (searchRecords)
   └── Update Record
       - Object: Tasks
       - Record: {{iterator.currentItem.id}}
       - Status: Late
```

### Создание записей из массива

**Цель**: вебхук получает заказ с несколькими позициями; создайте запись для каждой

```
1. Webhook Trigger (receives items array)
2. Filter (items.length > 0)
3. Iterator (trigger.body.items)
   └── Create Record
       - Object: Order Items
       - Name: {{iterator.currentItem.name}}
       - Quantity: {{iterator.currentItem.qty}}
       - Related Order: {{trigger.body.orderId}}
```

### Условная обработка внутри цикла

**Цель**: отправлять письма только контактам с действительными адресами электронной почты

```
1. Search Records (People)
2. Iterator (searchRecords)
   └── Filter (currentItem.email is not empty)
       └── Send Email
           - To: {{iterator.currentItem.email}}
```

## Устранение неполадок

### "Iterator expects an array"

**Причина**: вы передали одну запись вместо массива.

**Решение**: убедитесь, что вы передаёте результат действия Search Records или поле-массив, а не одну запись.

```
✅ Correct: {{searchRecords}}
❌ Wrong: {{searchRecords[0]}}
```

### Итератор не запускается

**Причина**: массив пуст.

**Решение**: добавьте фильтр перед итератором, чтобы проверить длину массива:

```
Filter: {{searchRecords.length}} > 0
```

### Действия выполняются слишком много раз

**Причина**: действие Search Records вернуло больше записей, чем ожидалось.

**Решение**:

* Добавьте более точные фильтры в Search Records
* Установите ограничение в Search Records (макс. 200)
* Добавьте фильтр внутри итератора для дополнительных условий

## Особенности производительности

* **Расход кредитов**: каждая итерация потребляет кредиты на свои действия
* **Время**: обработка больших массивов занимает больше времени
* **Ограничения**: рассмотрите пакетную обработку очень больших операций
* **Лимиты скорости**: при большом числе итераций внешние вызовы API могут упираться в лимиты скорости

## Лучшие практики

1. **Всегда проверяйте длину массива** перед итератором, чтобы избежать ошибок
2. **Добавляйте фильтры внутри циклов**, если обрабатывать нужно не все элементы
3. **Переименуйте шаг Iterator**, чтобы он описывал, что именно перебирается
4. **Тестируйте на небольших массивах** перед обработкой больших наборов данных
5. Отслеживайте выполнения рабочих процессов, чтобы убедиться, что итерации завершаются как ожидается

## Связанные материалы

* [Действия рабочего процесса](/l/ru/user-guide/workflows/capabilities/workflow-actions)
* [Как использовать ветвления](/l/ru/user-guide/workflows/capabilities/use-branches-in-workflows)
* [Частые вопросы о рабочих процессах](/l/ru/user-guide/workflows/how-tos/need-more-help/workflows-faq)