Backfill Feature Views

Backfill berechnet die materialisierten Werte Ihrer Feature Views über die von Ihnen gewählten Zeiträume neu. Verwenden Sie es, nachdem Sie historische Quelldaten korrigiert oder hinzugefügt haben, sodass die Offline- und Online-Materialisierungen die aktualisierten Daten widerspiegeln.

Die Materialisierung berechnet bei jedem Durchlauf die aktuellen Feature-Werte und berechnet bereits geschriebene Werte nicht erneut. Eine Änderung der Quelldaten für einen vergangenen Zeitraum erreicht die materialisierten Werte erst, wenn man für diesen Zeitraum ein Backfill ausführt. Verwenden Sie Backfill in Szenarien wie den folgenden:

  • Ein Problem mit der Datenqualität in den vorgelagerten Daten hat einen vergangenen Zeitraum beeinflusst, und du hast die Quellzeilen korrigiert.
  • Quelldaten für einen vergangenen Zeitraum trafen ein, nachdem die Materialisierung sie bereits verarbeitet hatte.

Ein Backfill ist ein einmaliger Auftrag, der parallel zu Ihrer geplanten Materialisierung läuft. Das ändert nichts am Materialisierungsplan. Siehe Materialisieren von Featureansichten.

Requirements

  • databricks-feature-engineering 0.18.2 und höher. Weitere Anforderungen finden Sie unter Anforderungen.
  • Jede Feature View ist eine Batch-Aggregationsfunktion, die eine DeltaTableSource und eine SlidingWindow oder TumblingWindowverwendet. Dauerhafte Fenster werden nicht unterstützt.
  • Jede Feature View wird materialisiert und hat mindestens einen Materialisierungslauf abgeschlossen. Backfill berechnet Werte neu, die die Materialisierung bereits geschrieben oder gespeichert hat, sodass eine Feature View nicht zum ersten Mal materialisiert werden kann.
  • Sie starten den Abgleich als denselben Benutzer oder denselben Dienstprinzipal, der die Featureansichten materialisiert hat, und zwar aus dem Arbeitsbereich, in dem diese materialisiert wurden.

Erlaubnisse

Backfill wird unter deinem Benutzer ausgeführt und liest und schreibt die gleichen Tabellen wie deine Materialisierung, also nutzt es die gleichen Privilegien wie deine Materialisierung. Beschreibungen aller Unity Catalog-Berechtigungen finden Sie unter Referenz zu Unity Catalog-Berechtigungen.

  • Sie müssen in jeder Feature-Ansicht, die Sie beim Abgleich nachfüllen, MANAGE angeben.
  • Um einen Abgleich zu überprüfen, benötigen Sie READ FEATURE in jeder Objektansicht des Abgleichs. Um einen Abgleich abzubrechen, benötigen Sie MANAGE in jeder Objektansicht des Abgleichs.

Backfill starten

Um einen Backfill zu starten, rufen Sie backfill_features mit den Feature Views, für die ein Backfill ausgeführt werden soll, und einem oder mehreren Zeitspannen auf:

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:

Alle Feature Views in einem Aufruf müssen zu denselben Zeitpunkten Werte erzeugen. Sie müssen dasselbe Intervall zwischen Werten (die slide_duration eines SlidingWindow oder die window_duration eines TumblingWindow) und dasselbe offset haben. Andernfalls schlägt der Aufruf mit einem Fehler fehl, der die Featureansichten nach Intervallen gruppiert, sodass Sie für jede Gruppe einen separaten Abgleich-Vorgang starten können.

Jede BackfillRange hat ein start_time, das inklusiv ist, und ein end_time, das exklusiv ist. Beide sind Python-Wertedatetime. Ein datetime ohne Angabe einer Zeitzone wird als UTC interpretiert. Jeder start_time muss früher als sein end_timesein, und die Bereiche eines Calls dürfen sich nicht überlappen. Informationen dazu, wie der Abgleich die einzelnen Bereiche interpretiert, finden Sie unter Wie der Abgleich Zeitbereiche anwendet.

Das folgende Beispiel füllt für zwei Feature Views eine Woche Verlauf rückwirkend nach:

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>

Bevor das Auffüllen beginnt, prüft backfill_features Folgendes. Wenn eine Prüfung fehlschlägt, scheitert der Aufruf mit einem Fehler, der die betroffenen Feature Views benennt.

  • Jede Feature View erfüllt die Anforderungen, einschließlich eines abgeschlossenen Materialisierungslaufs.
  • Du hast jede Feature View materialisiert.
  • Du hast die erforderlichen Rechte.

Die Methode gibt ein BackfillStatus zurück, das den Backfill beschreibt. operation_name identifiziert den Abgleich im Format operations/<operation-id>. Weitere Informationen finden Sie unter Abgleich überwachen oder abbrechen.

