Widoki funkcji backfill

Backfill oblicza zmaterializowane wartości Twoich Feature Views w wybranych przez Ciebie przedziałach czasowych. Używaj go po poprawie lub dodaniu historycznych danych źródłowych, tak aby materializacje offline i online odzwierciedlały zaktualizowane dane.

Materializacja oblicza ostatnie wartości cech przy każdym uruchomieniu i nie wraca do już zapisanych wartości. Zmiana danych źródłowych dla przedziału czasowego z przeszłości nie jest odzwierciedlana w zmaterializowanych wartościach, dopóki nie wykonasz backfill dla tego zakresu czasu. Używaj backfill w takich sytuacjach:

  • Problem z jakością danych w źródle wpłynął na wcześniejszy przedział czasowy i poprawiłeś wiersze źródłowe.
  • Dane źródłowe z zakresu czasu z przeszłości pojawiły się po tym, jak materializacja już je przetworzyła.

Backfill to jednorazowe zadanie, które odbywa się równolegle z planowaną materializacją. Nie zmienia to harmonogramu materializacji. Zobacz Materialize Feature Views.

Requirements

  • databricks-feature-engineering 0.18.2 i więcej. Inne wymagania znajdziesz w Wymagania.
  • Każdy widok cech to funkcja agregacji wsadowej, która wykorzystuje DeltaTableSource oraz SlidingWindow lub TumblingWindow. Okna trwałe nie są obsługiwane.
  • Każdy Feature View jest materializowany i ukończył co najmniej jeden cykl materializacji. Backfill ponownie oblicza wartości, które materializacja już zapisała, więc nie może po raz pierwszy zmaterializować Feature View.
  • Backfill zaczynasz jako ten sam użytkownik lub jednostka usługi, który zmaterializował Feature Views, z przestrzeni roboczej, w której zostały zmaterializowane.

Permissions

Backfill działa z Twoimi uprawnieniami i odczytuje oraz zapisuje te same tabele co Twoja materializacja, więc korzysta z tych samych uprawnień co Twoja materializacja. Pełne opisy uprawnień w Unity Catalog można znaleźć w sekcji Informacje o uprawnieniach w Unity Catalog.

  • Musisz mieć MANAGE na każdym Feature View, dla którego wykonujesz backfill.
  • Aby sprawdzić backfill, musisz READ FEATURE w każdym widoku Feature w backfillie. Aby anulować backfill, musisz mieć MANAGE na każdym Feature View w backfillu.

Rozpocznij backfill

Aby rozpocząć uzupełnianie, wywołaj backfill_features, podając widoki cech do uzupełnienia oraz co najmniej jeden zakres czasowy:

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:

Wszystkie widoki cech w jednym wywołaniu muszą generować wartości w tych samych momentach. Muszą mieć ten sam odstęp między wartościami (slide_duration elementu window_duration lub TumblingWindow elementu offset) oraz ten sam SlidingWindow. W przeciwnym razie wywołanie kończy się niepowodzeniem i zwraca błąd informujący o pogrupowaniu widoków cech według przedziałów, dzięki czemu można rozpocząć osobny backfill dla każdej grupy.

Każdy BackfillRange ma start_time, które jest inkluzywne, oraz end_time, które jest wyłączne. Oba są wartościami w Pythonie datetime. datetime bez strefy czasowej jest odczytywany jako UTC. Każdy start_time musi być wcześniejszy niż jego end_time, a zakresy w jednym wywołaniu nie mogą się nakładać. Aby dowiedzieć się, jak backfill interpretuje każdy zakres, zobacz: Jak backfill stosuje zakresy czasowe.

Poniższy przykład uzupełnia tydzień historii dla dwóch 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>

Przed rozpoczęciem zasypywania backfill_features sprawdza następujące rzeczy. Jeśli sprawdzenie się nie powiedzie, wywołanie kończy się błędem, który wymienia obiekty Feature Views, których dotyczy problem.

  • Każdy widok cech spełnia wymagania, w tym zakończone uruchomienie materializacji.
  • Zmaterializowano każdy Feature View.
  • Masz wymagane uprawnienia.

Metoda zwraca BackfillStatus, która opisuje uzupełnienie. Jego operation_name identyfikuje wypełnienie w formacie operations/<operation-id>. Zobacz Monitoruj lub anuluj backfill.

