回填特征视图

回填会重新计算你选择的时间范围内的特征视图的物化值。 在校正或添加历史源数据后使用,使离线和在线的物化结果反映更新后的数据。

Materialization 计算每次运行的近期特征值,不会重新处理已写入的值。 对过去时间范围的源数据所做的更改,在你回填该时间范围之前,不会反映到具体化值中。 在以下情景中使用回填:

  • 上游数据质量问题影响了过去的时间区间,你修正了源数据行。
  • 过去时间范围的源数据是在物化处理完毕之后才到达的。

回填是一次性工作,与预定的物化同步进行。 这不会改变具体化计划。 请参阅 具体化功能视图。

Requirements

  • databricks-feature-engineering 0.18.2及以上。 其他要求请参见 要求。
  • 每个特征视图都是一个批量聚合特征,使用 DeltaTableSource 和 SlidingWindow 或 TumblingWindow。 不支持生命周期窗口。
  • 每个特征视图都已具体化,并且至少完成了一次具体化运行。 回填会重新计算物化已经写入的数值,因此无法首次物化特征视图。
  • 你以实体化 Feature View 的同一个用户或服务主体,在实体化这些 Feature View 的工作区中开始回填。

Permissions

回填以你的身份运行,并且读写与你的具体化相同的表,因此它使用与你的具体化相同的权限。 有关完整的 Unity 目录权限描述,请参见 Unity 目录权限参考。

  • 你必须对每个要回填的特征视图具备 MANAGE 权限。
  • 要检查回填,你需要对回填的每个特征视图都具备 READ FEATURE 权限。 要取消回填,你需要对回填的每个特征视图都具备 MANAGE 权限。

开始回填

要开始回填,请调用 backfill_features 并传入要回填的 Feature Views 和一个或多个时间范围:

FeatureEngineeringClient.backfill_features(
    *,                                          # Arguments are keyword-only
    features: List[Union[str, Feature]],        # Feature Views to backfill, as Feature objects or full names
    backfill_ranges: List[BackfillRange],       # Time ranges of source data to reprocess
    request_id: Optional[str] = None,           # Idempotency token, a UUID
    tags: Optional[Dict[str, str]] = None,      # Custom tags for cost attribution
    budget_policy_id: Optional[str] = None,     # Serverless usage policy for cost attribution
    wait: bool = False,                         # Wait for the backfill to finish
) -> BackfillStatus:

同一调用中的所有特征视图都必须在相同的时间点产生数值。 它们的值之间必须具有相同的间隔(SlidingWindow的slide_duration或window_duration的TumblingWindow),且offset也必须相同。 否则,该调用会失败并返回一个错误,该错误会按时间间隔对特征视图进行分组,以便你可以为每组启动单独的回填。

每个 BackfillRange 都有一个 start_time(包含在内),以及一个 end_time(不包含)。 两者都是Pythondatetime值。 没有时区的 A datetime 会被视为 UTC。 每个 start_time 都必须早于其对应的 end_time,且同一次调用中的范围不能重叠。 关于回填如何解释每个区间,请参见 回填如何应用时间范围。

以下示例回填了两个特征视图的一周历史:

from datetime import datetime, timezone

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import BackfillRange

fe = FeatureEngineeringClient()

backfill = fe.backfill_features(
    features=[
        "main.feature_store.amount_sum_sliding_7d_1d",
        "main.feature_store.transaction_count_sliding_7d_1d",
    ],
    backfill_ranges=[
        BackfillRange(
            start_time=datetime(2026, 3, 1, tzinfo=timezone.utc),
            end_time=datetime(2026, 3, 8, tzinfo=timezone.utc),
        )
    ],
)

print(backfill.operation_name)  # operations/<operation-id>

在回填开始前,backfill_features 检查以下内容。 如果检查失败,调用将失败,并返回一条指出受影响的功能视图的错误信息。

  • 每个特征视图都满足要求,包括已完成的具体化运行。
  • 你已具体化每个特征视图。
  • 你拥有所需的权限。

该方法返回一个描述回填的 BackfillStatus。 它 operation_name 标识回填,其格式为 operations/<operation-id>。 参见 “监控或取消回填”。

为了让调用能够安全地重试,将 UUID 作为 request_id 传递。 使用相同 request_id 的重试会返回原始回填,而不会启动新的回填。

要归因回填的成本,请传递 tags、budget_policy_id,或两者都传递。 它们只适用于那个回填。 参见使用标记和无服务器使用策略来归因成本。

回填如何应用时间范围

