Özellik Görünümlerini Geri Doldur

Backfill, seçtiğiniz zaman aralıkları boyunca Özellik Görünümlerinizin somutlaştırılmış değerlerini yeniden hesaplar. Tarihsel kaynak verilerini düzelttikten veya ekledikten sonra bunu kullanın; böylece çevrimdışı ve çevrimiçi somutlaştırmalar güncellenmiş verileri yansıtır.

Materialization, her çalıştırmada son öznitelik değerlerini hesaplar ve daha önce yazdığı değerleri yeniden ele almaz. Geçmiş bir zaman aralığı için kaynak veride yapılan bir değişiklik, o zaman aralığına backfill yapana kadar materyalize edilmiş değerlere ulaşmaz. Aşağıdaki gibi durumlarda geri doldurma kullanın:

  • Upstream kaynaklı bir veri kalitesi sorunu geçmiş bir zaman aralığını etkiledi ve kaynak satırlarını düzelttiniz.
  • Geçmiş bir zaman aralığına ait kaynak veriler, materialization bunları işledikten sonra geldi.

Backfill, planlanan materialization sürecinizle birlikte yürüyen tek seferlik bir iştir. Bu, materialization takvimini değiştirmez. Bkz. Özellik Görünümlerini Somutlaştırma.

Requirements

  • databricks-feature-engineering 0.18.2 ve üzeri. Diğer gereksinimler için Gereksinimler bölümüne bakın.
  • Her Özellik Görünümü, bir DeltaTableSource ve veya SlidingWindow ya da TumblingWindow kullanan bir toplu toplama özelliğidir. Kalıcı pencereler desteklenmiyor.
  • Her Özellik Görünümü materyalize edilmiştir ve en az bir materyalizasyon çalıştırmasını tamamlamıştır. Backfill, maddeleştirmenin zaten yazdığı değerleri yeniden hesaplar, bu yüzden bir Feature View'u ilk kez materyalize edemez.
  • Özellik Görünümleri’ni materialize eden aynı kullanıcı veya hizmet sorumlusu olarak, bunların materialize edildikleri çalışma alanından doldurmaya başlarsınız.

Permissions

Backfill sizin gibi çalışır ve materialization’ınızla aynı tabloları okur ve yazar, yani materialization’ınızla aynı ayrıcalıkları kullanır. Tam Unity Kataloğu ayrıcalık açıklamaları için Unity Kataloğu ayrıcalıkları referansına bakınız.

  • Geri doldurduğunuz her Özellik Görünümünde MANAGE bulunmalıdır.
  • Bir geri doldurmayı kontrol etmek için, geri doldurmadaki her Özellik Görünümü'nde READ FEATURE olması gerekir. Bir geri doldurmayı iptal etmek için MANAGE, geri doldurmadaki her Özellik Görünümü'nde buna sahip olmanız gerekir.

Backfill başlat

Bir geri doldurma başlatmak için, geri doldurulacak Özellik Görünümleriyle ve bir veya daha fazla zaman aralığıyla backfill_features çağırın:

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:

Tek bir çağrıdaki tüm Özellik Görünümleri aynı zamanlarda değerler üretmelidir. Değerler arasında (bir SlidingWindow öğesinin slide_duration değeri veya bir window_duration öğesinin TumblingWindow değeri) için aynı aralığı ve aynı offset paylaşmalıdırlar. Aksi takdirde çağrı, Özellik Görünümlerinin aralığa göre gruplandığını belirten bir hatayla başarısız olur; böylece her grup için ayrı bir geri doldurma başlatabilirsiniz.

Her BackfillRange, kapsayıcı bir start_time ve dışlayıcı bir end_time içerir. İkisi de Python datetime değerleridir. Saat dilimi olmayan bir A datetime, UTC olarak okunur. Her start_time, kendi end_time'inden daha erken olmalı ve bir çağrıdaki aralıklar örtüşemez. Backfill’in her aralığı nasıl yorumladığını görmek için bkz. Backfill zaman aralıklarını nasıl uygular.

Aşağıdaki örnek, iki Özellik Görünümü için bir haftalık geçmiş verisini doldurur:

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>

Dolgu başlamadan önce backfill_features aşağıdakileri kontrol eder. Bir kontrol başarısız olursa, çağrı etkilenen Özellik Görünümlerinin adını belirten bir hatayla sonuçlanır.

  • Her Özellik Görünümü, tamamlanmış bir somutlaştırma çalıştırması da dahil olmak üzere gereksinimleri karşılar.
  • Her Feature View'ı oluşturdunuz.
  • Gerekli ayrıcalıklara sahipsin.

