Vues des fonctionnalités de renvoi

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

La matérialisation calcule les valeurs de fonctionnalités 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 renvoi est un travail ponctuel qui s’exécute parallèlement à votre matérialisation 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 renvoi avec le même utilisateur ou principal de service qui a matérialisé les vues de fonctionnalités, depuis l’espace de travail où elles sont matérialisées.

Permissions

Le renvoi s’exécute avec votre identité, et il lit et écrit les mêmes tables que votre matérialisation, donc il utilise les mêmes privilèges que votre matérialisation. 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 vue de fonctionnalité que vous renvoyez.
• Pour vérifier un renvoi, il faut READ FEATURE sur chaque vue de fonctionnalité du renvoi. Pour annuler un renvoi, il faut MANAGE sur chaque vue de fonctionnalité du renvoi.

Démarrer un renvoi

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. Un 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 vues de fonctionnalités :

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 renvoi, 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 operation_name identifie le renvoi dans le format operations/<operation-id>. Voir Surveiller ou annuler un renvoi.

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 renvoi 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 renvoi. 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 renvoi 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 fonctionnalité SlidingWindow produit une valeur chaque slide_duration, et une fonctionnalité TumblingWindow 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 renvoi 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. Vous ne pouvez pas renvoyer une seule de ces données.

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

Surveiller ou annuler un renvoi

backfill_features revient sans attendre la fin du renvoi pour terminer. 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 renvoi.

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 renvoi, 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 :

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 renvoi 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 renvoi 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 vues de fonctionnalités ou plages temporelles peuvent ne pas être mises à jour.

Pour récupérer, recommencez le même renvoi. Si vous avez fourni un request_id, fournissez-en un nouveau, car une nouvelle tentative avec l’original request_id retourne le renvoi 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 renvoyées.
• Les Feature Views qui produisent des valeurs à différents intervalles ou décalages ne peuvent pas partager un seul backfill. Commencez un renvoi 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.