メインコンテンツまでスキップ

エンティティの特徴量の値をパージ

備考

ベータ版

この機能はベータ版です。使用するには、ワークスペース管理者が [プレビュー] ページから Feature Views Advanced Functionality を有効にする必要があります。Databricksのプレビューを管理するを参照してください。

特徴量エンティティパージを使用して、選択したエンティティの1つ以上の特徴量ビューのコンピュートされた特徴量の値を削除します。defaultでは、パージは、Unity CatalogおよびLakebaseの該当するオフラインおよびオンラインマテリアライズドビューの一致する行で、選択した特徴量の値をNULLに設定します。一致する行を削除するには、delete_rows=Trueをセットします。 パージしたいマテリアライズドビューが作成されたワークスペースでパージをランします。特徴量ビューの定義、マテリアライズドビュー、またはソースデータは削除されません。他のワークスペースで作成されたマテリアライズドビューは影響を受けません。

たとえば、データ削除リクエストを受け取った後に、顧客の実体化された特徴値を消去できます。顧客のエンティティキーを含む行も削除するには、delete_rows=True を設定します。

警告

パージを送信する前に、選択したエンティティを特徴量ソースデータから削除し、ソースがそれらのエンティティ用の新しいデータを受信しないようにする必要があります。パージはソースを変更せず、スケジュールされた継続的なマテリアライズを停止しません。一致するソースデータが残っているか、後から到着した場合、マテリアライズによって値が再作成されます。

要件​

  • 特徴量は、登録されたFeature Viewsである必要があります。各Feature Viewには、パージを送信するワークスペースで作成されたマテリアライゼーションが少なくとも1つ存在する必要があります。異なるワークスペースで作成されたマテリアライゼーションをパージするには、ワークスペースごとに個別のリクエストを送信します。RequestSource、FeatureViewSource、およびその他の実体化できない特徴量はサポートされていません。
  • 3 つの部分からなる Unity Catalog 名を使用して、1~500 個の一意のフィーチャを指定します。
  • リクエストを送信するときに、バックフィルが進行中、または論理削除フェーズでパージされている機能を含めることはできません。「フィーチャービューのバックフィル」を参照してください。
  • エンティティテーブルは、少なくとも1つの列を持つUnity CatalogのDeltaテーブルである必要があります。「エンティティテーブルの準備」を参照してください。
  • Databricks Feature Engineeringクライアント バージョン 0.18.0 以降を使用してください。
  • delete_rows=True での行削除には、Databricks Feature エンジニアリング クライアント バージョン 0.18.3 以上を使用してください。
  • delete_rows=True の場合、影響を受ける各マテリアライズドビューを共有するすべての機能を含めます。要求は複数のテーブルにまたがる可能性があり、その要件は各テーブルに個別に適用されます。検証では、INVALID_PARAMETER_VALUE を含む不完全なカバレッジが拒否され、影響を受けるテーブルと要求がカバーしていない列がリストされます。

権限​

本番運用では、機能ビューを作成および実体化するService Principalと同じプリンシパルとしてパージを実行することをDatabricksでは推奨しています。このプリンシパルには通常、すでに必要な権限が付与されています。権限が変更されている場合は、パージを送信する前に次の要件を確認してください。

パージを送信して完了するには、次の権限が必要です:

  • MANAGE リクエスト内のすべてのFeature Viewに対して。
  • SELECT エンティティテーブルで。
  • SELECT および、パージが更新するオフライン、部分集計、およびオンラインの各テーブルの MODIFY。
  • オンラインストアで使用されるLakebaseインスタンスまたはプロジェクトへのアクセス権。オンラインテーブルの読み取りと更新、および delete_rows=True の際の行の削除権限が含まれます。 プロジェクト権限の付与 を参照してください。
  • 埋め込みスキーマのないスキーマレジストリ ストリームの場合、利用可能な場合は SELECT や READ_METADATA などの取り込みテーブルのメタデータを読み取る権限。パージの検証では、取り込みテーブルの行ではなく、スキーマを読み取ってエンティティキーの型を解決します。
  • USE CATALOG また、上記の各リソースの親カタログとスキーマに対する USE SCHEMA が必要です。

Unity Catalog の特権の詳細については、 Unity Catalog の特権リファレンスを参照してください。フィーチャ ビューの権限については、 フィーチャ ビューのマテリアライズを参照してください。

エンティティテーブルの準備​

削除するエンティティを特定する Delta テーブルを作成します。各列は、リクエスト内のすべての Feature View のエンティティキーに対応している必要があります。列名とデータ型は、Feature View のエンティティキーと一致している必要があります。非キー列を含めないでください。

