Backfill-featureweergaven

Backfill berekent opnieuw de gematerialiseerde waarden van je Feature Views over de door je gekozen tijdsperioden. Gebruik het nadat je historische brongegevens hebt gecorrigeerd of toegevoegd, zodat de offline en online materialisaties de bijgewerkte data weerspiegelen.

Materialisatie berekent bij elke run recente featurewaarden en bezoekt de reeds geschreven waarden niet opnieuw. Een wijziging van de brongegevens voor een eerdere periode bereikt de gematerialiseerde waarden pas als je die tijdsperiode backfillt. Gebruik backfill in scenario's zoals de volgende:

  • Een probleem met de gegevenskwaliteit in een upstream databron heeft een eerdere tijdsperiode beïnvloed, en je hebt de bronrijen gecorrigeerd.
  • Brongegevens voor een tijdsbereik in het verleden arriveerden nadat materialisatie deze al had verwerkt.

Een backfill is een eenmalige klus die parallel loopt aan je geplande materialisatie. Het verandert het materialisatieschema niet. Zie Functieweergaven materialiseren.

Requirements

  • databricks-feature-engineering 0.18.2 en hoger. Zie voor andere vereisten Vereisten.
  • Elke Feature View is een batchaggregatiefunctie die een DeltaTableSource gebruikt en een SlidingWindow of TumblingWindow. Vensters met onbepaalde duur worden niet ondersteund.
  • Elke Feature View is gematerialiseerd en heeft minstens één materialisatierun voltooid. Backfill berekent waarden opnieuw die materialisatie al heeft geschreven, dus het kan geen Feature View voor het eerst materialiseren.
  • Je voert de backfill uit als dezelfde gebruiker of service-principal die de Feature Views heeft gematerialiseerd, vanuit de werkruimte waar ze zijn gematerialiseerd.

Permissions

Backfill draait als jij en leest en schrijft dezelfde tabellen als je materialisatie, dus het gebruikt dezelfde privileges als je materialisatie. Voor volledige Unity Catalog privilegebeschrijvingen, zie Unity Catalog privileges referentie.

  • Je moet MANAGE hebben op elke Feature View die je backfillt.
  • Om een backfill te controleren, heb je READ FEATURE nodig op elke Feature View in de backfill. Om een backfill te annuleren, moet je MANAGE op elke Feature View in de backfill hebben.

Backfill starten

Om een backfill te starten, roep je backfill_features aan met de Feature Views die je wilt backfillen en één of meer tijdsintervallen:

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 één aanroep moeten op dezelfde momenten waarden produceren. Ze moeten hetzelfde interval delen tussen waarden (de slide_duration van een SlidingWindow of de window_duration van een TumblingWindow) en dezelfde offset. Anders mislukt de aanroep met een fout over het groeperen van de Feature Views per interval, zodat je voor elke groep een aparte backfill kunt starten.

Elk BackfillRange heeft een start_time, die inclusief is, en een end_time, die exclusief is. Beide zijn Python-waardendatetime. Een datetime zonder tijdzone wordt als UTC gelezen. Elke start_time moet eerder zijn dan zijn end_time, en de intervallen in één oproep mogen niet overlappen. Zie voor informatie over hoe backfill elk bereik interpreteert, Hoe backfill tijdsintervallen toepast.

Het volgende voorbeeld vult één week geschiedenis aan voor twee Feature Views:

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>

Voordat de backfill begint, controleert backfill_features het volgende. Als een controle faalt, faalt de aanroep met een foutmelding die de getroffen Feature Views benoemt.

  • Elke Feature View voldoet aan de vereisten, inclusief een voltooide materialisatierun.
  • Je hebt elke Feature View gematerialiseerd.
  • Je hebt de vereiste privileges.

De methode geeft een BackfillStatus terug die de backfill beschrijft. Het operation_name identificeert de backfill, in het formaat operations/<operation-id>. Zie Een backfill controleren of annuleren.

