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

# 回填历史 bundle

> 计算历史 EVM 数据并跟踪对应 BlockDB 写入作业。

回填对历史源数据行执行函数，并为对应 bundle 写入派生数据。沿用[按区块计算](/zh/guides/block-computation)的转换逻辑，使用历史输入与输出上下文。

## 链与历史上下文

bundle 标识源数据分区，不会为每次函数读取选择 EVM 状态。如果函数查询历史状态，应从每条源记录取得正确区块标识，并传给读取操作。

## 前置条件

* 可以访问源数据文件与 BlockDB BatchWrite 的 bundle 部署。
* 兼容的目标 block 表，以及覆盖写入所选 bundle 的权限。
* 转换函数所需的源 schema。
* 函数执行 EVM 读取时，还需要历史节点数据。

## 提交一个 bundle

将[按区块计算](/zh/guides/block-computation)中的 `source_code` 传给此辅助函数。使用你的源表、目标表及选定 bundle 编号。

```python theme={null}
from blockx import (
    SOURCE_ROW, BlockBundleCallConfig, BlockTableWriteHandler,
    Function, TaskBuilder,
)


def submit_bundle(number, source_table, target_table, source_code):
    task = TaskBuilder.build(
        BlockBundleCallConfig(number=number, triggerSources=[{
            "table": source_table,
            "func": Function(source_code=source_code),
            "params": ["eth", SOURCE_ROW],
        }]),
        BlockTableWriteHandler(targetTable=target_table, block_bundle=number),
    )
    result = task.submit()
    if not result.task_result.success:
        raise RuntimeError(result.task_result.failure_code)
    return task.task_id, result.handler_result
```

输入与输出使用相同 `number`。处理范围时，只提交目标 bundle 编号，并保留每个任务及 Writer 结果。决定重做哪些工作之前，先记录失败或状态未知的提交。

## 回填 bundle 范围

`backfill_block_bundles` 提交包含首尾编号的 bundle 范围。`BlockBundleCallConfigTemplate` 提供共用的触发配置。辅助函数对输入模板与 block 表 Writer 模板调用 `for_bundle(number)`，让两者使用相同 bundle 编号。

```python theme={null}
from blockx import (
    SOURCE_ROW, BlockBundleCallConfigTemplate, BlockTableWriteHandler,
    Function, backfill_block_bundles,
)


def backfill_range(start_bundle_id, end_bundle_id,
                   source_table, target_table, source_code):
    config = BlockBundleCallConfigTemplate(triggerSources=[{
        "table": source_table,
        "func": Function(source_code=source_code),
        "params": ["eth", SOURCE_ROW],
    }])
    handler = BlockTableWriteHandler(targetTable=target_table)
    summary = backfill_block_bundles(
        start_bundle_id, end_bundle_id, config, handler,
    )
    if not summary.ok:
        raise RuntimeError(summary.failed_bundles, summary.failure_codes)
    return summary
```

沿用单 bundle 示例的表与函数前置条件。Writer 模板尚未指定 `block_bundle`；单独提交任务前，需要用 `for_bundle(number)` 实例化。范围辅助函数会完成这一步。

辅助函数返回 `BackfillSummary`，包含 `succeeded`、`failed_bundles` 和 `failure_codes`。默认在首个 bundle 失败时中止。这些计数描述任务结果，不代表存储侧作业已经完成。

## 定义可复用流水线

`Pipeline` 将触发表、函数和目标表组合起来。`Trigger.params` 用 `SOURCE_ROW` 指定输入记录在函数参数中的位置。复用上面的 EVM trace 转换逻辑：

```python theme={null}
from blockx import Function, Pipeline, SOURCE_ROW, Trigger


def make_pipeline(source_table, target_table, source_code):
    return Pipeline(
        triggers=[Trigger(
            table=source_table,
            func=Function(source_code=source_code),
            params=["eth", SOURCE_ROW],
        )],
        target_table=target_table,
    )
```

用 `make_pipeline(source_table, target_table, source_code)` 创建 `pipe`，再选择操作：

| 操作 | 范围与行为 |
| - | - |
| `pipe.backfill(block_start=18000001, block_end=18100000)` | 包含首尾的区块高度；完整 bundle 使用 bundle 任务，边界不足一个 bundle 的部分使用区块任务 |
| `pipe.backfill(block_start=18000001)` | 结束于触发表与依赖表的最小就绪高度 |
| `pipe.update()` | 长期运行的订阅；block 表目标先追平一次，再处理对齐后的区块事件 |

选择源表中已可用的高度。`backfill_block_bundles` 接收 bundle 编号，`Pipeline.backfill` 接收区块高度，两者单位不同。精确处理边界与运行 `update()` 还需要 block 部署。

通过 `Pipeline(depends=[...])` 添加只用于查询的上游表。它们约束就绪条件，但不会触发调用或提供参数。流水线按目标表类型选择 Writer；`Pipeline(condition=...)` 只向普通表输出传递条件。

订阅阶段的 `update()` 不会回填高度缺口。用 `backfill()` 显式补齐历史缺口。普通表与 time 表目标直接开始订阅，不执行初始区块追平。

## 确认完成

实际的 block 表 bundle 写入会在 Writer 结果中返回 `job_id`。任务成功确认 BatchWrite 已提交，不表示存储侧作业已完成。记录作业标识，确认其 BlockDB 状态与目标读取条件后，再将该范围标为就绪。

计算没有输出，本身不能证明源分区完整。尤其在所有行都被过滤时，应检查源数据可用性及预期的覆盖写入语义。

## 处理部分失败

| 结果 | 操作 |
| - | - |
| 源准备失败 | 修正源数据或配置后再执行 |
| 函数失败 | 检查输入行、历史读取上下文与函数错误 |
| 写入提交结果未知 | 再次覆盖写入前，检查已有作业 |
| 部分 bundle 成功 | 按 bundle 和写入作业分别跟踪完成情况 |

## 继续阅读

* [执行语义与结果](/zh/concepts/execution-semantics)
* [配置参考](/zh/reference/task-configuration)
* [Bundle 集群](/zh/components/bundle)


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