テーブルには、フィーチャビューのエンティティリストの先頭プレフィックスであるエンティティキーのサブセットを含めることができます。パージは、残りのキーに関係なく、指定されたキー値を持つすべてのエンティティに一致します。null キー値がサポートされています。

重要

エンティティテーブルの列には、すべてのエンティティキー、またはフィーチャビューのエンティティリストの順序に一致する先頭のプレフィックスが含まれている必要があります。エンティティテーブル内の列の順序は関係ありません。

既存のオンライン テーブルの場合、主キーの順序は、特徴量ビューのエンティティ リストの順序とは異なる場合があります。その場合、検証では代わりにオンライン テーブルの主キー プレフィックスを使用し、部分キーのリクエストが一致しない場合は必要な順序を報告します。

要求された特徴量ビューは、エンティティテーブルの列がすべての特徴量ビューのエンティティキーセットのサブセットである限り、異なるエンティティキーセットを持つことができます。

パージジョブは1つのDeltaテーブルのバージョンを解決し、そのスナップショットをすべてのターゲットに使用します。リクエストの送信後は、エンティティテーブルを変更しないでください。ジョブがバージョンを解決した後に追加されたエンティティをパージするには、別のリクエストを送信します。

NULL 値または行の削除を選択する​

defaultでは、パージは、選択した特徴量の値をNULLに設定し、エンティティキーと他の列を含む行を保持します。行を保持したまま特徴量の値を削除するには、このモードを使用します。

delete_rows=Trueをセットして、一致する行をエンティティキーを含めて削除します。エンティティキーと特徴量の値を削除する必要があるデータ削除リクエストには、行削除を使用します。「要件」で説明されているように、影響を受けるマテリアライズドビューを共有するすべての特徴量を含めます。

クリーンアップの仕組み​

パージには2つのフェーズがあります。

  • 論理削除 (PENDING_PURGEおよびRUNNING_PURGE状態): パージは、一致する行を削除するか、特徴量の値をNULLに設定し、その後、オンラインでの変更を同期します。このフェーズの後、パージは機能上のロックを解除するため、クリーンアップ中に別のパージを起動できます。
  • クリーンアップ(PENDING_CLEANUPおよびRUNNING_CLEANUPの状態):オフラインテーブルの場合、パージは少なくとも7日間待機してから、古いデータファイルとトランザクションLogsを削除します。クリーンアップが完了するまで操作は完了しません。

オフラインテーブルのファイルまたはLogsの保持期間が7日より長い場合、パージによってテーブル全体の保持期間が7日に短縮され、そのテーブルのタイムトラベルも7日に制限されます。操作中に保持設定を7日を超えて増やさないでください。クリーンアップが失敗します。

リテンションプロパティは、データファイルが delta.deletedFileRetentionDuration、トランザクションLogsが delta.logRetentionDuration です。パージを行っても、クリーンアップ後に元の値が復元されることはありません。

Lakebaseについて、Databricksは7日以下のポイントインタイムリストア (PITR) ウィンドウを推奨します。「リストア ウィンドウの構成」を参照してください。パージは、Lakebaseの自動履歴クリーンアップを待機したり、その履歴の物理的な削除を検証したりしません。

パージの送信​

FeatureEngineeringClient.purge_feature_entitiesを呼び出す.delete_rows引数のdefaultはFalseであるため、次の例では特徴値をNULLに設定し、行を保持します。このメソッドは、パージが完了するのを待たずに長期実行操作を返します。

Python
from databricks.feature_engineering import FeatureEngineeringClient

fe = FeatureEngineeringClient()

operation = fe.purge_feature_entities(
features=[
"main.feature_store.customer_purchase_count_30d",
"main.feature_store.customer_purchase_total_30d",
],
entities_table="main.feature_store.entities_to_purge",
)

print(f"Purge operation: {operation.name()}")

代わりに一致する行を削除するには:

Python
operation = fe.purge_feature_entities(
features=[
"main.feature_store.customer_purchase_count_30d",
"main.feature_store.customer_purchase_total_30d",
],
entities_table="main.feature_store.entities_to_purge",
delete_rows=True,
)

操作状態のモニタリング​

操作を更新して終了したかどうかを確認するには、operation.done() を使用します。operation.metadata() で状態を検査するか、fe.get_operation(name=operation.name()) をポーリングして metadata["state"] を読み取ります。

