Vues de fonctionnalités de rétroremplissage

Le rétroremplissage recalcule les valeurs matérialisées de vos Feature Views sur les plages de temps que vous choisissez. Utilisez-le après avoir corrigé ou ajouté des données sources historiques, afin que les materializations hors ligne et en ligne reflètent les données mises à jour.

La matérialisation calcule les valeurs de feature récentes à chaque exécution et ne recalcule pas les valeurs déjà écrites. Un changement des données sources pour une plage de temps passée n’atteint pas les valeurs matérialisées tant que vous n’effectuez pas un backfill sur cette plage de temps. Utilisez backfill dans des situations telles que les suivantes :

  • Un problème de qualité des données en amont a affecté une plage de temps passée, et vous avez corrigé les lignes sources.
  • Les données sources d’une période passée sont arrivées après que la matérialisation les ait déjà traitées.

Un backfill est un travail ponctuel qui s’exécute parallèlement à votre materialization programmée. Cela ne change pas le calendrier de matérialisation. Voir Matérialiser les vues des fonctionnalités.

Requirements

  • databricks-feature-engineering 0.18.2 et plus. Pour d’autres exigences, voir Exigences.
  • Chaque Feature View est une fonctionnalité d’agrégation par lots qui utilise un DeltaTableSource et un SlidingWindow ou TumblingWindow. Les Lifetime windows ne sont pas prises en charge.
  • Chaque Feature View est matérialisée et a terminé au moins une exécution de matérialisation. Le backfill recalcule des valeurs déjà écrites par la matérialisation, donc il ne peut pas matérialiser une Feature View pour la première fois.
  • Vous commencez le remplissage avec le même utilisateur ou principal de service qui a matérialisé les Feature Views, depuis l’espace de travail où elles sont matérialisées.

Permissions

Le backfill s’exécute avec votre identité, et il lit et écrit les mêmes tables que votre materialization, donc il utilise les mêmes privilèges que votre materialization. Pour les descriptions complètes des privilèges du Catalogue Unity, voir la référence des privilèges du Catalogue Unity.

  • Vous devez avoir MANAGE sur chaque Feature View que vous rétroalimentez.
  • Pour vérifier une réexécution, il faut READ FEATURE sur chaque Feature View de la réexécution. Pour annuler un backfill, il vous faut MANAGE sur chaque vue de fonctionnalité du backfill.

Démarrer le rétroremplissage

Pour commencer un backfill, appelez backfill_features avec les Feature Views à backfiller et une ou plusieurs plages temporelles :

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:

Toutes les vues de caractéristiques d’un même appel doivent produire des valeurs aux mêmes moments. Ils doivent partager le même intervalle entre les valeurs (le slide_duration d’un SlidingWindow ou le window_duration d’un TumblingWindow) et le même offset. Sinon, l’appel échoue avec une erreur qui regroupe les Feature Views par intervalle, ce qui permet de lancer un backfill séparé pour chaque groupe.

Chaque BackfillRange possède un start_time, qui est inclusif, et un end_time, qui est exclusif. Les deux sont des valeurs Pythondatetime. A datetime sans fuseau horaire est lu comme UTC. Chaque start_time doit être antérieur à son end_time, et les plages d’un appel ne peuvent pas se chevaucher. Pour savoir comment backfill interprète chaque plage, voir Comment backfill applique les plages de temps.

L’exemple suivant remplit une semaine d’historique pour deux 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>

Avant de commencer le remblai, backfill_features vérifie ce qui suit. Si une vérification échoue, l’appel échoue avec une erreur qui nomme les Feature Views concernées.

  • Chaque Vue de Caractéristiques répond aux exigences, y compris une exécution de matérialisation terminée.
  • Vous avez matérialisé chaque Feature View.
  • Vous avez les privilèges nécessaires.

La méthode renvoie un BackfillStatus qui décrit le backfill. Il identifie la operation_name valeur de remplacement, dans le format operations/<operation-id>. Voir « Surveiller ou annuler un backfill ».

