Backfill delle Feature View

Backfill ricalcola i valori materializzati delle tue Feature Views negli intervalli di tempo che scegli. Usala dopo aver corretto o aggiunto dati di fonte storici, così che le materializzazioni offline e online riflettano i dati aggiornati.

La materializzazione calcola i valori recenti delle feature a ogni run e non rivisita i valori già scritti. Una modifica ai dati di origine per un intervallo temporale passato non si riflette nei valori materializzati finché non si esegue il backfill di quell'intervallo. Usa il backfill in scenari come i seguenti:

• Un problema di qualità dei dati a monte ha influenzato un intervallo di tempo passato, e hai corretto le righe di sorgente.
• I dati di origine di un intervallo temporale passato arrivarono dopo che la materializzazione li aveva già processati.

Il backfill è un lavoro una tantum che viene eseguito parallelamente alla tua materializzazione programmata. Non cambia il calendario di materializzazione. Vedere Materialize Feature Views.

Requirements

• databricks-feature-engineering 0.18.2 e oltre. Per altri requisiti, vedi Requisiti.
• Ogni Feature View è una funzione di aggregazione batch che utilizza una DeltaTableSource e una SlidingWindow o TumblingWindow. Le finestre permanenti non sono supportate.
• Ogni Feature View è materializzata e ha completato almeno un'esecuzione di materializzazione. Il backfill ricalcola valori già scritti da materialization, quindi non può materializzare una Feature View per la prima volta.
• Si avvia il backfill con lo stesso utente o service principal che ha materializzato le Feature Views, dallo spazio di lavoro in cui sono state materializzate.

Permissions

Il backfill viene eseguito con la tua identità, legge e scrive le stesse tabelle della tua materializzazione, quindi usa gli stessi privilegi della tua materializzazione. Per descrizioni complete dei privilegi del Catalogo Unity, vedi riferimento ai privilegi del Catalogo Unity.

• Devi avere MANAGE in ogni Feature View per cui esegui il backfill.
• Per controllare un backfill, devi essere READ FEATURE su ogni Feature View nel backfill. Per annullare un backfill, devi MANAGE su ogni Feature View nel backfill.

Avvia un backfill

Per iniziare un backfill, chiama backfill_features con le Feature Views da riempire e uno o più intervalli temporali:

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:

Tutte le Feature View in una chiamata devono produrre valori negli stessi istanti. Devono condividere lo stesso intervallo tra i valori (quello slide_duration di un SlidingWindow o quello window_duration di un TumblingWindow) e lo stesso offset. Altrimenti, la chiamata fallisce con un errore che raggruppa le Feature View per intervallo, così da poter iniziare un backfill separato per ogni gruppo.

Ogni BackfillRange ha un start_time, che è inclusivo, e un end_time, che è esclusivo. Entrambi sono valori Pythondatetime. Un datetime senza fuso orario viene letto come UTC. Ogni start_time deve essere precedente al suo end_time, e gli intervalli in una chiamata non possono sovrapporsi. Per capire come il backfill interpreta ogni intervallo, vedi Come il backfill applica gli intervalli di tempo.

Il seguente esempio riempie una settimana di storia per due 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>

Prima che inizi il riempimento, backfill_features controlla quanto segue. Se un controllo fallisce, la chiamata fallisce con un errore che nomina le Feature View interessate.

• Ogni Feature View soddisfa i requisiti, inclusa una sequenza di materializzazione completata.
• Hai materializzato ogni Feature View.
• Hai i privilegi necessari.

Il metodo restituisce un BackfillStatus che descrive il riempimento (backfill). Il suo operation_name identifica il backfill, nel formato operations/<operation-id>. Vedere Monitorare o annullare un backfill.

Per rendere sicura la ripetizione della chiamata, passa un UUID come request_id. Un ritentativo con lo stesso request_id restituisce il backfill originale invece di iniziarne uno nuovo.

Per attribuire il costo di un backfill, passa tags, budget_policy_id o entrambi. Si applicano solo a quel backfill. Consulta i costi degli attributi con tag e le policy di utilizzo serverless.

Come il backfill applica gli intervalli di tempo

Ogni intervallo seleziona i dati sorgente da rielaborare: le righe sorgente con timestamp pari o successivi a start_time e precedenti a end_time. Backfill applica ogni intervallo come segue:

• Gli intervalli sono allineati ai valori interi della funzionalità. Backfill ricalcola l'intero insieme di valori della caratteristica, allargando ogni intervallo verso l'esterno fino ai momenti più vicini in cui la caratteristica produce un valore. Una SlidingWindow funzionalità produce un valore ogni slide_duration, e una TumblingWindow funzionalità produce un valore ogni window_duration, spostato dall'offset della finestra se ne imposti una. Ad esempio, per una funzionalità con una finestra di 1 ora slide_duration, un intervallo da 1:30 AM a 2:30 AM diventa 1:00 AM a 3:00 AM. Non devi allineare gli intervalli da solo. I range che si sovrappongono dopo l'allineamento vengono combinati in uno solo.
• I valori dopo il range possono cambiare. Il backfill riscrive ogni valore di caratteristica la cui finestra temporale include i dati rielaborati. Una finestra può terminare dopo end_time, quindi i valori fino a 1 window_duration dopo end_time possono cambiare. Ad esempio, per una funzionalità con un intervallo di 7 giorni window_duration, i valori fino a 7 giorni dopo end_time possono cambiare.
• Il riempimento si ferma ai valori più recenti materializzati. Il Backfill ricalcola solo la storia che la materialization ha già scritto. Se un intervallo supera i valori materializzati più recenti, il backfill si ferma lì e lascia che la materializzazione pianificata gestisca l'intervallo di tempo successivo.
• I limiti non impostati si estendono ai dati disponibili. Se ometti start_time, l'intervallo inizia dal timestamp più antico nei dati di origine. Se si omette end_time, l'intervallo si estende fino ai valori materializzati più recenti.