Yöntem, geri doldurmayı tanımlayan bir BackfillStatus döndürür. Onun operation_name geri dolguyu, operations/<operation-id> biçiminde tanımlar. Geri doldurmayı izleyin veya iptal edin.

Çağrının yeniden denenmesini güvenli kılmak için, request_id olarak bir UUID iletin. Aynı request_id ile yeniden denendiğinde, yeni bir doldurma başlatmak yerine orijinal backfill döndürülür.

Yedek doldurma maliyetini ilişkilendirmek için tags, budget_policy_id veya her ikisini iletin. Sadece o dolgu için geçerlidir. Etiketler ve sunucusuz kullanım politikalarıyla ilgili Öznitelik maliyetlerine bakın.

Geri doldurmanın zaman aralıklarına nasıl etki ettiği

Her aralık, yeniden işlenecek kaynak veriyi seçer: zaman damgaları start_time zamanında veya sonrasında ve end_time zamanından önce olan kaynak satırlar. Backfill her aralığa aşağıdaki gibi uygulanır:

  • Aralıklar özelliğin tam sayı değerlerine hizalanır. Backfill, tüm özellik değerlerini yeniden hesaplar, böylece her aralığı özelliğin bir değer ürettiği en yakın zamanlara kadar dışa doğru genişletir. Bir SlidingWindow özellik her slide_duration bir değer üretir ve bir TumblingWindow özellik ise, bir tane ayarlarsanız pencerenin offset değeri kadar kaydırılmış olarak, her window_duration bir değer üretir. Örneğin, 1 saatlik slide_duration olan bir özellik için, 1:30 ile 2:30 arasındaki aralık 1:00 ile 3:00 arası olur. Aralıkları kendiniz hizalamanıza gerek yok. Hizalama sonrası örtüşen aralıklar birleştirilir.
  • Aralıktan sonraki değerler değişebilir. Backfill, zaman penceresi yeniden işlenmiş verileri içeren her özellik değerini yeniden yazar. Bir pencere, end_time sonrasında bitebilir; bu yüzden end_time sonrasındaki bir window_durationye kadar olan değerler değişebilir. Örneğin, 7 günlük window_duration bir özellik için, end_time sonrasındaki 7 güne kadar değerler değişebilir.
  • Geri doldurma en son somutlaştırılmış değerlerde durur. Backfill, yalnızca materialization'ın zaten yazdığı geçmişi yeniden hesaplar. Bir aralık en son somutlaştırılmış değerlerin ötesine geçerse, geri doldurma burada durur ve daha sonraki zaman aralığını zamanlanmış somutlaştırmanıza bırakır.
  • Belirlenmemiş sınırlar kullanılabilir veriye kadar uzanır. Eğer start_time belirtmezseniz, aralık kaynak verisindeki en erken zaman damgasından başlar. Eğer end_time belirtmezseniz, aralık en son somutlaştırılmış değerlere kadar uzanır.

Bir backfill_ranges öğesinin BackfillStatus aralıkları, hizalama sonrası aralıklarınızdır. Geri doldurma onları en son somutlaştırılmış değerlere daraltmaz, böylece bildirilen bir aralık, doldurmanın yeniden hesapladığı değerlerin ötesine geçebilir. Daha sonraki değerleri geri doldurmanıza gerek yok, çünkü zamanlanmış somutlaştırmanız bunları mevcut kaynak verilerinden hesaplar.

Çevrimdışı ve çevrimiçi tablolar

Backfill, Feature View'un çevrimdışı tablosunu günceller ve eğer Feature View aynı zamanda çevrimiçi bir depoya da materialize edildiyse, çevrimiçi tablosunu da günceller. Her ikisini de içeren bir Feature View için, backfill çevrimdışı tabloyu yeniden hesaplar ve ardından çevrimiçi tabloyu ondan yeniden yayımlar. Sadece birini geriye dönük dolduramazsınız.

Çevrimiçi tablo, her varlık için en güncel değeri içeriyor. Bir geri doldurma, çevrimiçi değerleri yalnızca bir varlığın en son değerini değiştirdiğinde değiştirir.

Geri doldurmayı izlemek veya iptal etmek

backfill_features Doldurmanın bitmesini beklemeden geri döner. Beklemek için wait=True iletin veya döndürülen durumla wait_for_backfill çağrısını yapın:

backfill = fe.wait_for_backfill(backfill=backfill)

wait_for_backfill, geri doldurma başarılı olduğunda son BackfillStatus öğesini döndürür. Eğer backfill başarısız olursa veya iptal edilirse, sebebini açıklayan bir OperationFailed hata ortaya çıkar. Ne kadar bekleyeceğini sınırlamak için, timeout öğesini timedelta olarak geçirin. Eğer o zamana kadar dolgu bitmezse, wait_for_backfill bir TimeoutError oluşturur. Beklemeyi durdurmak backfill işlemini iptal etmez.