Om de aanroep veilig opnieuw te proberen, moet je een UUID doorgeven als request_id. Een herpoging met dezelfde request_id geeft de oorspronkelijke backfill terug in plaats van een nieuwe te starten.

Om de kosten van een backfill toe te schrijven, geef tags, budget_policy_id of beide door. Ze gelden alleen voor die backfill. Zie Attributkosten met tags en serverless gebruiksbeleid.

Hoe backfill tijdsintervallen toepast

Elke reeks selecteert de brongegevens om opnieuw te verwerken: de bronrijen met tijdstempels op of na start_time en vóór end_time. Backfill past elk bereik als volgt toe:

  • Bereiken worden afgestemd op gehele featurewaarden. Backfill berekent volledige featurewaarden opnieuw, zodat elk bereik naar buiten wordt vergroot tot de dichtstbijzijnde tijden waarop het feature een waarde produceert. Een SlidingWindow kenmerk produceert elke slide_duration een waarde, en een TumblingWindow feature produceert er één elke window_duration, verschoven met de offset van het venster als je er een instelt. Bijvoorbeeld, voor een functie met een slide_duration van 1 uur, wordt een bereik van 1:30 uur 's nachts tot 2:30 uur 's nachts van 1:00 uur 's nachts tot 3:00 uur 's nachts. Je hoeft bereiken niet zelf uit te lijnen. bereiken die overlappen na uitlijning worden samengevoegd tot één.
  • Waarden buiten het bereik kunnen veranderen. Backfill herschrijft elke featurewaarde waarvan het tijdvenster opnieuw verwerkte gegevens omvat. Een venster kan eindigen na end_time, dus waarden tot één window_duration na end_time kunnen veranderen. Bijvoorbeeld, voor een functionaliteit met een periode van 7 dagen window_duration, kunnen waarden tot 7 dagen na end_time veranderen.
  • Backfill stopt bij de meest recent gematerialiseerde waarden. Backfill herberekent alleen de geschiedenis die materialization al heeft geschreven. Als een bereik voorbij de meest recent gematerialiseerde waarden loopt, stopt backfill daar en laat het latere tijdsbereik over aan je geplande materialisatie.
  • Niet-ingestelde grenzen lopen door tot de beschikbare gegevens. Als je start_time weglaat, begint het bereik bij de vroegste tijdstempel in de brondata. Als je end_time weglaat, strekt het bereik zich uit tot de meest recent gematerialiseerde waarden.

De waarden van een backfill_ranges van een BackfillStatus zijn je waardenbereiken na uitlijning. Backfill beperkt ze niet tot de meest recent gematerialiseerde waarden, dus een gerapporteerd bereik kan verder reiken dan de waarden die de backfill opnieuw heeft berekend. Je hoeft de latere waarden niet aan te vullen, want je geplande materialisatie berekent ze uit de huidige brondata.

Offline en online tabellen

Backfill werkt de offline tabel van een Feature View bij en, als de Feature View ook wordt gematerialiseerd naar een online store, werkt het ook de online tabel bij. Voor een Feature View met beide berekent backfill de offline tabel opnieuw en publiceert vervolgens de online tabel ervan. Je kunt er niet maar één achteraf invullen.

De online tabel bevat de laatste waarde voor elke entiteit. Een backfill verandert online waarden alleen wanneer de backfill de laatste waarde van een entiteit verandert.

Monitor of annuleer een backfill

backfill_features retourneert zonder te wachten tot de backfill klaar is. Om te wachten, geef wait=True door, of roep wait_for_backfill aan met de geretourneerde status:

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill Geeft de definitieve BackfillStatus terug wanneer de backfill slaagt. Als de backfill faalt of wordt geannuleerd, wordt er een OperationFailed fout gegenereerd die de reden beschrijft. Om de wachttijd te beperken, geef een timeout door als een timedelta. Als de backfill dan nog niet klaar is, wait_for_backfill geeft een TimeoutError. Het stoppen van het wachten annuleert de backfill niet.

