Preencher Views de Recurso retroativamente

O preenchimento retroativo recalcula os valores materializados das suas Visualizações de Recursos ao longo dos intervalos de tempo que você escolher. Use-o após corrigir ou adicionar dados de origem históricos para que as materializações offline e online reflitam os dados atualizados.

A materialização computa os valores recentes dos recursos em cada execução e não revisita os valores que já foram escritos. Uma alteração nos dados de origem para um intervalo de tempo passado não chega aos valores materializados até que você preencha esse intervalo de tempo. Use o preenchimento retroativo em cenários como os seguintes:

• Um problema de qualidade de dados upstream afetou um intervalo de tempo passado e você corrigiu as linhas de origem.
• Os dados de origem para um intervalo de tempo passado chegaram depois que a materialização já os processou.

Um backfill é um Job único que é uma execução juntamente com a materialização agendada. Não altera programar de materialização. Consulte Materializar view de Recurso.

Requisitos

• databricks-feature-engineering 0.18.2 e acima. Para outros requisitos, consulte Requisitos.
• Cada recurso view é um recurso de agregação em lotes que usa um DeltaTableSource e um SlidingWindow ou TumblingWindow. Janelas de duração não são aceitas.
• Cada View de Recurso é materializada e completou pelo menos uma execução de materialização. O preenchimento retroativo recalcula os valores que a materialização já escreveu, portanto, ela não pode materializar uma View de Recurso pela primeira vez.
• Você começa o preenchimento retroativo como o mesmo usuário ou Service Principal que materializou as views de recursos, a partir do Workspace onde elas estão materializadas.

Permissões

O backfill está em execução como você, e ele lê e grava as mesmas tabelas da sua materialização, por isso usa os mesmos privilégios que sua materialização. Para obter descrições completas dos privilégios do Unity Catalog, consulte referência de privilégios do Unity Catalog.

• Você deve ter MANAGE em cada View de recurso que você preencher retroativamente.
• Para verificar um preenchimento retroativo, você precisa de READ FEATURE em cada recurso view no preenchimento retroativo. Para cancelar um preenchimento retroativo, você precisa de MANAGE em cada recurso view no preenchimento retroativo.

começar preenchimento retroativo

Para começar um preenchimento retroativo, chame backfill_features com as views de recursos para preencher retroativamente e um ou mais intervalos de tempo:

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:

Todas as visualizações de recursos em uma chamada devem produzir valores nos mesmos horários. Eles devem compartilhar o mesmo intervalo entre os valores (o slide_duration de uma SlidingWindow ou o window_duration de uma TumblingWindow) e o mesmo offset. Caso contrário, a chamada falhará com um erro que agrupa as recurso views por intervalo, para que você possa começar um preenchimento retroativo separado para cada grupo.

Cada BackfillRange tem um start_time, que é inclusivo, e um end_time, que é exclusivo. Ambos são valores datetime do Python. Um datetime sem um fuso horário é lido como UTC. Cada start_time deve ser anterior ao seu end_time, e os intervalos em uma chamada não podem se sobrepor. Para saber como o preenchimento retroativo interpreta cada intervalo, consulte Como o preenchimento retroativo aplica intervalos de tempo.

O exemplo a seguir preenche uma semana de história para duas views de recurso:

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>

Antes de começar o preenchimento retroativo, backfill_features verifica o seguinte. Se uma verificação falhar, a chamada falhará com um erro que nomeia as View de recurso afetadas.

• Cada View de Recurso cumpre os requisitos, incluindo uma execução de materialização concluída.
• Você materializou cada view de recurso.
• Você tem os privilégios necessários.

O método retorna um BackfillStatus que descreve o preenchimento retroativo. Seu operation_name identifica o preenchimento retroativo, no formato operations/<operation-id>. Consulte Monitorar ou cancelar um preenchimento retroativo.

Para tornar a chamada segura para tentar novamente, transmita um UUID como request_id. Uma nova tentativa com o mesmo request_id retorna o preenchimento retroativo original em vez de iniciar um novo.

