Remplir les vues de fonctionnalités

Le remplissage (backfill) recalcule les valeurs matérialisées de vos vues de fonctionnalités sur des périodes que vous choisissez. Utilisez cette option 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 compute les valeurs récentes des variables utilisables par les modèles à chaque exécution et ne revient pas sur les valeurs qu’elle a déjà écrites. Une modification des données sources pour une période passée ne modifie pas les valeurs matérialisées tant que vous n'effectuez pas un remplissage pour cette période. Utilisez le remplissage dans les scénarios suivants :

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

Un remplissage est un job ponctuel qui s'exécute parallèlement à votre matérialisation planifiée. Cela ne modifie pas le calendrier de matérialisation. Consultez Matérialiser les vues de caractéristiques.

Conditions requises

• databricks-feature-engineering 0.18.2 et supérieur. Pour les autres exigences, consultez la rubrique Exigences.
• Chaque vue de fonctionnalité est une fonctionnalité d'agrégation batch qui utilise un DeltaTableSource et un SlidingWindow ou TumblingWindow. Les fenêtres de durée de vie ne sont pas prises en charge.
• Chaque vue de fonctionnalité est matérialisée et a terminé au moins une exécution de matérialisation. Le remplissage recalcule les valeurs que la matérialisation a déjà écrites, il ne peut donc pas matérialiser une vue de fonctionnalité pour la première fois.
• Vous start le backfill en tant qu'utilisateur ou Service Principal qui a matérialisé les vues de caractéristiques, depuis le Workspace où elles sont matérialisées.

Autorisations

Le remplissage s'exécute en tant qu'utilisateur, lit et écrit les mêmes tables que votre matérialisation, et utilise donc les mêmes privilèges que votre matérialisation. Pour obtenir la description complète des privilèges Unity Catalog, consultez la référence des privilèges Unity Catalog.

• Vous devez disposer de MANAGE sur chaque vue de caractéristiques que vous remplissez.
• Pour vérifier un remplissage, vous devez avoir READ FEATURE sur chaque Feature View dans le remplissage. Pour annuler un remplissage, vous devez avoir MANAGE sur chaque Feature View dans le remplissage.

start un remplissage

Pour start un remplissage, appelez backfill_features avec les vues de fonctionnalités à remplir et une ou plusieurs plages horaires :

Python

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 fonctionnalités dans un seul 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 la même offset. Sinon, l'appel échoue avec une erreur qui regroupe les vues de fonctionnalités par intervalle, afin que vous puissiez start un remplissage séparé pour chaque groupe.

Chaque BackfillRange a un start_time, qui est inclusif, et un end_time, qui est exclusif. Les deux sont des valeurs Python datetime. Un datetime sans fuseau horaire est lu comme étant en 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 le remplissage interprète chaque plage, consultez Comment le remplissage applique les plages de temps.

L’exemple suivant remplit une semaine d’historique pour deux vues de fonctionnalités :

Python

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 le start du remplissage, backfill_features vérifie les éléments suivants. Si une vérification échoue, l'appel échoue avec une erreur qui nomme les vues de fonctionnalités concernées.

• Chaque vue de caractéristiques répond aux exigences, notamment une exécution de matérialisation terminée.
• Vous avez matérialisé chaque vue de fonctionnalités.
• Vous disposez des privilèges requis.

La méthode renvoie un BackfillStatus qui décrit le remplissage. Son operation_name identifie le remplissage, au format operations/<operation-id>. Voir Surveiller ou annuler un remplissage.

Pour rendre l'appel sûr en cas de nouvelle tentative, passez un UUID comme request_id. Une nouvelle tentative avec le même request_id renvoie le remplissage d'origine au lieu d'en commencer un nouveau.

Pour attribuer le coût d'un remplissage, passez tags, budget_policy_id ou les deux. Ils s'appliquent uniquement à ce remplissage. Voir Attribuer des coûts avec des tags et des politiques d’utilisation serverless.

Comment le remplissage s'applique aux plages de temps