Aby bezpiecznie ponowić wywołanie, należy podać UUID jako request_id. Ponowna próba z tym samym request_id zwraca oryginalny backfill zamiast rozpoczynać nowy.

Aby przypisać koszt backfillu, podaj tags, budget_policy_id lub oba. Dotyczą tylko tego zasypu. Zobacz Koszty atrybutów z tagami i zasadami użytkowania serverless.

Jak backfill stosuje zakresy czasowe

Każdy zakres wybiera dane źródłowe do ponownego przetwarzania: wiersze źródłowe ze znacznikami czasowymi od start_time i przed end_time. Backfill stosuje każdy zakres w następujący sposób:

  • Zakresy są wyrównane do całkowitych wartości właściwości. Backfill ponownie oblicza wszystkie wartości cechy, poszerzając każdy zakres na zewnątrz do najbliższych momentów, w których cecha generuje wartość. Cecha SlidingWindow generuje wartość co slide_duration, a cecha TumblingWindow generuje jedną co window_duration, przesuniętą o offset okna, jeśli go ustawisz. Na przykład dla funkcji z 1-godzinnym slide_duration, zakres od 1:30 do 2:30 w nocy zmienia się na 1:00 do 3:00. Nie musisz sam wyrównywać zakresów. Zakresy, które nakładają się po wyrównaniu, są łączone w jeden.
  • Wartości poza zakresem mogą się zmieniać. Backfill przepisuje każdą wartość cechy, której okno czasowe obejmuje ponownie przetworzone dane. Okno może kończyć się po end_time, więc wartości do jednego window_duration po end_time mogą się zmieniać. Na przykład dla funkcji z 7-dniowym window_duration, wartości do 7 dni po tym end_time mogą się zmienić.
  • Backfill kończy się na najnowszych zmaterializowanych wartościach. Backfill oblicza ponownie tylko historię, którą materializacja już zapisała. Jeśli zakres przekracza najnowsze zmaterializowane wartości, uzupełnienie kończy się na tym i pozostawia późniejszy zakres czasu dla zaplanowanej materializacji.
  • Nieustawione granice rozciągają się na dostępne dane. Jeśli pominiesz start_time, zakres zaczyna się od najwcześniejszego znacznika czasu w danych źródłowych. Jeśli pominiesz end_time, zakres rozszerza się do najnowszych zmaterializowanych wartości.

Zakresy elementów backfill_ranges i BackfillStatus po wyrównaniu. Backfill nie zawęża ich do najnowszych zmaterializowanych wartości, więc zgłoszony zakres może wykraczać poza wartości przeliczone przez backfill. Nie musisz uzupełniać wstecznie późniejszych wartości, ponieważ twoja zaplanowana materializacja oblicza je na podstawie bieżących danych źródłowych.

Tabele offline i online

Backfill aktualizuje offline tabelę Feature View i, jeśli Feature View jest również materializowany w magazynie online, aktualizuje również jej tabelę online. W przypadku widoku cech z tabelą offline i online backfill ponownie oblicza tabelę offline, a następnie ponownie publikuje na jej podstawie tabelę online. Nie można uzupełnić wstecznie tylko jednej z nich.

Tabela online zawiera najnowszą wartość dla każdego podmiotu. Backfill zmienia wartości online tylko wtedy, gdy zmienia najnowszą wartość danej encji.

Monitoruj lub anuluj backfill

backfill_features zwraca bez czekania na zakończenie backfillu. Aby czekać, przejdź wait=True lub wywołaj wait_for_backfill ze zwróconym statusem:

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill zwraca ostateczną BackfillStatus, gdy backfill się uda. Jeśli operacja backfill się nie powiedzie lub zostanie anulowana, pojawia się błąd OperationFailed, który opisuje przyczynę. Aby ograniczyć czas oczekiwania, przekaż timeout jako parametr timedelta. Jeśli zasypanie nie zostanie ukończone do tego czasu, wait_for_backfill zgłasza TimeoutError. Zatrzymanie oczekiwania nie anuluje wypełniania danych wstecznych.

Aby sprawdzić uzupełnienie bez oczekiwania lub z innego notesu bądź zadania, wywołaj get_backfill z nazwą operacji:

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

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

