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

# 循环执行

> 通过遍历数组在一个操作中批量处理多个项目

<Tip>
  我们强烈建议使用运行脚本来搭建自动化，因为它可以覆盖所有操作行为，包括原本需要手动搭建的操作。你只需在 AI 对话中描述需求即可。

  请注意：如果你手动添加操作，AI 后续将无法识别或修改它们。
</Tip>

循环执行会对数组中的**每一项**依次执行一次操作。项目按顺序处理，所有结果以数组形式返回。这是实现批量操作的核心功能，可以将单条记录的操作扩展为批量处理。

## 支持的操作

| 操作      | 支持循环 | 说明           |
| ------- | ---- | ------------ |
| 创建记录    | 是    | 批量创建多条记录     |
| 更新记录    | 是    | 批量更新多条记录     |
| 发送邮件    | 是    | 为每条记录发送个性化邮件 |
| HTTP 请求 | 是    | 批量调用外部 API   |
| AI 生成   | 是    | 批量处理 AI 任务   |

## 数组来源

循环执行需要一个数组作为数据源。常见的数组来源：

| 来源              | 说明                         |
| --------------- | -------------------------- |
| 查询记录的输出         | "查询记录"操作返回的记录数组，最常用的数组来源   |
| Webhook 请求体中的数组 | 外部系统通过 Webhook 传入的 JSON 数组 |
| AI 生成的 JSON 数组  | AI 生成操作返回的结构化 JSON 中的数组字段  |
| HTTP 请求响应中的数组   | 外部 API 返回的数据数组             |

## 如何设置

1. 打开一个支持循环的操作（如"创建记录"、"发送邮件"等）。
2. 点击操作配置区域中的**循环执行**开关。
3. 选择一个数组变量作为数据源。例如：点击 **+** 按钮选择"查询记录"步骤输出的记录数组。
4. 在字段映射中，引用**当前项**的属性，而非整个数组。例如：引用"当前记录的客户名称"而非"全部记录"。
5. 点击**测试**验证循环是否正确执行。

## 引用当前元素属性

开启循环执行后，字段映射中可以引用当前迭代项的具体属性。例如：

* 如果数据源是"查询记录"的输出，每一项是一条记录。你可以引用当前记录的 ID、各字段值。
* 如果数据源是 Webhook 中的 JSON 数组，每一项是数组中的一个对象。你可以引用该对象的属性。

<Tip>在字段映射的变量选择器中，选择循环数据源后，系统会自动列出当前项的可用属性。</Tip>

## 具体示例

### 示例一：批量发送个性化邮件

1. **查询记录**：筛选出所有本月生日的客户。
2. **发送邮件**（开启循环）：
   * 数据源：查询结果的记录数组
   * 收件人：当前记录的"邮箱"字段
   * 主题：`生日快乐，{{当前记录.客户名称}}！`
   * 正文：个性化祝福内容

### 示例二：批量创建任务

1. 触发器：项目表中新增一条项目记录。
2. **查询记录**：从"任务模板表"中查询所有模板任务。
3. **创建记录**（开启循环）：
   * 数据源：模板任务数组
   * 目标表格：任务表
   * 字段映射：将模板的任务名称、负责人、预计工时等映射到新任务

### 示例三：批量同步数据到外部系统

1. **查询记录**：筛选出所有待同步的记录。
2. **HTTP 请求**（开启循环）：
   * 数据源：查询结果
   * URL：`https://api.example.com/products`
   * Method：POST
   * Body：当前记录的产品信息

## HTTP 数组请求体

对于 HTTP 请求操作，除了常规的逐条循环，还可以使用**数组请求体**模式：将整个数组作为一个 JSON 数组，在**单次请求**中发送。

适用场景：

* 目标 API 支持批量操作接口
* 希望减少 HTTP 请求次数以提高效率
* 需要将多条数据打包发送

<Tip>如果目标 API 提供批量接口（如批量创建、批量更新），使用数组请求体比逐条请求更高效。</Tip>

## 性能说明

* 循环中的每一项是按顺序执行的，不是并行处理。数组越大，总执行时间越长。
* 大量数据的循环可能导致工作流运行时间较长。建议通过筛选条件控制数据量，避免不必要的遍历。
* 如果循环中某一项执行失败，不会影响其他项的执行。失败的项会在运行日志中标记。
* 对于 HTTP 请求，如果目标 API 有速率限制，大量循环请求可能触发限制。建议评估数据量和 API 限制后合理使用。

## 适用场景

* **批量通知发送**：定时查询所有逾期任务，为每位负责人发送个性化的提醒邮件。
* **数据批量迁移**：从一个表查询记录，批量创建到另一个表或另一个 Base 中。
* **批量 API 同步**：将多条产品数据逐条推送到电商平台的 API。
* **批量 AI 处理**：对一批记录逐条调用 AI 生成操作，进行分类、摘要或数据提取。

## 注意事项

* 开启循环后，字段映射中引用的变量含义从"整个数组"变为"当前迭代项"。确保你引用的是正确的层级。
* 循环执行的结果以数组形式返回，后续步骤可以引用这个结果数组。
* 空数组（0 项）不会执行任何操作，工作流会继续执行后续步骤。

## 相关文档

* [查询记录](/zh/basic/automation/actions/records/get-records)
* [创建记录](/zh/basic/automation/actions/records/create-record)
* [HTTP 请求](/zh/basic/automation/actions/logic/http-request)
* [发送邮件](/zh/basic/automation/actions/communication/send-email-overview)