Pour que l’appel puisse être relancé sans risque, passez un UUID comme request_id. Une nouvelle tentative avec la même méthode request_id renvoie le backfill d’origine au lieu d’en démarrer un nouveau.

Pour attribuer le coût d’un backfill, passer tags, budget_policy_id, ou les deux. Ils ne s’appliquent qu’à ce remblai. Voir Coûts d’attributs avec tags et politiques d’utilisation serverless.

Comment le backfill applique les plages de temps

Chaque plage sélectionne les données sources à retraiter : les lignes source avec des horodatages à partir de start_time et avant end_time. Le remplissage s’applique à chaque plage comme suit :

  • Les plages sont alignées sur des valeurs entières de fonctionnalité. Le backfill recalcule toutes les valeurs de la fonctionnalité, élargissant ainsi chaque plage vers l’extérieur jusqu’aux moments les plus proches auxquels la fonctionnalité produit une valeur. Une SlidingWindow variable produit une valeur chaque slide_duration, et une TumblingWindow variable en produit une chaque window_duration, décalée par le/la offset de la fenêtre si vous en définissez une. Par exemple, pour une fonctionnalité avec un slide_duration d’une heure, une plage de 1h30 à 2h30 devient de 1h00 à 3h00. Vous n’avez pas besoin d’aligner les plages vous-même. Les plages qui se chevauchent après l’alignement sont combinées en une seule.
  • Les valeurs après la plage peuvent changer. Le backfill réécrit chaque valeur de caractéristique dont la fenêtre temporelle inclut les données retraitées. Une fenêtre peut se terminer après end_time, donc les valeurs pouvant aller jusqu’à un window_duration après end_time peuvent changer. Par exemple, pour une fonctionnalité avec une durée de 7 window_durationjours , les valeurs jusqu’à 7 jours après end_time peuvent changer.
  • Le rattrapage s’arrête aux valeurs matérialisées les plus récentes. Le backfill ne recalcule que l’historique déjà écrit par la matérialisation. Si une plage dépasse les valeurs matérialisées les plus récentes, le backfill s’arrête là et laisse la plage de temps plus tardive à votre matérialisation prévue.
  • Les bornes non définies prennent la valeur des données disponibles. Si vous omettez start_time, la plage commence à l’horodatage le plus ancien dans les données sources. Si vous omettez end_time, la plage s’étend aux valeurs matérialisées les plus récentes.

Les backfill_ranges d’un BackfillStatus sont vos plages après alignement. Le backfill ne les réduit pas aux valeurs matérialisées les plus récentes, donc une plage indiquée peut dépasser les valeurs recalculées par le backfill. Vous n’avez pas besoin de remplir rétroactivement les valeurs ultérieures, car votre matérialisation programmée les calcule à partir des données sources actuelles.

Tables hors ligne et en ligne

Le backfill met à jour la table hors ligne d’une Feature View et, si la Feature View est également matérialisée dans un magasin en ligne, sa table en ligne. Pour une Feature View avec les deux, le backfill recalcule la table hors ligne puis republie la table en ligne à partir de celle-ci. Tu ne peux en renseigner qu’un seul a posteriori.

Le tableau en ligne contient la valeur la plus récente pour chaque entité. Un backfill ne modifie les valeurs en ligne que lorsqu’il modifie la dernière valeur d’une entité.

Surveillez ou annulez un backfill

backfill_features revient sans attendre la fin du backfill. Pour attendre, ignorer wait=True ou appeler wait_for_backfill avec le statut retourné :

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill retourne la version finale BackfillStatus lorsque le backfill réussit. Si le backfill échoue ou est annulé, il génère OperationFailed une erreur qui décrit la raison. Pour limiter la durée d’attente, passez timeout en tant que timedelta. Si le backfill n’est pas terminé d’ici là, wait_for_backfill déclenche un TimeoutError. Arrêter l’attente n’annule pas le rattrapage.

Pour vérifier un backfill sans attendre, ou depuis un autre notebook ou un autre job, appelez get_backfill avec le nom de l’opération :

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

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