Chaque plage sélectionne les données sources à retraiter : les lignes sources avec des Timestamp supérieurs ou égaux à start_time et inférieurs à end_time. Le remplissage applique chaque plage comme suit :

• Les plages sont alignées sur les valeurs de fonctionnalités entières. Le remplissage (backfill) recalcule des valeurs de fonctionnalités entières, ce qui élargit chaque plage vers l'extérieur jusqu'aux moments les plus proches où la fonctionnalité produit une valeur. Une fonctionnalité SlidingWindow produit une valeur tous les slide_duration, et une fonctionnalité TumblingWindow en produit une tous les window_duration, décalée par le offset de la fenêtre si vous en définissez un. Par exemple, pour une fonctionnalité avec un slide_duration d'une heure, une plage de 1 h 30 à 2 h 30 devient 1 h 00 à 3 h 00. Vous n'avez pas besoin d'aligner vous-même les plages. Les plages qui se chevauchent après alignement sont combinées en une seule.
• Les valeurs après la plage peuvent changer. Le remplissage réécrit chaque valeur de fonctionnalité dont la fenêtre temporelle inclut des données traitées. Une fenêtre peut se terminer après end_time, de sorte que les valeurs jusqu’à un window_duration après end_time peuvent changer. Par exemple, pour une fonctionnalité avec un window_duration de 7 jours, les valeurs jusqu’à 7 jours après end_time peuvent changer.
• Le remplissage s’arrête aux valeurs matérialisées les plus récentes. Le remplissage recalcule uniquement l’historique que la matérialisation a déjà écrit. Si une plage s’étend au-delà des valeurs matérialisées les plus récentes, le remplissage s’arrête là et laisse la plage horaire ultérieure à votre matérialisation programmée.
• Les limites non définies s'étendent aux données disponibles. Si vous omettez start_time, la plage start au premier Timestamp des données source. Si vous omettez end_time, la plage s’étend aux valeurs matérialisées les plus récentes.

La backfill_ranges d'un BackfillStatus correspond à vos plages après alignement. Le remplissage ne les réduit pas aux valeurs matérialisées les plus récentes, de sorte qu'une plage signalée peut s'étendre au-delà des valeurs que le remplissage a recalculées. Il n'est pas nécessaire de remplir les valeurs ultérieures, car votre matérialisation planifiée les compute à partir des données sources actuelles.

Tables hors ligne et en ligne

Le remplissage met à jour la table hors ligne d'une vue de fonctionnalités et, si la vue de fonctionnalités est également matérialisée dans un magasin en ligne, sa table en ligne. Pour une vue de fonctionnalités comprenant les deux, le remplissage recalcule la table hors ligne, puis republie la table en ligne à partir de celle-ci. Vous ne pouvez pas remplir un seul d'entre eux.

La table en ligne contient la dernière valeur pour chaque entité. Un remplissage modifie les valeurs en ligne uniquement lorsqu’il modifie la dernière valeur d’une entité.

Surveiller ou annuler un remplissage

backfill_features retourne sans attendre la fin du remplissage. Pour attendre, passez wait=True ou appelez wait_for_backfill avec le statut retourné :

Python

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill retourne le BackfillStatus final quand le remplissage réussit. Si le remplissage échoue ou est annulé, il soulève une erreur OperationFailed qui décrit la raison. Pour limiter la durée d'attente, passez un timeout en tant que timedelta. Si le remplissage n'est pas terminé d'ici là, wait_for_backfill soulève une TimeoutError. Arrêter l'attente ne cancel pas le remplissage.

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

Python

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 remplissage.
• state: L’état du remplissage, sous la forme d’une valeur BackfillState.
• feature_full_names: Les noms complets des vues de fonctionnalités dans le remplissage.
• backfill_ranges: Les intervalles de temps alignés, sous forme de valeurs BackfillRange avec des limites UTC.
• error: La raison pour laquelle le remplissage a échoué. Ce champ n'est défini que lorsque state est FAILED.

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

