メインコンテンツまでスキップ
に最終更新

フィーチャ ビューのバックフィル

バックフィルは、選択した時間範囲にわたって特徴量ビューのマテリアライズド値を再計算します。履歴ソースデータを修正または追加した後に使用して、オフラインおよびオンラインのマテリアライズドビューが更新されたデータを反映するようにします。

マテリアライゼーションは、ランごとに最近の特徴量をコンピュートし、すでに書き込まれた値には戻りません。過去の時間範囲のソースデータへの変更は、その時間範囲をバックフィルするまでマテリアライズされた値に到達しません。次のようなシナリオでバックフィルを使用します。

  • アップストリームのデータ品質の問題が過去の時間範囲に影響し、ソース行を修正しました。
  • 過去の期間のソースデータが、マテリアライズ処理で既に処理された後に到着しました。

バックフィルは、スケジュールされたマテリアライゼーションと並行してランする1回限りのジョブです。マテリアライゼーションのスケジュールは変更しません。特徴量ビューのマテリアライズを参照してください。

要件​

  • databricks-feature-engineering 0.18.2以上。その他の要件については、要件を参照してください。
  • 各特徴量ビューは、 DeltaTableSource と SlidingWindow または TumblingWindow を使用するバッチ集約特徴量です。存続期間ウィンドウはサポートされていません。
  • 各フィーチャ ビューはマテリアライズされ、少なくとも 1 回のマテリアライズ ランが完了しています。バックフィルはマテリアライズによって既に書き込まれた値を再計算するため、フィーチャ ビューを初めてマテリアライズすることはできません。
  • バックフィルは、特徴量ビューをマテリアライズしたときと同じユーザーまたはService Principalとして、それらがマテリアライズされているワークスペースから起動します。

権限​

バックフィルはあなたとしてランされ、マテリアライゼーションと同じテーブルの読み書きを行うため、マテリアライゼーションと同じ権限を使用します。完全な Unity Catalog の権限の説明については、Unity Catalog の権限のリファレンスを参照してください。

  • バックフィルする各特徴量ビューに対してMANAGEが必要です。
  • バックフィルをチェックするには、バックフィル内のすべての特徴量ビューでREAD FEATUREが必要です。バックフィルをキャンセルするには、バックフィル内のすべての特徴量ビューでMANAGEが必要です。

バックフィルを起動​

バックフィルを起動するには、バックフィルする特徴量ビューと1つ以上の時間範囲を指定して backfill_features を呼び出します。

Python
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:

1回の呼び出しに含まれるすべての特徴量ビューは、同時に値を生成する必要があります。それらは、値間の同じ間隔（SlidingWindowのslide_durationまたはTumblingWindowのwindow_duration）と同じoffsetを共有する必要があります。そうでない場合、呼び出しは失敗し、特徴量ビューを間隔でグループ化するエラーが返されます。これにより、グループごとに個別のバックフィルを起動できます。

各BackfillRangeには、インクルーシブなstart_timeと、エクスクルーシブなend_timeがあります。両方ともPython datetime値です。タイムゾーンのないdatetimeはUTCとして読み取られます。各start_timeは、そのend_timeより前の日付である必要があり、1回の呼び出しの範囲が重複することはできません。バックフィルが各範囲を解釈する方法については、「バックフィルが時間範囲を適用する方法」を参照してください。

次の例では、2つの特徴量ビューの1週間分の履歴をバックフィルします。

Python
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は以下を確認します。チェックに失敗した場合、呼び出しは影響を受けたFeature Viewの名前をエラーとして返して失敗します。

  • 各フィーチャ ビューは要件を満たしており、完了したマテリアライズ ランが含まれます。
  • 各機能ビューをマテリアライズしました。
  • 必要な権限があります。

このメソッドは、バックフィルを記述する BackfillStatusを返します。そのoperation_nameはバックフィルを特定し、その形式はoperations/<operation-id>です。バックフィルの監視またはキャンセルを参照してください。

呼び出しを安全に再試行できるように、UUIDをrequest_idとして渡します。同じrequest_idで再試行すると、新しいバックフィルを開始する代わりに元のバックフィルが返されます。

バックフィルのコストを属性化するには、tags、budget_policy_id、または両方を渡します。それらはそのバックフィルにのみ適用されます。タグとServerless使用ポリシーによるコストの属性化を参照してください。

バックフィルが時間範囲に適用される仕組み​

各範囲で再処理するソースデータを選択します。つまり、Timestampがstart_time以降かつend_time未満のソース行です。バックフィルは各範囲に次のように適用されます：

  • 範囲は特徴量全体の値に合わせて調整されます。バックフィルは特徴量全体の値の再計算を行うため、各範囲は特徴量が値を出力する最も近い時間まで外側に拡張されます。SlidingWindow の特徴量は slide_duration ごとに値を生成し、 TumblingWindow の特徴量は window_duration ごとに値を生成します。設定した場合は、ウィンドウの offset だけシフトします。例えば、1時間の slide_duration を持つ特徴量の場合、午前1:30から午前2:30までの範囲は午前1:00から午前3:00までになります。自分で範囲を調整する必要はありません。調整後に重複する範囲は 1 つに統合されます。
  • 範囲後の値は変更される可能性があります。バックフィルは、タイムウィンドウに再処理されたデータが含まれるすべての特徴量を書き換えます。ウィンドウは end_time の後に終了する可能性があるため、end_time から 1 つの window_duration までの値が変更される可能性があります。たとえば、7 日間の window_duration を持つ特徴量の場合、end_time から 7 日後までの値が変更される可能性があります。
  • バックフィルは、最新のマテリアライズド値で停止します。バックフィルは、マテリアライゼーションがすでに書き込んだ履歴のみを再計算します。範囲が最新のマテリアライズド値を超えている場合、バックフィルはそこで停止し、それ以降の時間範囲はスケジュールされたマテリアライゼーションに任せます。
  • 設定されていない境界は、使用可能なデータまで拡張されます。start_time を省略した場合、範囲はソースデータで最も古いTimestampから始まります。end_time を省略した場合、範囲は最新のマテリアライズされた値まで拡張されます。