クリーンアップを伴うオフラインパージの場合、状態は次のフェーズを記述します:

  • PENDING_PURGE:論理削除の起動を待機中です。
  • RUNNING_PURGE: パージは、一致する行を削除するか、特徴値を NULL に設定し、変更をオンラインで同期します。
  • PENDING_CLEANUP: パージは、オフライン保持期間が終了するまで待機しています。
  • RUNNING_CLEANUP: パージは、古いオフラインデータファイルとトランザクションLogsをクリーンアップします。

クリーンアップタスクを伴わないオンライン専用のパージおよびランは、代わりにPENDINGまたはRUNNINGをレポートする場合があります。操作はSUCCEEDED、FAILED、またはCANCELLEDで終了します。

機能ごとの結果を確認する​

機能ごとの結果は、操作が完了した後に利用可能になります。サブミットするセッションで、operation.done()がTrueを返す後にoperation.wait()を使用します。後でセッションで結果を取得するには、パージをサブミットした時に表示された操作名を指定してfe.get_operation(name=...)を呼び出します。

Python
from databricks.feature_engineering import FeatureEngineeringClient
from databricks.sdk.service.ml import PurgeFeatureEntitiesResponse

fe = FeatureEngineeringClient()
status = fe.get_operation(name="operations/<operation_id>")

if not status.done:
print(f"Purge is still in progress: {status.metadata['state']}")
elif status.error:
print(f"Purge operation error: {status.error}")
else:
response = PurgeFeatureEntitiesResponse.from_dict(status.response)
print(f"Purge state: {response.state}")

for result in response.results or []:
print(
result.feature,
result.offline_state,
result.online_state,
result.error,
)

完了したレスポンスには、フィーチャービューごとに1つの結果が含まれます。

  • offline_state オフラインマテリアライゼーションの結果をレポートします。
  • online_state オンラインマテリアライゼーションの複合結果を報告します。
  • 結果は、SUCCEEDED、FAILED、または NOT_APPLICABLE です。
  • フィーチャービューにそのストアタイプのマテリアライゼーションターゲットがない場合、結果は NOT_APPLICABLE になります。たとえば、オンライン専用のフィーチャービューのオフラインの結果は NOT_APPLICABLE になり、オンラインのマテリアライゼーションがないフィーチャービューのオンラインの結果は NOT_APPLICABLE になります。
  • error 該当するターゲットが失敗した場合のフィーチャビュー固有のエラーが含まれています。

特徴量ごとの結果をすべて確認します。操作は、フィーチャ ビューやストアの種類によって異なる結果で終了する場合があります。

操作レベルの障害については、response.stateとresponse.errorも確認してください。

部分的障害からの回復​

パージが部分的に失敗した場合は、機能ごとのエラーを調査し、アクセスまたは構成の問題を修正してください。失敗した結果の機能ビューに新しい request_id を指定して、新しいパージリクエストを送信します。行削除の場合は、それらの機能の一部が前のリクエストで成功した場合でも、影響を受けるマテリアライズドビューを共有するすべての機能を含めます。再試行する前に、ソースデータをクリーンに保ちます。失敗が続く場合は、Databricks サポートに連絡してください。

リクエストを安全に再試行する​

request_id を UUID4 の値に設定し、リクエストが承認されるまで保持します。ネットワークまたはクライアントの障害によって送信結果が不明確になった場合は、同じ ID を使用して同じリクエストを再試行してください。Databricks は、2 番目の削除を開始する代わりに、既存の操作を返します。

特徴量セットとエンティティテーブルは、元のリクエストと一致している必要があります。異なるリクエストパラメーターでIDを再利用することは拒否されます。IDを省略するとクライアントがIDを生成しますが、アプリケーションレベルのリトライをべき等にするには明示的なIDが必要です。これは、外部のオーケストレーションレイヤーが操作を再試行する場合にも役立ちます。

パージコンピュートコストの属性​

パージランではServerlessコンピュートを使用します。Databricks Feature Engineeringクライアントバージョン0.18.1以降では、tagsまたはbudget_policy_idを使用してコンピュートコストを割り当てます:

Python
operation = fe.purge_feature_entities(
features=["main.feature_store.customer_purchase_count_30d"],
entities_table="main.feature_store.entities_to_purge",
tags={"team": "recommendations", "workflow": "privacy-deletion"},
budget_policy_id="00000000-0000-0000-0000-000000000000",
)

タグはパージコンピュートに適用され、Unity Catalogフィーチャーリソースには適用されません。1 つのリクエストでサポートされるタグの数は最大 25 個です。