Rellenar vistas de características

Backfill recalcula los valores materializados de tus Feature Views a lo largo de los intervalos de tiempo que elijas. Úsalo después de corregir o añadir datos fuente históricos, para que las materializaciones offline y online reflejen los datos actualizados.

La materialización calcula los valores recientes de las características en cada ejecución y no vuelve a revisar los valores que ya ha escrito. Un cambio en los datos de origen de un intervalo de tiempo pasado no se refleja en los valores materializados hasta que recalculas ese intervalo. Utiliza backfill en escenarios como los siguientes:

• Un problema de calidad de datos aguas arriba afectó a un intervalo de tiempo anterior, y corregiste las filas fuente.
• Los datos fuente de un intervalo temporal anterior llegaron después de que la materialización ya los hubiera procesado.

Un rellenado retroactivo es un trabajo puntual que se desarrolla junto con tu materialización programada. No cambia el calendario de materialización. Consulte Materializar vistas de atributos.

Requirements

• databricks-feature-engineering 0.18.2 y superiores. Para otros requisitos, véase Requisitos.
• Cada vista de características es una característica de agregación por lotes que utiliza una DeltaTableSource y una SlidingWindow o TumblingWindow. No se admiten Lifetime windows.
• Cada Vista de Característica se materializa y ha completado al menos una ejecución de materialización. El backfill recalcula valores que la materialización ya ha escrito, por lo que no puede materializar una Feature View por primera vez.
• Se inicia el backfill como el mismo usuario o entidad de servicio que materializó las Feature Views, desde el espacio de trabajo donde se materializaron.

Permissions

El backfill se ejecuta con tu identidad, y lee y escribe las mismas tablas que tu materialización, por lo que usa los mismos privilegios que tu materialización. Para las descripciones completas de privilegios del Catálogo de Unity, consulte la referencia de privilegios del Catálogo de Unity.

• Debes tener MANAGE en cada Feature View que reproceses.
• Para comprobar un backfill, necesitas READ FEATURE en cada Feature View del backfill. Para cancelar un backfill, necesitas estar MANAGE en todas las vistas de características del backfill.

Iniciar backfill

Para iniciar un relleno, llama a backfill_features con las Feature Views que se deben rellenar y uno o más intervalos temporales:

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:

Todas las vistas de características en una llamada deben producir valores en los mismos momentos. Deben compartir el mismo intervalo entre los valores (el slide_duration de un SlidingWindow o el window_duration de un TumblingWindow) y el mismo offset. De lo contrario, la llamada falla con un error que agrupa las Feature Views por intervalo, de modo que puedes iniciar un backfill separado para cada grupo.

Cada BackfillRange tiene un start_time, que es inclusivo, y un end_time, que es exclusivo. Ambos son valores de Pythondatetime. A datetime sin huso horario se lee como UTC. Cada start_time debe ser anterior a su end_time, y los rangos en una misma llamada no pueden solaparse. Para ver cómo el relleno interpreta cada rango, véase Cómo aplica el relleno los intervalos de tiempo.

El siguiente ejemplo rellena una semana de historia para dos 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>

Antes de que empiece el relleno, backfill_features comprueba lo siguiente. Si una comprobación falla, la llamada falla con un error que nombra las Feature Views afectadas.

• Cada Vista de Características cumple con los requisitos, incluyendo una ejecución de materialización completada.
• Materializaste cada Feature View.
• Tienes los privilegios necesarios.

El método devuelve un BackfillStatus que describe el backfill. Su operation_name identifica el relleno, en el formato operations/<operation-id>. Ver Monitorizar o cancelar un backfill.

Para que la llamada sea segura para intentarlo de nuevo, pasa un UUID como request_id. Un reintento con la misma request_id devuelve el backfill original en lugar de empezar uno nuevo.

Para atribuir el coste de un backfill, pasar tags, budget_policy_id o ambos. Solo aplican a ese relleno. Consulta Costes de atributos con etiquetas y políticas de uso sin servidor.

Cómo se aplica el backfill a los intervalos de tiempo

Cada rango selecciona los datos fuente a reprocesar: las filas fuente con marcas de tiempo en o después de start_time y antes de end_time. El relleno aplica cada rango de la siguiente manera:

• Los rangos están alineados a valores enteros de la característica. Backfill recalcula los valores completos de las características, por lo que amplía cada rango hacia afuera hasta los momentos más cercanos en los que la característica produce un valor. Una SlidingWindow característica produce un valor cada slide_duration, y una TumblingWindow característica produce uno cada window_duration, desplazado por el offset de la ventana si se establece uno. Por ejemplo, para una función con una duración de 1 hora slide_duration, un rango de 1:30 AM a 2:30 AM pasa a ser de 1:00 AM a 3:00 AM. No necesitas alinear los rangos tú mismo. Los rangos que se solapan tras la alineación se combinan en uno solo.
• Los valores fuera del intervalo pueden cambiar. El backfill reescribe cada valor de característica cuya ventana temporal incluye datos reprocesados. Una ventana puede terminar después de end_time, por lo que los valores hasta un window_duration después de end_time pueden cambiar. Por ejemplo, para una característica con una ventana de 7 días window_duration, los valores hasta 7 días después de end_time pueden cambiar.
• El relleno se detiene en los valores materializados más recientes. Backfill solo recalcula el historial que la materialización ya ha escrito. Si un rango se extiende más allá de los valores materializados más recientes, el relleno retrospectivo se detiene ahí y deja el rango de tiempo posterior a tu materialización programada.
• Los límites no definidos se extienden a los datos disponibles. Si omites start_time, el rango comienza en la marca temporal más temprana de los datos fuente. Si omites end_time, el rango se extiende hasta los valores materializados más recientes.