Para atribuir o custo de um preenchimento retroativo, passe tags, budget_policy_id ou ambos. Eles se aplicam apenas a esse preenchimento retroativo. Consulte Atribuir custos com tags e políticas de uso serverless.

Como o preenchimento retroativo aplica intervalos de tempo

Cada intervalo seleciona os dados de origem a reprocessar: as linhas de origem com Timestamp iguais ou posteriores a start_time e anteriores a end_time. O preenchimento retroativo aplica cada intervalo da seguinte forma:

• Os intervalos estão alinhados aos valores de recurso inteiros. O preenchimento retroativo recalcula valores de recurso inteiros, portanto, ele expande cada intervalo para fora até os momentos mais próximos em que o recurso produz um valor. Um recurso SlidingWindow produz um valor a cada slide_duration, e um recurso TumblingWindow produz um a cada window_duration, deslocado pelo offset da janela se você definir um. Por exemplo, para um recurso com um slide_duration de 1 hora, um intervalo de 01:30 às 02:30 torna-se de 01:00 às 03:00. Você não precisa alinhar os intervalos sozinho. Os intervalos que se sobrepõem após o alinhamento são combinados em um só.
• Os valores após o intervalo podem mudar. O preenchimento retroativo reescreve cada valor de recurso cuja janela de tempo inclui dados reprocessados. Uma janela pode terminar após end_time, portanto, os valores de até um window_duration após end_time podem mudar. Por exemplo, para um recurso com um window_duration de 7 dias, os valores de até 7 dias após end_time podem mudar.
• O preenchimento retroativo para nos valores materializados mais recentes. O preenchimento retroativo recomputa apenas a história que a materialização já escreveu. Se um intervalo ultrapassar os valores materializados mais recentes, o preenchimento retroativo será interrompido e deixará o intervalo de tempo posterior para a materialização agendada.
• Os limites não definidos se estendem aos dados disponíveis. Se você omitir start_time, o intervalo começará no timestamp mais antigo nos dados de origem. Se você omitir end_time, o intervalo se estenderá aos valores materializados mais recentes.

O backfill_ranges de um BackfillStatus são seus intervalos após o alinhamento. O preenchimento retroativo não os restringe aos valores materializados mais recentes, portanto, um intervalo relatado pode se estender além dos valores que o preenchimento retroativo recalculou. Você não precisa fazer o preenchimento retroativo dos valores posteriores, porque sua materialização agendada computes a partir dos dados de origem atuais.

Tabelas offline e online

O backfill atualiza a tabela offline de uma recurso view e, se a recurso view também estiver materializada para um armazenamento online, sua tabela online. Para um recurso view com ambos, o backfill recalcula a tabela offline e então republica a tabela online a partir dela. Você não pode fazer o backfill de apenas um deles.

A tabela online mantém o valor mais recente para cada entidade. Um preenchimento retroativo altera os valores online apenas quando altera o valor mais recente de uma entidade.

Monitorar ou cancelar um backfill

backfill_features retorna sem esperar que o preenchimento retroativo seja concluído. Para esperar, transmita wait=True ou chame wait_for_backfill com o status retornado:

Python

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill retorna o BackfillStatus final quando o preenchimento retroativo é bem-sucedido. Se o preenchimento retroativo falhar ou for cancelado, ele gera um erro OperationFailed que descreve o motivo. Para limitar quanto tempo ele aguarda, passe um timeout como um timedelta. Se o preenchimento retroativo não tiver terminado até então, wait_for_backfill gerará um TimeoutError. Parar a espera não cancela o preenchimento retroativo.

Para verificar um preenchimento retroativo sem esperar, ou de outro notebook ou job, chame get_backfill com o nome da operação:

Python

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

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

A BackfillStatus tem os seguintes campos:

• operation_name: O nome que identifica o preenchimento retroativo.
• state: O estado do preenchimento retroativo, como um valor BackfillState.
• feature_full_names: Os nomes completos das view de recursos no preenchimento retroativo.
• backfill_ranges: Os intervalos de tempo alinhados, como valores BackfillRange com limites UTC.
• error: O motivo pelo qual o preenchimento retroativo falhou. Este campo é definido apenas quando state é FAILED.

