Backfill Feature Views

Backfill beräknar om de materialiserade värdena för dina Feature Views över tidsintervall som du väljer. Använd den efter att du har rättat eller lagt till historisk källdata, så att offline- och onlinematerialiseringarna speglar den uppdaterade datan.

Materialization beräknar de senaste feature-värdena vid varje körning och bearbetar inte igen värden som den redan har skrivit. En ändring av källdata för ett tidigare tidsintervall når inte de materialiserade värdena förrän du bakåtfyller det tidsintervallet. Använd backfill i scenarier som följande:

  • Ett problem med datakvaliteten uppströms påverkade ett tidigare tidsintervall, och du rättade källraderna.
  • källdata för ett tidigare tidsintervall anlände efter att materialiseringen redan hade bearbetat den.

En backfill är ett engångsjobb som löper parallellt med din planerade materialisering. Det förändrar inte materialiseringsschemat. Se Materialisera funktionsvyer.

Requirements

  • databricks-feature-engineering 0.18.2 och uppåt. För andra krav, se Krav.
  • Varje Feature View är en batchaggregationsfunktion som använder en DeltaTableSource och en SlidingWindow eller TumblingWindow. Fönster med beständighet stöds inte.
  • Varje Feature View är materialiserad och har genomfört minst en materialiseringsrunda. Backfill beräknar om värden som materialiseringen redan har skrivit, så Backfill kan inte materialisera en Feature View för första gången.
  • Du startar backfillen som samma användare eller tjänsteprincip som materialiserade Feature Views, från arbetsytan där de materialiserades.

Permissions

Backfill körs som du, och den läser och skriver samma tabeller som din materialisering, så den använder samma privilegier som din materialisering. För fullständiga Unity Catalog-privilegiebeskrivningar, se referensen för Unity-katalogens privilegier.

  • Du måste ha MANAGE på varje Feature View som du bakfyller.
  • För att kontrollera en backfill behöver du READ FEATURE på varje Feature View i backfillen. För att avbryta en backfill behöver du MANAGE för varje Feature View i backfillen.

Starta en backfill

För att starta en backfill, anropa backfill_features med Feature Views för att backfylla och ett eller flera tidsintervall:

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:

Alla funktionsvyer i ett anrop måste generera värden vid samma tidpunkter. De måste ha samma intervall mellan värden (the SlidingWindow av en window_duration eller the TumblingWindow av en offset) och samma slide_duration. Annars misslyckas anropet med ett felmeddelande om att Feature Views grupperas efter intervall, så att du kan starta en separat backfill för varje grupp.

Varje BackfillRange har en start_time, som är inkluderande, och en end_time, som är exklusiv. Båda är Python-värden datetime. Ett datetime utan tidszon läses som UTC. Varje start_time måste vara tidigare än sin end_time, och intervallen i ett samtal får inte överlappa. För hur backfill tolkar varje intervall, se Hur backfill tillämpar tidsintervall.

Följande exempel fyller ut en veckas historik för två 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>

Innan fyllningen börjar kontrollerar backfill_features följande. Om en kontroll misslyckas, misslyckas anropet med ett fel som namnger de berörda Feature Views.

Metoden returnerar en BackfillStatus som beskriver backfillen. Dess operation_name identifierar backfill, i formatet operations/<operation-id>. Se Övervaka eller avbryta backfill.

För att göra anropet säkert att försöka igen, ange ett UUID som request_id. Ett nytt försök med samma request_id ger den ursprungliga backfill istället för att starta en ny.

För att tillskriva kostnaden för en återfyllning, ange tags, budget_policy_id eller båda. De gäller endast den bakåtfyllningen. Se Attributkostnader med taggar och serverless användningspolicys.

Hur backfill tillämpar tidsintervall

Varje intervall väljer källdata att återbearbeta: källraderna med tidsstämplar vid eller efter start_time och före end_time. Backfill tillämpar varje intervall enligt följande:

  • Intervallen justeras mot hela objektvärden. Backfill beräknar om alla feature-värden, så det utvidgar varje intervall utåt till de närmaste tidpunkter då featuren producerar ett värde. En SlidingWindow funktion ger ett värde varje slide_duration, och en TumblingWindow funktion ger ett varje window_duration, förskjutet med fönstrets offset om du sätter ett. Till exempel, för en funktion med en 1-timmars slide_duration, blir intervallet från 01:30 till 02:30 till 01:00 till 03:00. Du behöver inte linjera intervallen själv. Intervall som överlappar efter justering slås ihop till ett intervall.
  • Värden utanför intervallet kan ändras. Backfill skriver om varje funktionsvärde vars tidsfönster inkluderar ombehandlade data. Ett fönster kan sluta efter end_time, så värden upp till ett window_duration efter end_time kan ändras. Till exempel, för en funktion med 7-dagars window_duration, kan värden upp till 7 dagar efter end_time ändras.
  • Backfill stannar vid de senaste materialiserade värdena. Backfill beräknar bara om den historik som materialiseringen redan har skrivit. Om ett spann sträcker sig bortom de senaste materialiserade värdena, stannar bakåtfyllningen där och lämnar det senare tidsintervallet till din planerade materialisering.
  • Gränser som inte angetts sträcker sig till tillgängliga data. Om du utelämnar start_time, börjar intervallet vid den tidigaste tidsstämpeln i källdatan. Om du utelämnar end_time, sträcker intervallet sig till det senast materialiserade värdet.