Beklemeden veya başka bir not defterinden ya da işten bir backfill’i kontrol etmek için, işlem adıyla get_backfill çağırın:

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

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

BackfillStatus aşağıdaki alanlara sahiptir:

  • operation_name: Dolguyu tanımlayan isim.
  • state: Arka dolgunun durumu, BackfillState değeri olarak.
  • feature_full_names: Backfill işlemindeki Özellik Görünümlerinin tam isimleri.
  • backfill_ranges: UTC sınırlarına sahip BackfillRange değerleri olarak hizalanmış zaman aralıkları.
  • error: Backfill işleminin başarısız olma nedeni. Bu alan yalnızca FAILEDstate olduğunda ayarlanır.

Geri doldurma durumu aşağıdaki değerlerden biridir:

State Description
PENDING Backfill kabul edildi ve henüz çalışmaya başlamadı.
RUNNING Geri doldurma çalışıyor.
SUCCEEDED Backfill tamamlandı ve özellik değerlerini aralıklarında yeniden hesapladı.
FAILED Doldurma işlemi bir hata nedeniyle durdu. Başarısız bir geri doldurmadan kurtarma bölümüne bakın.
CANCELLED Doldurma işlemi tamamlanmadan iptal edildi.

Eğer işlem adı yoksa, list_materialized_features tarafından döndürülen latest_backfill_operation alanında somutlaştırılmış bir özelliğin en son geri doldurmasını bulun ve bunu get_backfill öğesine iletin.

Bir geri doldurmayı iptal etmek için, cancel_backfill öğesini durumuyla çağırın:

fe.cancel_backfill(backfill=backfill)

Bir geri doldurmayı iptal etmek, durdurulmasını ister. Bitmek üzere olan bir dolgu yine de başarılı olabilir, bu yüzden son durumunu get_backfill ile kontrol edin. Zaten bitmiş bir geri doldurmanın iptalinin etkisi yoktur. İptal edilen bir geri doldurma, Başarısız bir geri doldurmadan kurtarma bölümünde açıklandığı gibi, bazı özellik değerlerinin yeniden hesaplanmasına neden olabilir.

Concurrency

Planlanan somutlaştırmanızla birlikte bir geri doldurma işlemi de çalışır. Farklı Feature View'ların geri doldurulması da aynı anda çalışabilir.

Aynı anda yalnızca bir Özellik Görünümü için bir geri doldurma çalışabilir. Zaten devam eden bir Özellik Görünümü için geri doldurma başlatırsanız, istek ALREADY_EXISTS hatasıyla başarısız olur. Bir sonraki backfill’e başlamadan önce önceki backfill’in bitmesini bekleyin.

Başarısız bir geri doldurma işleminden kurtulun

Başarısız veya iptal edilen bir geri doldurma işlemi bitmeden durabilir. Geri doldurmanın durmadan önce yeniden yazdığı her değer tamamen yeniden hesaplanır. Ulaşılmayan değerler önceki değerlerini korur, bu yüzden bazı Özellik Görünümleri veya zaman aralıkları güncellenmeyebilir.

Kurtarmak için aynı backfill'i tekrar başlatın. Eğer bir request_id ilettiyseniz, yenisini iletin; çünkü orijinal request_id ile yeniden deneme, yeni bir deneme başlatmak yerine başarısız backfill'i döndürür. Doldurma işlemini tekrarlamak güvenlidir. Kaynak veri değişmediyse, zaten başarılı olan bir aralığı yeniden hesaplamak aynı değerleri verir.

Limitations

  • Yalnızca DeltaTableSource ve SlidingWindow veya TumblingWindow kullanan toplu toplama özellikleri geri doldurulabilir. Akış özellikleri, ColumnSelection özellikler, RollingWindow veya SawtoothWindow özellikli özellikler, ömür boyu penceresi olan özellikler ve diğer kaynaklara sahip özellikler, örneğin RequestSource, geri doldurulamaz.
  • Farklı aralıklarda veya ofsetlerde değer üreten Özellik Görünümleri, bir geri doldurmayı paylaşamaz. Her grup için ayrı bir geri doldurma başlat.
  • Backfill, Feature View'un çevrimdışı tablosunu günceller ve eğer Feature View aynı zamanda çevrimiçi bir depoda somutlaştırılmışsa, çevrimiçi tablosunu da günceller. Bunlardan yalnızca birini geriye dönük dolduramazsınız.
  • Geri doldurma, en son materyalize edilmiş değerlerden sonra zaman aralıklarını doldurmaz. Planlanan oluşturmanız onları doldurur.
  • Son güncelleştirme: