回填会重新计算你选择的时间范围内的特征视图的物化值。 在校正或添加历史源数据后使用,使离线和在线的物化结果反映更新后的数据。
Materialization 计算每次运行的近期特征值,不会重新处理已写入的值。 对过去时间范围的源数据所做的更改,在你回填该时间范围之前,不会反映到具体化值中。 在以下情景中使用回填:
- 上游数据质量问题影响了过去的时间区间,你修正了源数据行。
- 过去时间范围的源数据是在物化处理完毕之后才到达的。
回填是一次性工作,与预定的物化同步进行。 这不会改变具体化计划。 请参阅 具体化功能视图。
Requirements
-
databricks-feature-engineering0.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和 aSlidingWindow或TumblingWindow的批处理聚合特征才能被回填。 流媒体特征、ColumnSelection特征、带有RollingWindow或SawtoothWindow的特征、带有生命周期窗口的特征,以及带有其他源(例如RequestSource)的特征均不支持回填。 - 在不同间隔或偏移产生数值的特征视图不能共享一个回填。 为每个组分别启动回填。
- 回填会更新功能视图的离线表;如果该功能视图也实体化到在线存储中,则也会更新其在线表。 你不能只回填其中一个。
- 回填不会填充最近具体化值之后的时间范围。 你计划的具体化将填充这些范围。