Los backfill_ranges de un BackfillStatus son tus rangos después de la alineación. El backfill no los reduce a los valores materializados más recientes, por lo que un rango reportado puede extenderse más allá de los valores que el backfill recalculó. No necesitas rellenar los valores posteriores, porque tu materialización programada los calcula a partir de los datos fuente actuales.

Tablas offline y online

Backfill actualiza la tabla offline de una Feature View y, si la Feature View también se materializa en una tienda online, su tabla online. Para una Feature View con ambos, el backfill recalcula la tabla offline y luego republica la tabla online desde ella. No puedes completar retroactivamente solo uno de ellos.

La tabla online contiene el valor más reciente para cada entidad. Un backfill cambia los valores online solo cuando cambia el valor más reciente de una entidad.

Monitorizar o cancelar un backfill

backfill_features devuelve sin esperar a que termine el relleno. Para esperar, pasar wait=Trueo llamar wait_for_backfill con el estado devuelto:

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill devuelve el BackfillStatus final cuando el retrorelleno tiene éxito. Si el relleno falla o se cancela, genera un OperationFailed error que describe la razón. Para limitar la espera, pasa un timeout como un timedelta. Si el relleno no ha terminado para entonces, wait_for_backfill genera un TimeoutError. Detener la espera no cancela el backfill.

Para comprobar un backfill sin esperar, o desde otro cuaderno o trabajo, llama get_backfill con el nombre de la operación:

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

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

Un BackfillStatus tiene los siguientes campos:

• operation_name: El nombre que identifica el relleno.
• state: El estado del relleno, como valor BackfillState.
• feature_full_names: Los nombres completos de las Feature Views en el rellenado retrospectivo.
• backfill_ranges: Los rangos de tiempo alineados, como valores BackfillRange con límites UTC.
• error: La razón por la que falló el backfill. Este campo se establece solo cuando state es FAILED.

El estado de backfill es uno de los siguientes valores:

Si no tienes el nombre de la operación, encuentra el backfill más reciente de una feature materializada en el campo latest_backfill_operation devuelto por list_materialized_features, y pásalo a get_backfill.

Para cancelar un backfill, llama a cancel_backfill con el estado:

fe.cancel_backfill(backfill=backfill)

Cancelar un backfill solicita que se detenga. Un backfill que está a punto de terminar aún puede tener éxito, así que comprueba su estado final con get_backfill. Cancelar un backfill que ya ha terminado no tiene ningún efecto. Un relleno cancelado puede hacer que algunos valores de características se recalculen, como se describe en Recuperar de un relleno fallido.

Concurrency

Un backfill se ejecuta en paralelo con tu materialización programada. También se pueden ejecutar backfills de diferentes Feature Views al mismo tiempo.

Solo un backfill puede ejecutarse para una Feature View a la vez. Si inicias un backfill para una Feature View que ya tiene un backfill en curso, la solicitud falla con un error ALREADY_EXISTS. Espera a que termine el relleno anterior antes de empezar el siguiente.

Recuperar de un backfill fallido

Un backfill fallido o cancelado puede detenerse antes de terminar. Cada valor que el backfill reescribió antes de detenerse se recalcula completamente. Los valores a los que no llegó mantienen sus valores anteriores, por lo que algunas Feature Views o rangos de tiempo pueden no actualizarse.

Para recuperar, vuelve a empezar el mismo backfill. Si has proporcionado un request_id, proporciona uno nuevo, porque un reintento con el request_id original devuelve el backfill fallido en lugar de empezar uno nuevo. El relleno se puede repetir con seguridad. Si los datos fuente no han cambiado, recalcular un rango que ya se calculó correctamente produce los mismos valores.

Limitations

• Solo las características de agregación por lotes que usan a DeltaTableSource y a SlidingWindow o TumblingWindow pueden ser rellenadas. Las funciones de streaming, las funciones ColumnSelection, las funciones con un SawtoothWindow o RollingWindow, las funciones con una ventana de duración definida y las funciones con otras fuentes, como RequestSource, no se pueden rellenar retrospectivamente.
• Las vistas de características que producen valores en diferentes intervalos o desplazamientos no pueden compartir un solo backfill. Inicia un backfill independiente para cada grupo.
• Backfill actualiza la tabla offline de una vista de características y, si la vista de características también se materializa en una tienda online, su tabla online. No puedes completar de forma retroactiva solo uno de ellos.
• El backfill no rellena los rangos de tiempo posteriores a los valores materializados más recientes. Tu actualización programada los llena.