Um einen sicheren erneuten Aufruf zu ermöglichen, übergeben Sie eine UUID als request_id. Ein erneuter Versuch mit demselben request_id bringt das ursprüngliche Backfill zurück, anstatt ein neues zu starten.

Um die Kosten für einen Backfill zuzuordnen, übergeben Sie tags, budget_policy_id oder beides. Sie gelten nur für diese Verfüllung. Siehe Attributkosten mit Tags und serverlosen Nutzungsrichtlinien.

Wie Backfill auf Zeiträume angewendet wird

Jeder Bereich wählt die Quelldaten aus, die erneut verarbeitet werden sollen: die Quellzeilen mit Zeitstempeln ab start_time und bis einschließlich end_time. Backfill wendet jeden Bereich wie folgt an:

  • Die Bereiche sind auf ganze Merkmalswerte ausgerichtet. Bei der Methode des Abgleichs werden die Werte des gesamten Merkmals neu berechnet, sodass jeder Bereich nach außen hin bis zu den nächstgelegenen Zeitpunkten erweitert wird, zu denen das Merkmal einen Wert liefert. Ein SlidingWindow-Merkmal liefert alle slide_duration einen Wert, und ein TumblingWindow-Merkmal liefert alle window_duration einen Wert, verschoben um den Wert offset des Fensters, sofern Sie einen solchen festgelegt haben. Zum Beispiel wird bei einer Funktion mit 1-stündiger slide_duration ein Zeitraum von 1:30 Uhr bis 2:30 Uhr zu 1:00 Uhr bis 3:00 Uhr morgens. Du musst die Bereiche nicht selbst ausrichten. Bereiche, die sich nach der Ausrichtung überlappen, werden zu einem kombiniert.
  • Werte außerhalb des Bereichs können sich ändern. Der Abgleich schreibt jeden Feature-Wert neu, dessen Zeitfenster neu verarbeitete Daten umfasst. Ein Fenster kann nach end_timeenden , sodass sich Werte bis zu einem window_duration nach end_time ändern können. Für ein Merkmal mit einem 7-Tage-window_duration können sich beispielsweise Werte bis zu 7 Tage nach end_time ändern.
  • Das Auffüllen stoppt bei den zuletzt materialisierten Werten. Der Abgleich berechnet nur die Historie neu, die vom Materialisierungsvorgang bereits geschrieben wurde. Wenn eine Spanne über die zuletzt materialisierten Werte hinausgeht, endet das Auffüllen dort und lässt den späteren Zeitraum für Ihre geplante Materialisierung.
  • Nicht festgelegte Grenzen reichen bis zu den verfügbaren Daten. Wenn Sie start_time weglassen, beginnt der Bereich mit dem frühesten Zeitstempel in den Quelldaten. Wenn Sie end_time weglassen, erstreckt sich der Bereich auf die zuletzt materialisierten Werte.

Die backfill_ranges eines BackfillStatus sind die Bereiche nach der Ausrichtung. Backfill schränkt sie nicht auf die zuletzt materialisierten Werte ein, sodass ein gemeldeter Bereich über die Werte hinausgehen kann, die das Backfill neu berechnet hat. Du musst die späteren Werte nicht nachfüllen, weil deine geplante Materialisierung sie aus den aktuellen Quelldaten berechnet.

Offline- und Online-Tabellen

Backfill aktualisiert die Offline-Tabelle einer Feature View und, falls die Feature View auch in einen Online-Store materialisiert wird, deren Online-Tabelle. Für eine Feature View mit beiden Tabellen berechnet Backfill die Offline-Tabelle neu und veröffentlicht dann die Online-Tabelle aus dieser erneut. Sie können nicht nur ein Element abgleichen.

Die Online-Tabelle enthält den neuesten Wert für jede Entität. Ein Backfill ändert Online-Werte nur, wenn er den neuesten Wert einer Entität ändert.

Backfill überwachen oder stornieren

backfill_features kehrt zurück, ohne auf den Abgleich zu warten. Warten Sie, übergeben Sie wait=True oder rufen Sie wait_for_backfill mit dem zurückgegebenen Status auf:

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill gibt das endgültige BackfillStatus zurück, wenn der Abgleich gelingt. Wenn das Backfill fehlschlägt oder abgebrochen wird, wird ein OperationFailed Fehler ausgelöst, der den Grund beschreibt. Um die Wartezeit zu begrenzen, geben Sie ein timeout als ein timedelta durch. Wenn der Abgleich bis dahin nicht fertig ist, löst wait_for_backfill ein TimeoutError aus. Das Stoppen des Wartens hebt den Abgleich nicht auf.

