백필 피처 뷰

백필은 선택한 시간 범위에 따른 피처 뷰의 물질화된 값을 재계산합니다. 과거 소스 데이터를 수정하거나 추가한 후에 사용하면, 오프라인과 온라인 머티리얼라이제이션이 업데이트된 데이터를 반영하도록 합니다.

Materialization은 각 실행 시 최근 특징 값을 계산하며 이미 작성한 값은 다시 처리하지 않습니다. 과거 시간 범위에 대한 소스 데이터 변경은 해당 시간 범위를 백필해야 물질화된 값에 반영됩니다. 다음과 같은 상황에서 백필을 사용하세요:

  • 업스트림 데이터 품질 문제가 과거 시간 범위에 영향을 미쳤고, 소스 행을 수정하셨습니다.
  • 과거 시간 범위의 소스 데이터는 머티리얼라이제이션이 이미 처리한 후에 도착했다.

백필은 예정된 머티리얼라이제이션 작업과 함께 진행되는 일회성 작업입니다. 매티얼라이제이션 일정은 변경되지 않습니다. Materialize Feature Views를 참조하세요.

Requirements

  • databricks-feature-engineering 0.18.2 이상입니다. 기타 요구 사항은 요구 사항을 참조하세요.
  • 각 기능 뷰는 DeltaTableSource와 SlidingWindow 또는 TumblingWindow를 사용하는 배치 집계 기능입니다. 영구 창은 지원되지 않습니다.
  • 각 피처 뷰는 물질화되었으며 최소 한 번의 물질화 실행을 완료했습니다. 백필은 이미 머티리얼라이제이션이 기록한 값을 다시 계산하므로 Feature View를 처음으로 머티리얼라이즈할 수 없습니다.
  • Feature View를 구체화한 동일한 사용자 또는 서비스 주체로, Feature Views가 구체화된 작업 공간에서 백필을 시작합니다.

Permissions

백필은 사용자 권한으로 실행되며, 머티리얼라이제이션과 동일한 테이블을 읽고 쓰기 때문에 머티리얼라이제이션과 동일한 권한을 사용합니다. Unity 카탈로그 권한 설명은 Unity 카탈로그 권한 참고 문서를 참조하세요.

  • 백필하는 각 기능 뷰에는 MANAGE가 있어야 합니다.
  • 백필을 확인하려면 백필 내 모든 피처 뷰에서 READ FEATURE이(가) 필요합니다. 백필을 취소하려면 백필에 포함된 모든 피처 뷰에서 MANAGE해야 합니다.

백필 시작

백필을 시작하려면 백필할 Feature View와 하나 이상의 시간 범위를 지정하여 backfill_features를 호출하세요:

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:

하나의 호출에서 모든 피처 뷰는 같은 시점에 값을 생성해야 합니다. 이들은 값 사이의 간격(window_duration의 SlidingWindow 또는 TumblingWindow의 slide_duration)과 동일한 offset를 공유해야 합니다. 그렇지 않으면 Feature View를 구간별로 그룹화하라는 오류와 함께 호출이 실패하여 각 그룹별로 별도의 백필을 시작할 수 있습니다.

각 BackfillRange에는 포괄적인 end_time와 배타적인 start_time가 있습니다. 둘 다 Python datetime 값입니다. 시간대가 없는 A datetime 는 UTC로 읽힙니다. 각 start_time는 해당 end_time보다 이전이어야 하며, 한 통화의 범위는 겹칠 수 없습니다. 백필이 각 범위를 어떻게 해석하는지에 대해서는 백필이 시간 범위를 어떻게 적용하는지를 참고하세요.

다음 예시는 두 개의 Feature View에 대해 일주일간의 기록을 보충합니다:

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>

되메우기 시작하기 전에 backfill_features가 다음 사항을 확인합니다. 검사가 실패하면, 해당 호출은 영향을 받는 기능 뷰의 이름이 명시된 오류와 함께 실패합니다.

  • 각 기능 뷰는 완료된 구체화 실행을 포함한 요구사항을 충족합니다.
  • 각 피처 뷰를 머티리얼라이즈하셨습니다.
  • 필요한 권한을 갖추셨습니다.

메서드는 되채우기를 설명하는 BackfillStatus를 반환합니다. 이는 operations/<operation-id> 형식의 operation_name로 백필을 식별합니다. 되메우기 모니터링 또는 취소를 참조하세요.

