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

# Data Transform

> 通过构建行、串联数组、扁平化数组或将对象转换为表格网格来重塑工作流数据，无需调用外部服务

# Data Transform

当你需要在另一个步骤读取之前重塑现有工作流输出时，请使用 **Data Transform**。

Data Transform 不调用外部服务。它在 **Google Sheets**、**Airtable**、**Custom API** 以及后续 **Iteration** 步骤之前很有用。

## 配置

| 选项 | 是否必填 | 说明 |
| - | - | - |
| Name | 否 | 步骤在工作流画布中的标签。 |
| Mode | 是 | 要运行的转换。选择 **Build Rows**、**Concat Arrays**、**Flatten Array**、**Objects to Grid**、**Classify Date** 或 **Summarize**。 |
| Fields | 仅 Build Rows | 输出对象键及其源值。 |
| Sources | 仅 Concat Arrays | 要追加到一个数组的数组值。 |
| Source Value | Flatten Array 和 Objects to Grid | 要转换的一个数组值。 |
| Headers | 仅 Objects to Grid | 可选列名。留空则使用记录中的全部键。 |
| Mismatch Policy | 仅 Build Rows | 如何处理长度不同的数组。 |
| Date Field, Status Field, Age Field, Stale After, Today | 仅 Classify Date | 包含日期的字段、新增状态字段的名称、可选的过期天数窗口，以及用于比较的日期。 |
| Group By, Total Field, Count items where | 仅 Summarize | 用于按值计数的可选字段、用于求和的可选数字字段，以及可选的计数条件（字段、运算符和值，与 Filter 相同）。 |

从 **Search steps...** 的 **Utilities** 分组添加此步骤。

## 模式

### Build Rows

使用 **Build Rows** 按索引将数组打包成一组对象。

每个字段都有 **Key** 和 **Source Value**。键变为对象属性。源可以是完整的变量引用，例如 `{{tool_names}}` 或 `{{step_3.output}}`，或者静态值。如果未配置字段或字段键为空，该步骤会失败。

数组源值按索引读取。静态标量值会为每一行重复。

示例:

```json theme={null}
{
  "tool_names": ["Exa", "Airtable"],
  "search_contexts": ["Search context for Exa", "Search context for Airtable"]
}
```

Build Rows 字段:

```json theme={null}
[
  { "key": "tool_name", "value": "{{tool_names}}" },
  { "key": "search_context", "value": "{{search_contexts}}" },
  { "key": "workspace", "value": "Fetch Hive" }
]
```

输出:

```json theme={null}
[
  {
    "tool_name": "Exa",
    "search_context": "Search context for Exa",
    "workspace": "Fetch Hive"
  },
  {
    "tool_name": "Airtable",
    "search_context": "Search context for Airtable",
    "workspace": "Fetch Hive"
  }
]
```

当数组长度不同时，使用 **Mismatch Policy**:

| 策略 | 行为 |
| - | - |
| Pad null | 使用最长数组，并用 `null` 填充缺失值。这是默认值。 |
| Strict fail | 如果数组长度不匹配，则步骤失败。 |
| Truncate | 使用最短的数组长度。 |

### Concat Arrays

使用 **Concat Arrays** 将多个数组追加为一个更长的数组。

每个源必须解析为数组。如果源解析为字符串、对象、数字或布尔值，步骤将失败。

示例 sources:

```json theme={null}
[
  { "value": "{{step_2.output}}" },
  { "value": "{{step_3.output}}" }
]
```

如果这些值为 `["a", "b"]` 和 `["c"]`，则输出为:

```json theme={null}
["a", "b", "c"]
```

### Flatten Array

使用 **Flatten Array** 将一个数组扁平化一层。

嵌套数组元素会展开。非数组元素保持原位。

示例 source:

```json theme={null}
[[1, 2], 3, [4]]
```

输出:

```json theme={null}
[1, 2, 3, 4]
```

### Objects to Grid

当上一步返回对象数组，并且你想把该数据集写入 **Google Sheets** 时，使用 **Objects to Grid**。

将 **Source Value** 设为记录数组，例如 `{{step_2.output}}`。如果上一步把行包在某个字段中（例如 **AI Keyword Data Search**），请改用该字段，例如 `{{step_2.output.items}}`。将 **Headers** 留空即可按首次出现的顺序使用每个对象键。也可以传入解析为列名数组的占位符，或逗号分隔列表，例如 `keyword, volume, difficulty`。