Um einen Abgleich ohne Wartezeit oder aus einem anderen Notizbuch oder Auftrag zu überprüfen, rufen Sie get_backfill mit dem Operationsnamen auf:

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

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

Ein BackfillStatus hat folgende Felder:

  • operation_name: Der Name, der das Backfill kennzeichnet.
  • state: Der Zustand des Abgleich als BackfillState-Wert.
  • feature_full_names: Die vollständigen Namen der Feature Views im Backfill.
  • backfill_ranges: Die ausgerichteten Zeitbereiche als BackfillRange Werte mit UTC-Grenzen.
  • error: Der Grund, warum das Backfill fehlgeschlagen ist. Dieses Feld wird nur gesetzt, wenn stateFAILED ist.

Der Backfill-Zustand hat einen der folgenden Werte:

State Description
PENDING Die Nachfüllung wurde akzeptiert und noch nicht gestartet.
RUNNING Der Backfill läuft.
SUCCEEDED Der Abgleich wurde fertiggestellt und die Feature-Werte in den Intervallen neu berechnet.
FAILED Der Backfill wurde aufgrund eines Fehlers gestoppt. Siehe Wiederherstellung nach einem fehlgeschlagenen Abgleich.
CANCELLED Der Backfill wurde abgebrochen, bevor er abgeschlossen war.

Wenn Sie den Operationsnamen nicht haben, finden Sie das aktuellste Backfill eines materialisierten Features im von list_materialized_features zurückgegebenen Feld latest_backfill_operation und übergeben es an get_backfill.

Um einen Backfill aufzuheben, rufen Sie cancel_backfill mit seinem Status auf:

fe.cancel_backfill(backfill=backfill)

Durch das Abbrechen eines Abgleichs wird dessen Beendigung veranlasst. Ein Backfill, der kurz vor dem Ende steht, kann dennoch noch erfolgreich abgeschlossen werden, also prüfe seinen Endzustand mit get_backfill. Das Stornieren eines bereits fertiggestellten Backfills hat keine Wirkung. Ein abgebrochener Backfill kann dazu führen, dass einige Merkmalswerte neu berechnet werden, wie in Recover from a failed Backfill beschrieben.

Konkurrenz

Ein Backfill läuft parallel zu deiner geplanten Materialisierung. Backfills verschiedener Feature Views können ebenfalls gleichzeitig ausgeführt werden.

Für eine Feature View kann jeweils nur ein Backfill ausgeführt werden. Wenn Sie eine Backfill für eine Feature View starten, die bereits einen Backfill im Gange hat, scheitert die Anfrage mit einem ALREADY_EXISTS Fehler. Warte, bis der vorherige Backfill fertig ist, bevor du mit dem nächsten startest.

Wiederherstellung nach einem fehlgeschlagenen Abgleich

Ein fehlgeschlagener oder abgebrochener Abgleich kann stoppen, bevor er fertig ist. Jeder Wert, den das Backfill neu geschrieben hat, bevor es anhielt, wird vollständig neu berechnet. Werte, die es nicht erreicht hat, behalten ihre früheren Werte, sodass einige Feature Views oder Zeitbereiche möglicherweise nicht aktualisiert werden.

Um den Vorgang wiederherzustellen, starten Sie denselben Abgleich erneut. Falls Sie einen Wert request_id übergeben haben, übergeben Sie bitte einen neuen Wert, da ein erneuter Versuch mit dem ursprünglichen Wert request_id den fehlgeschlagenen Abgleich zurückgibt, anstatt einen neuen zu starten. Backfill kann gefahrlos wiederholt werden. Wenn sich die Quelldaten nicht geändert haben, erzeugt die Neuberechnung eines Bereichs, der bereits erfolgreich neu berechnet wurde, dieselben Werte.

Limitations

  • Nur Batch-Aggregationsfunktionen, die ein DeltaTableSource und ein SlidingWindow oder TumblingWindow verwenden, können abgeglichen werden. Streaming-Funktionen, ColumnSelection Features, Features mit einem RollingWindow oder SawtoothWindow, Features mit einem Lifetime-Fenster und Features mit anderen Quellen, wie RequestSource, können nicht zurückgefüllt werden.
  • Feature Views, die Werte in unterschiedlichen Abständen oder Offsets erzeugen, können keinen einzigen Backfill teilen. Starte für jede Gruppe ein separates Backfill.
  • Backfill aktualisiert die Offline-Tabelle einer Feature View und, falls die Feature View auch in einen Online-Store materialisiert wird, deren Online-Tabelle. Sie können nicht nur ein Element abgleichen.
  • Backfill füllt keine Zeiträume nach den zuletzt materialisierten Werten aus. Ihre geplante Materialisierung füllt diese aus.
  • Zuletzt aktualisiert um