État	Description
PENDING	Le remplissage a été accepté et n'a pas encore start.
RUNNING	Le remplissage est en cours d'exécution.
SUCCEEDED	Le remplissage est terminé et a recalculé les valeurs de la fonctionnalité dans ses plages.
FAILED	Le remplissage s’est arrêté à cause d’une erreur. Voir Récupérer à partir d'un remplissage échoué.
CANCELLED	Le remplissage a été annulé avant d'être terminé.

État	Description
PENDING	Le remplissage a été accepté et n'a pas encore start.
RUNNING	Le remplissage est en cours d'exécution.
SUCCEEDED	Le remplissage est terminé et a recalculé les valeurs de la fonctionnalité dans ses plages.
FAILED	Le remplissage s’est arrêté à cause d’une erreur. Voir Récupérer à partir d'un remplissage échoué.
CANCELLED	Le remplissage a été annulé avant d'être terminé.

Si vous ne connaissez pas le nom de l'opération, recherchez le remplissage le plus récent d'une fonctionnalité matérialisée dans le champ latest_backfill_operation retourné par list_materialized_features, et transmettez-le à get_backfill.

Pour annuler un remplissage, appelez cancel_backfill avec son statut :

Python

fe.cancel_backfill(backfill=backfill)

L'annulation d'un remplissage demande son arrêt. Un remplissage sur le point de se terminer peut encore réussir. Vérifiez son état final avec get_backfill. L'annulation d'un remplissage déjà terminé n'a aucun effet. Un remplissage annulé peut laisser certaines valeurs de caractéristiques recalculées, comme décrit dans Récupérer à partir d’un remplissage échoué.

Simultanéité

Un remplissage s'exécute avec votre matérialisation planifiée. Les remplissages de différentes vues de fonctionnalités peuvent également s'exécuter en même temps.

Un seul remplissage peut être exécuté pour une vue de fonctionnalités à la fois. Si vous start un remplissage pour une vue de fonctionnalités qui dispose déjà d’un remplissage en cours, la demande échoue avec une erreur ALREADY_EXISTS. Attendez que le remplissage précédent soit terminé avant de démarrer le suivant.

Récupération après un échec de remplissage

Un remplissage échoué ou annulé peut s'arrêter avant de se terminer. Chaque valeur que le remplissage a réécrite avant de s'arrêter est entièrement recalculée. Les valeurs qu'il n'a pas atteintes conservent leurs valeurs antérieures, de sorte que certaines vues de caractéristiques ou plages de temps peuvent ne pas être mises à jour.

Pour récupérer, start le même remplissage. Si vous avez transmis un request_id, transmettez-en un nouveau, car une nouvelle tentative avec le request_id original renvoie le remplissage ayant échoué au lieu d’en lancer un nouveau. Le remplissage peut être répété en toute sécurité. Si les données sources n’ont pas changé, le recalcul d’une plage qui a déjà réussi produira les mêmes valeurs.

Limites

• Seules les fonctionnalités d'agrégation batch qui utilisent une DeltaTableSource et une SlidingWindow ou TumblingWindow peuvent être remplies. Les fonctionnalités de streaming, les fonctionnalités ColumnSelection, les fonctionnalités avec un RollingWindow ou SawtoothWindow, les fonctionnalités avec une fenêtre de durée de vie et les fonctionnalités avec d'autres sources, telles que RequestSource, ne peuvent pas être remplies.
• Les vues de fonctionnalités qui produisent des valeurs à différents intervalles ou décalages ne peuvent pas partager un seul remplissage. start un remplissage distinct pour chaque groupe.
• Le remplissage met à jour la table hors ligne d’une vue de fonctionnalités et, si la vue de fonctionnalités est également matérialisée dans un magasin en ligne, sa table en ligne. Vous ne pouvez pas remplir un seul d'entre eux.
• Le remplissage ne remplit pas les plages de temps après les valeurs matérialisées les plus récentes. Votre matérialisation planifiée les remplit.