backfill_ranges för en BackfillStatus är dina intervall efter justering. Backfill begränsar dem inte till de senaste materialiserade värdena, så ett rapporterat intervall kan sträcka sig bortom de värden som backfillen beräknade om. Du behöver inte bakåtfylla de senare värdena, eftersom din schemalagda materialisering beräknar dem från den aktuella källdatan.

Offline- och onlinetabeller

Backfill uppdaterar offline-tabellen för en Feature View och, om Feature View också materialiseras till en onlinebutik, dess online-tabell. För en Feature View med båda beräknar backfill om offline-tabellen och återpublicerar sedan online-tabellen från den. Du kan inte bara bakåtfylla en av dem.

Onlinetabellen innehåller det senaste värdet för varje objekt. En backfill ändrar online-värden endast när den ändrar det senaste värdet för en entitet.

Övervaka eller avbryt en backfill

backfill_features returnerar utan att vänta på att fyllningen ska bli klar. För att vänta, skicka wait=True, eller anropa wait_for_backfill med den returnerade statusen:

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill returnerar det slutliga BackfillStatus när backfillen lyckas. Om backfill misslyckas eller avbryts uppstår ett OperationFailed-fel som beskriver orsaken. För att begränsa hur länge den väntar, skicka timeout som en timedelta. Om backfillen inte är klar då, utlöser wait_for_backfill en TimeoutError. Att stoppa väntan avbryter inte backfill.

För att kontrollera en backfill utan att vänta, eller från en annan anteckningsbok eller jobb, anropa get_backfill med operationsnamnet:

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

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

BackfillStatus har följande fält:

  • operation_name: Namnet som identifierar utfyllningen.
  • state: Tillståndet för återfyllning, som ett BackfillState-värde.
  • feature_full_names: De fullständiga namnen på Feature Views i backfillen.
  • backfill_ranges: De alignerade tidsintervallen, som BackfillRange-värden med UTC-gränser.
  • error: Anledningen till att backfill misslyckades. Detta fält anges endast när state är FAILED.

Tillfyllningstillståndet är ett av följande värden:

State Description
PENDING Backfillen accepterades och har inte börjat köras ännu.
RUNNING Backfill körs.
SUCCEEDED Backfillen slutfördes och omberäknade featurevärdena i sina intervall.
FAILED Backfill stoppades på grund av ett fel. Se Återställ efter en misslyckad backfill.
CANCELLED Fyllningen avbröts innan den var klar.

Om du inte har operationsnamnet, hitta den senaste backfillen av en materialiserad funktion i latest_backfill_operation fältet som returneras av list_materialized_features, och skicka den till get_backfill.

För att avbryta backfillen, anropa cancel_backfill när den har statusen:

fe.cancel_backfill(backfill=backfill)

Att avbryta en backfill begär att den stoppas. En backfill som är på väg att bli klar kan fortfarande lyckas, så kontrollera dess slutgiltiga tillstånd med get_backfill. Att avbryta en backfill som redan är klar har ingen effekt. En avbruten backfill kan lämna vissa funktionsvärden omberäknade, som beskrivs i Återställ efter en misslyckad backfill.

Concurrency

En backfill körs parallellt med din planerade materialisering. Backfills av olika Feature Views kan också köras samtidigt.

Endast en backfill kan köras för en Feature View åt gången. Om du startar en backfill för en Feature View som redan har en backfill som pågår, misslyckas förfrågan med ett ALREADY_EXISTS-fel. Vänta tills den tidigare backfillen är klar innan du börjar med nästa.

Återställ efter en misslyckad backfill

En misslyckad eller avbruten fyllning kan stanna innan den är klar. Varje värde som backfillen skrev om innan den stannade beräknas om fullständigt. Värden som inte nåddes behåller sina tidigare värden, så vissa funktionsvyer eller tidsintervall kanske inte uppdateras.

För att återställa, starta samma backfill igen. Om du skickade in en request_id, skicka in en ny, eftersom ett nytt försök med det ursprungliga request_id returnerar den misslyckade backfillen i stället för att starta en ny. Backfill kan upprepas utan risk. Om källdatan inte har ändrats, ger omberäkning av ett intervall som redan har beräknats samma värden.

Limitations

  • Endast batchaggregeringsfunktioner som använder DeltaTableSource och SlidingWindow eller TumblingWindow kan efterfyllas. Streamingfunktioner, ColumnSelection funktioner, funktioner med ett RollingWindow eller SawtoothWindow, funktioner med ett livstidsfönster och funktioner med andra källor, såsom RequestSource, kan inte fyllas i retroaktivt.
  • Feature Views som ger värden med olika intervall eller offsets kan inte dela en backfill. Starta en separat backfill för varje grupp.
  • Backfill uppdaterar offline-tabellen för en Feature View och, om Feature View också materialiseras till en onlinebutik, dess online-tabell. Du kan inte bara bakåtfylla en av dem.
  • Backfill fyller inte i tidsintervall efter de senaste materialiserade värdena. Din schemalagda materialisering fyller i dem.