Un BackfillStatus possède les champs suivants :

  • operation_name: Le nom qui identifie le remblai.
  • state: L’état du remblai, sous forme de valeur BackfillState.
  • feature_full_names: Les noms complets des Feature Views dans le backfill.
  • backfill_ranges: Les plages de temps alignées, représentées sous forme de valeurs BackfillRange délimitées en UTC.
  • error: La raison pour laquelle le backfill a échoué. Ce champ n’est défini que lorsque state est FAILED.

L’état de backfill est l’une des valeurs suivantes :

State Description
PENDING Le backfill a été accepté et n’a pas encore démarré.
RUNNING Le backfill est en cours.
SUCCEEDED Le backfill s'est terminé et a recalculé les valeurs de feature dans les plages concernées.
FAILED Le rétroremplissage s’est arrêté à cause d’une erreur. Voir Récupérer après un backfill ayant échoué.
CANCELLED Le rétroremplissage a été annulé avant sa fin.

Si vous n’avez pas le nom de l’opération, trouvez le backfill le plus récent d’une feature matérialisée dans le champ latest_backfill_operation retourné par list_materialized_features, et passez-le à get_backfill.

Pour annuler un backfill, appelez cancel_backfill avec son statut :

fe.cancel_backfill(backfill=backfill)

L’annulation d’une requête de backfill demande son arrêt. Un backfill qui est sur le point de se terminer peut toujours réussir, donc vérifiez son état final avec get_backfill. Annuler un backfill déjà terminé n’a aucun effet. Un backfill annulé peut laisser certaines valeurs de caractéristiques recalculées, comme décrit dans Récupérer après un backfill ayant échoué.

Concurrency

Un backfill s’exécute en parallèle de votre matérialisation planifiée. Des backfills de différentes Feature Views peuvent également s’exécuter simultanément.

Un seul backfill peut s’exécuter pour une Feature View à la fois. Si vous lancez un backfill pour une Feature View qui a déjà un backfill en cours, la requête échoue avec une ALREADY_EXISTS erreur. Attends que le backfill précédent soit terminé avant de commencer le suivant.

Récupérer après l’échec d’un backfill

Un backfill défaillant ou annulé peut s’arrêter avant d’être terminé. Chaque valeur que le backfill a réécrite avant de s’arrêter est entièrement recalculée. Les valeurs non atteintes conservent leurs valeurs antérieures, donc certaines Feature Views ou plages temporelles peuvent ne pas être mises à jour.

Pour récupérer, recommencez le même remplissage. Si vous avez fourni un request_id, fournissez-en un nouveau, car une nouvelle tentative avec l’original request_id retourne le backfill ayant échoué au lieu d’en commencer un nouveau. Le backfill peut être répété sans risque. Si les données sources n’ont pas changé, recalculer une plage dont le calcul a déjà réussi produit les mêmes valeurs.

Limitations

  • Seules les fonctionnalités d’agrégation par lots qui utilisent un DeltaTableSource et un SlidingWindow ou TumblingWindow peuvent faire l’objet d’un remplissage rétroactif. Les fonctionnalités de streaming, les fonctionnalités ColumnSelection, les fonctionnalités avec un RollingWindow ou SawtoothWindow, les fonctionnalités avec une fenêtre d’attribution à vie, et les fonctionnalités avec d’autres sources, telles que RequestSource, ne peuvent pas être comblées.
  • Les Feature Views qui produisent des valeurs à différents intervalles ou décalages ne peuvent pas partager un seul backfill. Commencez un backfill séparé pour chaque groupe.
  • Backfill met à jour la table hors ligne d’une Feature View et, si la Feature View est également matérialisée dans un magasin en ligne, sa table en ligne. Tu ne peux pas en renseigner qu’un seul a posteriori.
  • Le backfill ne couvre pas les plages temporelles après les dernières valeurs matérialisées. La vue matérialisée planifiée les remplit.
  • Dernière mise à jour :