Il backfill_ranges di una BackfillStatus sono i tuoi intervalli dopo l'allineamento. Il backfill non li restringe ai valori materializzati più recenti, quindi un intervallo riportato può andare oltre i valori che il backfill ha ricalcolato. Non è necessario backfillare i valori futuri, perché la materializzazione programmata li calcola dai dati di origine attuali.

Tabelle offline e online

Il backfill aggiorna la tabella offline di una Feature View e, se la Feature View viene materializzata anche su uno store online, la sua tabella online. Per una Feature View con entrambe le tabelle, il backfill ricalcola la tabella offline e poi ripubblica la tabella online da essa. Non puoi eseguire il backfill solo di uno di essi.

La tabella online contiene il valore più recente per ogni entità. Un backfill cambia i valori online solo quando modifica il valore più recente di un'entità.

Monitora o annulla un backfill

backfill_features ritorna senza aspettare che il backfill finisca. Per aspettare, passare wait=True o chiamare wait_for_backfill con lo stato restituito:

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill restituisce l'ultimo BackfillStatus quando il backfill ha successo. Se il riempimento fallisce o viene annullato, genera un OperationFailed errore che descrive la ragione. Per limitare quanto tempo aspetta, passa un timeout come timedelta. Se il riempimento non è finito entro quel momento, wait_for_backfill genera un TimeoutError. Fermare l'attesa non annulla il backfill.

Per controllare un backfill senza aspettare, o da un altro notebook o job, chiama get_backfill con il nome dell'operazione:

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

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

Un BackfillStatus ha i seguenti campi:

• operation_name: Il nome che identifica il backfill.
• state: Lo stato del riempimento, come valore BackfillState.
• feature_full_names: I nomi completi delle Feature View nel backfill.
• backfill_ranges: I intervalli temporali allineati, come valori BackfillRange con limiti UTC.
• error: Il motivo per cui il backfill non è riuscito. Questo campo è impostato solo quando state è FAILED.

Lo stato di backfill è uno dei seguenti valori:

Se non hai il nome dell'operazione, trova il backfill più recente di una feature materializzata nel campo latest_backfill_operation restituito da list_materialized_features e passalo a get_backfill.

Per annullare un backfill, chiama cancel_backfill specificandone lo stato:

fe.cancel_backfill(backfill=backfill)

L'annullamento di un backfill ne richiede l'arresto. Un backfill che sta per completarsi può comunque avere successo, quindi controlla il suo stato finale con get_backfill. Annullare un backfill che è già finito non ha alcun effetto. Un backfill cancellato può far ricalcolare alcuni valori delle funzionalità, come descritto in Recover from a failed backfill.

Concurrency

Un backfill viene eseguito in parallelo alla tua materialization programmata. Anche i backfill di diverse Feature View possono essere eseguiti contemporaneamente.

Solo un backfill può essere eseguito per una Feature View alla volta. Se inizi un backfill per una Feature View che ha già un backfill in corso, la richiesta fallisce con un ALREADY_EXISTS errore. Aspetta che il backfill precedente finisca prima di iniziare il prossimo.

Recupero da un backfill non riuscito

Un backfill non riuscito o annullato può interrompersi prima di terminare. Ogni valore che il backfill ha riscritto prima di fermarsi viene completamente ricalcolato. I valori che non sono stati raggiunti mantengono i valori precedenti, quindi alcune Feature View o intervalli temporali potrebbero non essere aggiornati.

Per recuperare, avvia nuovamente lo stesso backfill. Se hai fornito un request_id, forniscine uno nuovo, perché un nuovo tentativo con l'originale request_id restituisce il backfill non riuscito invece di avviarne uno nuovo. Il backfill può essere ripetuto in sicurezza. Se i dati sorgente non sono cambiati, ricalcolare un intervallo già calcolato con successo produce gli stessi valori.

Limitations

• Solo le funzionalità di aggregazione batch che usano DeltaTableSource e SlidingWindow o TumblingWindow possono essere retrocompilate. Le funzionalità di streaming, le funzionalità ColumnSelection, le funzionalità con un RollingWindow o un SawtoothWindow, le funzionalità con una finestra di vita e le funzionalità con altre fonti, come RequestSource, non possono essere popolate retroattivamente.
• Le feature View che producono valori a intervalli diversi o offset non possono condividere un solo backfill. Inizia un backfill separato per ogni gruppo.
• Il Backfill aggiorna la tabella offline di una Feature View e, se la Feature View viene materializzata anche su un archivio online, la sua tabella online. Non puoi backfillare solo uno di essi.
• Backfill non popola gli intervalli di tempo successivi ai valori materializzati più recenti. Il tuo aggiornamento pianificato li riempie.