Om een backfill te controleren zonder te wachten, of vanuit een ander notitieboekje of taak, roep get_backfill aan met de naam van de bewerking:

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

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

Een BackfillStatus heeft de volgende velden:

  • operation_name: De naam die de backfill identificeert.
  • state: De staat van de backfill, als waarde BackfillState .
  • feature_full_names: De volledige namen van de Feature Views in de backfill.
  • backfill_ranges: De uitgelijnde tijdsbereiken, als BackfillRange waarden met UTC-grenzen.
  • error: De reden dat de backfill faalde. Dit veld wordt alleen ingesteld wanneer state is FAILED.

De backfill-toestand is een van de volgende waarden:

State Description
PENDING De backfill werd geaccepteerd en is nog niet gestart.
RUNNING De backfill wordt uitgevoerd.
SUCCEEDED De backfill werd voltooid en de featurewaarden in zijn bereik werden opnieuw berekend.
FAILED De backfill is gestopt vanwege een fout. Zie Herstellen van een mislukte backfill.
CANCELLED De backfilltaak werd geannuleerd voordat deze was voltooid.

Als je de bewerkingsnaam niet hebt, zoek dan de meest recente backfill van een gematerialiseerd kenmerk in het latest_backfill_operation veld dat door list_materialized_features wordt teruggegeven en geef deze door aan get_backfill.

Om een backfill te annuleren, roep cancel_backfill aan met de status:

fe.cancel_backfill(backfill=backfill)

Als u een backfill annuleert, stopt deze. Een backfill die bijna klaar is, kan nog steeds slagen, dus controleer zijn eindtoestand met get_backfill. Het annuleren van een backfill die al klaar is, heeft geen effect. Een geannuleerde backfill kan ervoor zorgen dat sommige featurewaarden opnieuw worden berekend, zoals beschreven in Recover from a failed backfill.

Concurrency

Een backfill loopt parallel aan je geplande materialisatie. Backfills van verschillende Feature Views kunnen ook tegelijkertijd draaien.

Er kan slechts één backfill tegelijk draaien voor een Feature View. Als je een backfill start voor een Feature View die al een backfill in uitvoering heeft, mislukt het verzoek met een ALREADY_EXISTS foutmelding. Wacht tot de vorige backfill klaar is voordat je aan de volgende begint.

Herstellen van een mislukte backfill

Een mislukte of geannuleerde backfill kan stoppen voordat deze klaar is. Elke waarde die de backfill overschreef voordat deze stopte, wordt volledig opnieuw berekend. Waarden die het niet bereikte, behouden hun eerdere waarden, dus sommige Feature Views of tijdsbereiken worden mogelijk niet bijgewerkt.

Om het probleem te verhelpen, begin je opnieuw met dezelfde backfill. Als je een request_id hebt doorgegeven, geef dan een nieuwe door, omdat een nieuwe poging met de oorspronkelijke request_id de mislukte backfill retourneert in plaats van een nieuwe te starten. Backfill kan veilig opnieuw worden uitgevoerd. Als de brongegevens niet zijn veranderd, levert het opnieuw berekenen van een bereik dat al succesvol is berekend dezelfde waarden op.

Limitations

  • Alleen batchaggregatiefuncties die een DeltaTableSource en een SlidingWindow of TumblingWindow gebruiken kunnen worden teruggevuld. Streamingfuncties, ColumnSelection-features, features met een RollingWindow of SawtoothWindow, features met een levensduurvenster en features met andere bronnen, zoals RequestSource, kunnen niet worden aangevuld.
  • Feature Views die waarden op verschillende intervallen of offsets produceren, kunnen niet één backfill delen. Begin een aparte backfill voor elke groep.
  • Backfill werkt de offline tabel van een Feature View bij en, als de Feature View ook wordt gematerialiseerd naar een online store, ook de online tabel. Je kunt er niet maar één achteraf invullen.
  • Backfill vult geen tijdsintervallen na de meest recent gematerialiseerde waarden. Je geplande vernieuwing vult deze in.
  • Laatst bijgewerkt om