호출을 안전하게 다시 시도할 수 있도록 UUID를 request_id로 전달하세요. 같은 request_id로 재시도하면 새 백필을 시작하는 대신 원래 백필을 반환합니다.

되메우기 비용을 귀속하려면 tags, budget_policy_id 또는 둘 다를 전달하세요. 이는 그 되메우기에만 적용됩니다. 태그 및 서버리스 사용 정책이 적용된 속성 비용을 참고하세요.

되채우기가 적용되는 시간 범위

각 범위는 재처리할 소스 데이터를 선택합니다: 타임스탬프가 start_time 이상 end_time 미만인 소스 행입니다. 백필은 각 범위별로 다음과 같이 적용됩니다:

  • 범위는 정수 기능 값에 정렬됩니다. 백필은 전체 특징 값을 재계산하여 각 범위를 바깥쪽으로 넓혀 특징이 값을 생성하는 가장 가까운 시점까지 확장합니다. SlidingWindow 특징은 매 slide_duration마다 값을 생성하고, TumblingWindow 특징은 매 window_duration마다 값을 생성하며, 창을 설정하면 창의 offset만큼 이동된 상태로 생성됩니다. 예를 들어, 1시간 slide_duration인 기능의 경우, 오전 1시 30분부터 오전 2시 30분까지의 범위가 오전 1시부터 3시로 바뀝니다. 직접 범위를 정렬할 필요는 없습니다. 정렬 후 겹치는 범위들은 하나로 합쳐집니다.
  • 범위 이후에는 값이 변할 수 있습니다. 백필은 재처리된 데이터를 포함하는 시간 창을 가진 모든 특징 값을 다시 씁니다. 창은 end_time 후에 끝날 수 있으므로, 값은 end_time 이후 최대 1 window_duration까지 변할 수 있습니다. 예를 들어, window_duration이 7일인 기능의 경우 end_time 후 최대 7일까지 값이 변경될 수 있습니다.
  • 되메우기는 가장 최근의 머티리얼라이즈된 값에서 멈춥니다. 백필은 머티리얼라이제이션이 이미 기록한 이력만 재계산합니다. 만약 범위가 가장 최근에 구체화된 값을 넘어서면, 백필은 거기서 멈추고 이후 시간대는 예정된 물질화로 남겨둡니다.
  • 설정되지 않은 경계는 사용 가능한 데이터까지 확장됩니다. 만약 start_time를 누락하면 범위는 소스 데이터에서 가장 이른 타임스탬프에서 시작됩니다. end_time를 생략하면 범위는 가장 최근에 구체화된 값까지 확장됩니다.

backfill_ranges의 BackfillStatus은 정렬 후의 범위입니다. 백필은 가장 최근에 구체화된 값으로 좁히지 않기 때문에, 보고된 범위는 백필이 재계산한 값을 넘어 확장될 수 있습니다. 이후 값은 다시 채울 필요가 없습니다. 예약된 머티리얼라이제이션이 현재 소스 데이터에서 해당 값을 계산하기 때문입니다.

오프라인 및 온라인 테이블

백필은 피처 뷰의 오프라인 테이블을 업데이트하며, 피처 뷰가 온라인 스토어에도 머티리얼라이즈되어 있다면 온라인 테이블을 업데이트합니다. 둘 다 있는 Feature View의 경우, 백필이 오프라인 테이블을 재계산한 후 온라인 테이블을 다시 게시합니다. 그중 하나만 백필할 수는 없어요.

온라인 표에는 각 법인의 최신 값이 저장되어 있습니다. 백필은 엔터티의 최신 값을 변경할 때만 온라인 값을 변경합니다.

backfill 모니터링 또는 취소

backfill_features 다시 메우기가 끝나기를 기다리지 않고 반환됩니다. 대기하거나, wait=True를 전달하거나, 반환된 상태로 wait_for_backfill을 호출하세요:

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill는 백필이 성공하면 최종 BackfillStatus를 반환합니다. 되메우기가 실패하거나 취소되면 그 이유를 설명하는 OperationFailed 오류를 발생시킵니다. 대기 시간을 줄이려면 timeout를 timedelta로 전달하세요. 만약 그때까지 메우기가 완성되지 않았다면, wait_for_backfill에서 TimeoutError를 발생시킵니다. 대기를 멈춘다고 해서 백필이 취소되는 것은 아닙니다.