示例 source:

```json theme={null}
[
  { "keyword": "ai agents", "volume": 1200 },
  { "keyword": "workflows", "volume": 800, "difficulty": 12 }
]
```

输出:

```json theme={null}
{
  "headers": ["keyword", "volume", "difficulty"],
  "rows": [
    ["ai agents", 1200, null],
    ["workflows", 800, 12]
  ]
}
```

将这些值传入 Google Sheets **Upsert Rows** 步骤:

```text theme={null}
{{STEP_IDENTIFIER.output.headers}}
{{STEP_IDENTIFIER.output.rows}}
```

缺失的键会变成空单元格。记录中的嵌套对象或数组会原样传递；Google Sheets 单元格最适合文本和数字这类简单值。

### Classify Date

当你需要知道某个日期是否已过时使用 **Classify Date**，例如招标截止日期或优惠到期日。模型在比较日期时不可靠，因此在 AI 步骤提取出原始日期文本之后，由此模式用代码完成比较。

将 **Source Value** 设为记录数组，将 **Date Field** 设为包含日期的字段（例如 `deadline`），并保持 **Today** 为 `{{_current_date}}`。每条记录都会带上一个状态字段（默认 `date_status`）：

| 状态 | 含义 |
| - | - |
| open | 日期是今天或之后。 |
| closed | 日期已过。 |
| stale | 日期已过且超过 **Stale After** 天（仅在设置后）。 |
| unclear | 日期缺失、无法读取或有歧义。 |

若要按天数排序或筛选，请设置 **Age Field**：每条记录还会以该名称带上距该日期的天数（未来日期为负数，日期不明确则为 `null`）。日期之后的时间或时区会被忽略。日和月都不大于 12 且没有月份名称的数字日期，例如 `10/12/2026`，有歧义，会返回 **unclear** 而不是猜测。`25/12/2026`、`2026-12-25` 和 `25 December 2026` 都会被正常读取。

### Summarize

使用 **Summarize** 统计列表数量，可选地对数字字段求和并按另一个字段分组，使后续步骤报告的数字与列表一致。输出为 `{ "count": 5, "total": 17.5, "groups": [{ "value": "open", "count": 2, "total": 12 }] }`；只有设置了 **Total Field** 才会出现 `total`，只有设置了 **Group By** 才会出现 `groups`。求和时会跳过非数字值。

当后续步骤需要满足某个条件的项数或百分比时（例如清单中找到了多少项、占全部的比例），请使用 **Count items where**。设置字段、运算符和值（例如 `status` **is one of** `structured, buried`）。此时输出还会包含 `matched`（满足条件的项数）和 `matched_percent`（`matched` 占 `count` 的百分比，四舍五入为整数；列表为空时为 `0`）。像引用其他输出一样引用它们，例如 `{{step_6.output.matched_percent}}`，这样数字由该步骤得出，而不是由 AI 步骤自行计数。

## 输出

Data Transform 将其结果存储在:

```text theme={null}
{{STEP_IDENTIFIER.output}}
```

对于 **Build Rows**，输出是一个对象数组。这种形状非常适合期望记录或行的集成步骤。

对于 **Concat Arrays** 和 **Flatten Array**，输出是后续步骤可以遍历的数组。

对于 **Objects to Grid**，输出是包含 `headers` 和 `rows` 的对象。将其用于 Google Sheets **Upsert Rows**。

## 备注

* 源值应该是完整的占位符，例如 `{{step_2.output}}`，或者静态标量值。
* Data Transform V1 不支持混合模板字符串，例如 `Research for {{tool_names}}`。
* Data Transform 将数组和对象保留为结构化 JSON，供下游步骤使用。
* Data Transform 是免费的实用步骤。

另见:[Google Sheets](https://docs.fetchhive.com/zh/workflows/steps/integrations/google-sheets.md)、[Airtable](https://docs.fetchhive.com/zh/workflows/steps/integrations/airtable.md)、[Custom API](https://docs.fetchhive.com/zh/workflows/steps/utility/custom-api.md) 和 [测试与迭代](https://docs.fetchhive.com/zh/workflows/testing-and-iteration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.