BackfillStatusのbackfill_rangesは、調整後の範囲です。バックフィルはそれらを最新のマテリアライズド値に絞り込まないため、レポートされる範囲はバックフィルが再計算した値を超えて拡張される可能性があります。スケジュールされたマテリアライズは現在のソースデータからコンピュートされるため、後の値をバックフィルする必要はありません。

オフラインとオンラインのテーブル​

バックフィルは特徴量ビューのオフラインテーブルを更新します。また、特徴量ビューがオンラインストアにもマテリアライズされている場合は、そのオンラインテーブルも更新します。オフラインテーブルとオンラインテーブルの両方がある特徴量ビューでは、バックフィルによってオフラインテーブルが再計算され、そのテーブルからオンラインテーブルが再公開されます。そのうち一方だけをバックフィルすることはできません。

オンラインテーブルは、各エンティティの最新の値を保持します。バックフィルは、エンティティの最新値を変更する場合にのみオンライン値を変更します。

バックフィルの監視またはキャンセル​

backfill_features バックフィルが完了するのを待たずに返します。待機するには、wait=Trueを渡すか、返されたステータスでwait_for_backfillを呼び出します。

Python
backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill バックフィルが成功したときに、最終的なBackfillStatusを返します。バックフィルが失敗したかキャンセルされた場合、その理由を示すOperationFailedエラーが発生します。待ち時間を制限するには、timeoutをtimedeltaとして渡します。バックフィルがその時までに完了していない場合、wait_for_backfillはTimeoutErrorを発生させます。待機を停止してもバックフィルはキャンセルされません。

バックフィルを待たずに、または別のノートブックやジョブから確認するには、操作名を指定してget_backfillを呼び出します。

Python
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の場合にのみ設定されます。

バックフィルの状態は次の値のいずれかです。

状態

説明

PENDING

バックフィルは受け付けられましたが、実行は起動されていません。

RUNNING

バックフィルが実行されています。

SUCCEEDED

バックフィルが終了し、範囲内の特徴量値が再計算されました。

FAILED

バックフィルはエラーのため停止しました。「失敗したバックフィルからの回復」を参照してください。

CANCELLED

バックフィルは完了する前にキャンセルされました。

状態

説明

PENDING

バックフィルは受け付けられましたが、実行は起動されていません。

RUNNING

バックフィルが実行されています。

SUCCEEDED

バックフィルが終了し、範囲内の特徴量値が再計算されました。

FAILED

バックフィルはエラーのため停止しました。「失敗したバックフィルからの回復」を参照してください。

CANCELLED

バックフィルは完了する前にキャンセルされました。

操作名が不明な場合は、list_materialized_features から返される latest_backfill_operation フィールドでマテリアライズド特徴量の最新のバックフィルを見つけ、それを get_backfill に渡します。

バックフィルをキャンセルするには、ステータスを指定してcancel_backfillを呼び出します。

Python
fe.cancel_backfill(backfill=backfill)

バックフィルをキャンセルすると、停止するように要求されます。もうすぐ終了するバックフィルは成功する可能性があります。そのため、get_backfillで最終状態を確認してください。すでに完了しているバックフィルをキャンセルしても効果はありません。キャンセルされたバックフィルによって、失敗したバックフィルからの復旧で説明されているように、一部の特徴量の値が再計算されたままになる可能性があります。

同時実行​

バックフィルは、スケジュールされたマテリアライゼーションと並行してランします。異なる特徴量ビューのバックフィルも同時にランできます。

一度に実行できる特徴量ビューのバックフィルは1つだけです。すでにバックフィルが進行中の特徴量ビューのバックフィルを起動すると、要求は ALREADY_EXISTS エラーで失敗します。次のバックフィルを開始する前に、前のバックフィルが終了するまでお待ちください。

失敗したバックフィルからの復旧​

失敗またはキャンセルされたバックフィルは、完了前に停止する可能性があります。バックフィルが停止する前に書き換えた各値は、完全に再計算されます。到達できなかった値は以前の値のままになるため、一部の特徴量ビューまたは時間範囲が更新されない場合があります。

復旧するには、同じバックフィルをもう一度起動してください。request_idを渡した場合は、新しいものを渡してください。元のrequest_idで再試行すると、新しいバックフィルが開始される代わりに、失敗したバックフィルが返されるためです。バックフィルは安全に繰り返すことができます。ソースデータが変更されていない場合、すでに成功している範囲を再計算しても同じ値が生成されます。

制限​

  • DeltaTableSource と SlidingWindow または TumblingWindow を使用するバッチ集計特徴量のみをバックフィルできます。ストリーミング特徴量、ColumnSelection 特徴量、RollingWindow または SawtoothWindow を持つ特徴量、ライフタイムウィンドウを持つ特徴量、および RequestSource などの他のソースを持つ特徴量はバックフィルできません。
  • 異なる間隔またはオフセットで値を生成する特徴ビューは、1つのバックフィルを共有できません。各グループの個別のバックフィルを起動します。
  • バックフィルは特徴量ビューのオフラインテーブルを更新し、特徴量ビューがオンラインストアにマテリアライズされている場合は、そのオンラインテーブルも更新します。一方のみをバックフィルすることはできません。
  • バックフィルは、最新のマテリアライズド値の後の時間範囲を埋めるものではありません。スケジュールされたマテリアライゼーションによってそれらが埋められます。
このページの見出し