O estado de preenchimento retroativo é um dos seguintes valores:

Status	Descrição
PENDING	O preenchimento retroativo foi aceito e ainda não começou a ser executado.
RUNNING	O preenchimento retroativo está sendo executado.
SUCCEEDED	O preenchimento retroativo foi concluído e recalculou os valores de recursos em seus intervalos.
FAILED	O preenchimento retroativo parou devido a um erro. Consulte Recuperar de um preenchimento retroativo falho.
CANCELLED	O preenchimento retroativo foi cancelado antes de terminar.

Status	Descrição
PENDING	O preenchimento retroativo foi aceito e ainda não começou a ser executado.
RUNNING	O preenchimento retroativo está sendo executado.
SUCCEEDED	O preenchimento retroativo foi concluído e recalculou os valores de recursos em seus intervalos.
FAILED	O preenchimento retroativo parou devido a um erro. Consulte Recuperar de um preenchimento retroativo falho.
CANCELLED	O preenchimento retroativo foi cancelado antes de terminar.

Se você não tiver o nome da operação, localize o preenchimento retroativo mais recente de um recurso materializado no campo latest_backfill_operation retornado por list_materialized_features e passe-o para get_backfill.

Para cancelar um preenchimento retroativo, chame cancel_backfill com seu status:

Python

fe.cancel_backfill(backfill=backfill)

Cancelar um preenchimento retroativo solicita que ele pare. Um preenchimento retroativo que está prestes a terminar ainda pode ter sucesso, portanto, verifique seu estado final com get_backfill. Cancelar um preenchimento retroativo que já terminou não tem efeito. Um preenchimento retroativo cancelado pode deixar alguns valores de recursos recomputados, como descrito em Recuperar de um preenchimento retroativo com falha.

Concorrência

Uma execução de preenchimento retroativo ocorre junto com sua materialização agendada. Os preenchimentos retroativos de diferentes Views de recursos também podem ter execução ao mesmo tempo.

Apenas um preenchimento retroativo pode ser executado para uma view de recurso por vez. Se você começar um preenchimento retroativo para uma view de recurso que já tem um preenchimento retroativo em andamento, a solicitação falhará com um erro ALREADY_EXISTS. Aguarde a conclusão do preenchimento retroativo anterior antes de iniciar o próximo.

Recuperar de uma falha no preenchimento retroativo

Um preenchimento retroativo falho ou cancelado pode parar antes de terminar. Cada valor que o preenchimento retroativo reescreveu antes de parar é totalmente recomputado. Os valores que não foram alcançados mantêm seus valores anteriores, portanto, algumas Views de recursos ou intervalos de tempo podem não ser atualizados.

Para recuperar, começar o mesmo preenchimento retroativo novamente. Se você passou um request_id, passe um novo, porque uma nova tentativa com o request_id original retorna o preenchimento retroativo com falha em vez de iniciar um novo. O preenchimento retroativo é seguro para repetir. Se os dados de origem não mudaram, o recálculo de um intervalo que já foi concluído com êxito produz os mesmos valores.

Limitações

• Apenas recursos de agregação em lote que usam um DeltaTableSource e um SlidingWindow ou TumblingWindow podem ser preenchidos retroativamente. Recursos de transmissão, ColumnSelection recursos, recursos com um RollingWindow ou SawtoothWindow, recursos com uma janela de tempo de vida e recursos com outras origens, como RequestSource, não podem ser preenchidos retroativamente.
• As views de recursos que produzem valores em diferentes intervalos ou deslocamentos não podem compartilhar um preenchimento retroativo. Comece um preenchimento retroativo separado para cada grupo.
• O preenchimento retroativo atualiza a tabela offline de uma recurso view e, se a recurso view também estiver materializada em um armazenamento online, sua tabela online. Você não pode preencher apenas um deles.
• O preenchimento retroativo não preenche intervalos de tempo após os valores materializados mais recentes. A materialização agendada os preenche.