BackfillStatus ma następujące pola:

  • operation_name: Nazwa identyfikująca backfill.
  • state: Stan zasypu jako wartość BackfillState .
  • feature_full_names: Pełne nazwy Feature Views w backfillu.
  • backfill_ranges: Zakresy czasowe wyrównane jako BackfillRange wartości z ograniczeniami UTC.
  • error: Powód, dla którego backfill się nie powiódł. To pole jest ustawiane tylko wtedy, gdy state jest FAILED.

Stan backfill to jedna z następujących wartości:

State Description
PENDING Uzupełnienie danych zostało zaakceptowane i jeszcze nie zaczęło działać.
RUNNING Uzupełnianie danych wstecznych jest w toku.
SUCCEEDED Proces backfillu zakończył się i ponownie obliczył wartości cech w swoich zakresach.
FAILED Zasypywanie zatrzymało się z powodu błędu. Zobacz Odzyskiwanie po nieudanym backfillu.
CANCELLED Backfill został anulowany przed jego ukończeniem.

Jeśli nie masz nazwy operacji, znajdź najnowsze uzupełnienie danych dla zmaterializowanej cechy w polu latest_backfill_operation zwróconym przez list_materialized_features i przekaż je do get_backfill.

Aby anulować uzupełnianie danych, wywołaj cancel_backfill, podając jego stan:

fe.cancel_backfill(backfill=backfill)

Anulowanie backfill powoduje wysłanie żądania zatrzymania. Uzupełnienie, które jest bliskie końca, nadal może się powiodować, więc sprawdź jego ostateczny stan za pomocą get_backfill. Anulowanie już zakończonego uzupełniania danych nie ma żadnego efektu. Anulowane uzupełnienie może pozostawić niektóre wartości cech przeliczone, jak opisano w Odzyskiwanie po nieudanym uzupełnianiu.

Concurrency

Backfill jest uruchamiany równolegle do zaplanowanej materializacji. Uzupełnianie danych różnych Feature Views może również działać jednocześnie.

Tylko jeden backfill może działać dla widoku Feature View w danym momencie. Jeśli rozpoczniesz uzupełnianie dla Feature View, który ma już uzupełnianie w toku, żądanie kończy się błędem ALREADY_EXISTS. Poczekaj, aż poprzednie uzupełnianie danych się skończy, zanim zaczniesz kolejne.

Odzyskiwanie po nieudanym backfillu

Nieudany lub anulowany backfill może się zatrzymać przed zakończeniem. Każda wartość, którą backfill nadpisał przed zatrzymaniem, jest w pełni przeliczana. Wartości, do których nie dotarł, zachowują wcześniejsze wartości, więc niektóre Feature Views lub zakresy czasowe mogą nie być aktualizowane.

Aby odzyskać, zacznij od nowa to samo uzupełnianie danych. Jeśli przekazano request_id, przekaż nowy, ponieważ ponowienie z użyciem oryginalnego request_id zwraca nieudane uzupełnienie zamiast rozpoczynać nowe. Backfill można bezpiecznie powtarzać. Jeśli dane źródłowe się nie zmieniły, ponowne obliczenie zakresu, który już się powiódł, daje te same wartości.

Limitations

  • Tylko funkcje agregacji wsadowej, które wykorzystują DeltaTableSource i SlidingWindow lub TumblingWindow, można uzupełnić historycznie. Funkcje przesyłania strumieniowego, funkcje ColumnSelection, funkcje z RollingWindow lub SawtoothWindow, funkcje z oknem istnienia oraz funkcje z innymi źródłami, takie jak RequestSource, nie mogą być uzupełniane.
  • Feature Views, które generują wartości w różnych odstępach czasu lub z różnymi przesunięciami, nie mogą współdzielić jednego backfillu. Zacznij osobne uzupełnianie dla każdej grupy.
  • Backfill aktualizuje offline tabelę Feature View i, jeśli Feature View jest również materializowany w magazynie online, aktualizuje również jego tabelę online. Nie można uzupełnić tylko jednego z nich.
  • Backfill nie wypełnia zakresów czasowych po ostatnich zmaterializowanych wartościach. Twoje zaplanowane odświeżanie je wypełnia.
  • Ostatnia aktualizacja o