기다리지 않고 백필을 확인하거나 다른 노트북이나 작업에서 확인하려면 오퍼레이션 이름과 함께 get_backfill를 호출하세요:

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

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

BackfillStatus는 다음과 같은 필드를 가집니다:

  • operation_name: 백필을 식별하는 이름입니다.
  • state: 되메움 상태를 BackfillState 값으로.
  • feature_full_names: 백필의 Feature View 전체 이름.
  • backfill_ranges: 정렬된 시간 범위, 즉 UTC 경계를 갖는 BackfillRange 값.
  • error: 백필이 실패한 이유. 이 필드는 FAILED이/가 state일 때만 설정됩니다.

백필 상태는 다음 값 중 하나입니다:

주 Description
PENDING 백필이 승인되었고 아직 실행을 시작하지 않았습니다.
RUNNING 백필이 진행 중입니다.
SUCCEEDED 백필이 완료되었고 해당 범위의 특징값을 재계산했습니다.
FAILED 백필 작업이 오류 때문에 멈췄습니다. 실패한 백필에서 복구를 참조하세요.
CANCELLED 백필 작업은 완료되기 전에 취소되었습니다.

연산 이름이 없다면, list_materialized_features에서 반환된 latest_backfill_operation 필드에서 구체화된 피처의 가장 최근 백필을 찾아 get_backfill에 전달하세요.

백필을 취소하려면 다음 상태로 cancel_backfill를 호출하세요:

fe.cancel_backfill(backfill=backfill)

백필을 취소하면 중단이 요청됩니다. 곧 완료될 백필도 성공할 수 있으니, get_backfill와 함께 최종 상태를 확인하라. 이미 완료된 백필을 취소해도 효과가 없습니다. 취소된 백필은 일부 특성 값이 재계산되도록 할 수 있으며, 이는 실패한 백필에서 복구에 설명된 바와 같습니다.

Concurrency

예정된 머티리얼라이제이션과 함께 백필이 병행 실행됩니다. 서로 다른 피처 뷰의 백필을 동시에 실행할 수도 있습니다.

Feature View에 대해 한 번에 한 개의 백필만 실행할 수 있습니다. 이미 백필이 진행 중인 기능 뷰에 대한 백필을 시작하면, 요청이 ALREADY_EXISTS 오류와 함께 실패합니다. 이전 백필 작업이 끝날 때까지 기다렸다가 다음 작업을 시작하세요.

실패한 백필에서 복구

실패하거나 취소된 백필은 완료되기 전에 중단될 수 있습니다. 백필이 멈추기 전에 재작성한 각 값은 완전히 재계산됩니다. 도달하지 못한 값들은 이전 값을 유지하기 때문에 일부 기능 뷰나 시간 범위가 업데이트되지 않을 수 있습니다.

복구하려면 같은 백필을 다시 시작하세요. 만약 request_id를 전달했다면, 새 것을 전달하세요. 원래 request_id로 다시 시도하면 새로 시작하는 대신 실패한 백필이 반환되기 때문입니다. 되메우기는 안전하게 반복해도 됩니다. 원본 데이터가 변하지 않았다면, 이미 성공한 범위를 다시 계산해도 같은 값이 나옵니다.

Limitations

  • a DeltaTableSource 와 a SlidingWindow 또는 TumblingWindow 를 사용하는 배치 집계 기능만 백필이 가능합니다. 스트리밍 기능, ColumnSelection 기능, RollingWindow 또는 SawtoothWindow가 있는 기능, 수명 기간 윈도우가 있는 기능, 그리고 예: RequestSource와 같은 다른 소스가 있는 기능은 백필될 수 없습니다.
  • 서로 다른 간격이나 오프셋에서 값을 생성하는 피처 뷰는 하나의 백필을 공유할 수 없습니다. 각 그룹별로 별도의 backfill을 시작하세요.
  • 백필은 피처 뷰의 오프라인 테이블을 업데이트하며, 피처 뷰가 온라인 스토어에도 구체화되어 있다면 온라인 테이블을 업데이트합니다. 그중 하나만 백필할 수는 없어요.
  • 백필은 가장 최근에 구체화된 값 이후의 시간 범위를 채우지 않습니다. 예약된 구체화가 해당 항목을 채웁니다.
  • 에 마지막으로 업데이트됨