回填历史 bundle

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

链与历史上下文

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

前置条件

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

提交一个 bundle

将按区块计算中的 source_code 传给此辅助函数。使用你的源表、目标表及选定 bundle 编号。

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 编号。

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 转换逻辑：

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 和写入作业分别跟踪完成情况

开始使用

核心概念

使用指南

参考

架构

组件

开发指南

链与历史上下文

前置条件

提交一个 bundle

回填 bundle 范围

定义可复用流水线

确认完成

处理部分失败

继续阅读

​链与历史上下文

​前置条件

​提交一个 bundle

​回填 bundle 范围

​定义可复用流水线

​确认完成

​处理部分失败

​继续阅读

链与历史上下文

前置条件

提交一个 bundle

回填 bundle 范围

定义可复用流水线

确认完成

处理部分失败

继续阅读