每个区间选择要重新处理的源数据:时间戳在 start_time 或之后且在 end_time 之前的源行。 回填按以下方式应用于每个范围:

  • 范围会对齐到整体特征值。 回填会重新计算整体特征值,因此会将每个范围向外扩展到该特征产生值所对应的最近时间点。 一个SlidingWindow特征在每个 TumblingWindow都产生一个值,而一个slide_duration特征在每个 window_duration都产生一个值,如果设置了窗口,该值会按窗口的offset发生偏移。 例如,对于一个包含 1 小时 slide_duration 的特征,从凌晨 1:30 到 2:30 的范围会变成凌晨 1:00 到 3:00。 你不需要自己对齐范围。 在对齐后重叠的范围会合并为一个。
  • 超出该范围后的数值可能会变化。 回填会重写包含重新处理数据的时间窗口的每个特征值。 窗口可以在 end_time 之后结束,因此,在 end_time 之后最多一个 window_duration 内的值可能会发生变化。 例如,对于一个 7 天 window_duration 的特征,在 end_time 后 7 天内,数值可能会发生变化。
  • 回填在最近的具体化值处停止。 回填只重新计算具体化已写入的历史数据。 如果某个范围超出了最新的具体化值,回填会停在此处,并将更晚的时间范围留给计划的具体化来处理。
  • 未设置的边界会扩展到可用数据范围。 如果省略 start_time,范围将从源数据中最早的时间戳开始。 如果省略 end_time,范围会延伸到最近已物化的值。

BackfillStatus 的 backfill_ranges 是对齐后的范围。 回填不会将其缩小到最近物化的值,所以报告的范围可能会超出回填重新计算的数值。 你无需回填后面的数值,因为计划的具体化会根据当前源数据计算这些数值。

离线与在线表格

回填会更新功能视图的离线表,如果该功能视图也实体化到在线存储,则也会更新其在线表。 对于两者兼具的功能视图,回填会重新计算离线表,然后从中重新发布在线表。 你不能只回填其中一个。

在线表格中保存每个实体的最新值。 回填仅在改变实体最新值时才会改变在线值。

监控或取消回填

backfill_features 无需等待回填完成即可返回。 要等待,请传入 wait=True,或使用返回的状态调用 wait_for_backfill:

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill 回填成功后返回最终 BackfillStatus。 如果回填失败或被取消,会引发一个 OperationFailed 错误,说明原因。 为了限制等待时间,将 timeout 作为 timedelta 传递。 如果回填尚未完成,则 wait_for_backfill 会引发一个 TimeoutError。 停止等待并不能取消回填。

要检查回填而不等待,或在其他笔记本或作业中检查,请使用操作名称调用 get_backfill:

backfill = fe.get_backfill(operation_name="operations/<operation-id>")

print(backfill.state)  # For example, BackfillState.RUNNING

BackfillStatus 有以下字段:

  • operation_name:标识回填的名称。
  • state:回填的状态,作为一个 BackfillState 值。
  • feature_full_names:回填中特征视图的全名。
  • backfill_ranges:对齐后的时间范围,以 BackfillRange 值表示,边界为 UTC。
  • error:回填失败的原因。 该字段仅在 state 为 FAILED 时设置。

回填状态是以下数值之一:

State Description
PENDING 回填已被接受,但尚未开始运行。
RUNNING 回填正在进行。
SUCCEEDED 回填已完成,并在其范围内重新计算了特征值。
FAILED 回填任务因错误已停止。 参见“从回填失败中恢复”。
CANCELLED 回填在完成前就被取消了。

如果没有操作名称,请在 list_materialized_features 返回的 latest_backfill_operation 字段中查找具体化特征的最近回填,并将其传递给 get_backfill。

要取消回填,请使用其状态调用 cancel_backfill:

fe.cancel_backfill(backfill=backfill)

取消回填会请求其停止。 即将完成的回填仍然可能成功,因此用 get_backfill 检查其最终状态。 取消已经完成的回填不会有任何效果。 已取消的回填可能会导致某些特征值被重新计算,详见 “从失败回填恢复”中描述。

Concurrency

回填会与你计划的具体化同时运行。 不同特征视图的回填也可以同时运行。

一次只能为一个特征视图运行一个回填。 如果你开始为已经有回填正在进行中的功能视图进行回填,请求会因出现 ALREADY_EXISTS 错误而失败。 等上一个回填完成后再开始下一个。

从回填失败中恢复

失败或取消的回填可能会在完成前停止。 回填停止前重写的每个值都会被完全重新计算。 回填未覆盖到的值会保留其先前的值,因此可能不会更新某些特征视图或时间范围。

要恢复,可以重新开始同样的回填。 如果你传入了一个 request_id,请传入一个新值,因为使用原有 request_id 的重试会返回失败的回填,而不是重新开始一个新回填。 回填是安全的,可以重复执行。 如果源数据没有变化,重新计算已经成功的范围会得到相同的数值。

Limitations

  • 只有使用 a DeltaTableSource 和 a SlidingWindow 或 TumblingWindow 的批处理聚合特征才能被回填。 流媒体特征、ColumnSelection 特征、带有 RollingWindow 或 SawtoothWindow 的特征、带有生命周期窗口的特征,以及带有其他源(例如 RequestSource)的特征均不支持回填。
  • 在不同间隔或偏移产生数值的特征视图不能共享一个回填。 为每个组分别启动回填。
  • 回填会更新功能视图的离线表;如果该功能视图也实体化到在线存储中,则也会更新其在线表。 你不能只回填其中一个。
  • 回填不会填充最近具体化值之后的时间范围。 你计划的具体化将填充这些范围。