Share via

Unity 目錄中的功能工程

  • 發行項

此頁面說明如何在 Unity 目錄中建立和使用功能數據表。

此頁面僅適用於針對 Unity 目錄啟用的工作區。 如果您的工作區未針對 Unity 目錄啟用，請參閱 使用工作區功能存放區中的功能。

需求

Unity 目錄中的功能工程需要 Databricks Runtime 13.2 或更新版本。 此外，Unity 目錄中繼存放區必須具有 許可權模型 1.0 版。

在 Unity 目錄 Python 用戶端中安裝功能工程

Unity 目錄中的功能工程具有 Python 用戶端 FeatureEngineeringClient。 類別可在 PyPI 上使用套件， databricks-feature-engineering 並預安裝在 Databricks Runtime 13.3 LTS ML 和更新版本。 如果您使用非 ML Databricks Runtime，則必須手動安裝用戶端。 使用相容性矩陣來尋找 Databricks 執行時間版本的正確版本。

%pip install databricks-feature-engineering

dbutils.library.restartPython()

在 Unity 目錄中建立功能資料表的目錄和架構

您必須建立新的 目錄，或使用功能數據表的現有目錄 。

若要建立新的目錄，您必須擁有CREATE CATALOG中繼存放區的許可權。

CREATE CATALOG IF NOT EXISTS <catalog-name>

若要使用現有的目錄，您必須擁有 USE CATALOG 目錄的許可權。

USE CATALOG <catalog-name>

Unity 目錄中的功能數據表必須儲存在架構中。 若要在目錄中建立新的架構，您必須擁有 CREATE SCHEMA 目錄的許可權。

CREATE SCHEMA IF NOT EXISTS <schema-name>

在 Unity 目錄中建立功能數據表

注意

您可以在 Unity 目錄中使用現有的 Delta 數據表，其中包含主鍵條件約束做為功能數據表。 如果數據表沒有定義主鍵，您必須使用 ALTER TABLE DDL 語句更新資料表以新增條件約束。 請參閱 在 Unity 目錄中使用現有的 Delta 資料表作為功能資料表。

不過，將主鍵加入串流數據表或由 Delta Live Tables 管線發佈到 Unity 目錄的具體化檢視表，需要修改串流數據表或具體化檢視定義的架構，以包含主鍵，然後重新整理串流數據表或具體化檢視表。 請參閱 使用差異實時數據表管線建立的串流數據表或具體化檢視作為功能數據表。

Unity 目錄中的功能數據表是 Delta 資料表。 功能數據表必須有主鍵。 功能數據表，就像 Unity 目錄中的其他數據資產一樣，是使用三層命名空間來存取： <catalog-name>.<schema-name>.<table-name>。

您可以使用 Databricks SQL、Python FeatureEngineeringClient或 Delta Live Tables 管線，在 Unity 目錄中建立功能數據表。

Databricks sql

您可以使用任何 Delta 資料表搭配 主鍵條件約束 作為功能數據表。 下列程式代碼示範如何使用主鍵建立資料表：

CREATE TABLE ml.recommender_system.customer_features (
  customer_id int NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id)
);

若要建立 時間序列功能數據表，請將時間數據行新增為主鍵數據行，並指定 TIMESERIES 關鍵詞。 TIMESERIES 關鍵詞需要 Databricks Runtime 13.3 LTS 或更新版本。

CREATE TABLE ml.recommender_system.customer_features (
  customer_id int NOT NULL,
  ts timestamp NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id, ts TIMESERIES)
);

建立數據表之後，您可以像其他 Delta 數據表一樣將數據寫入其中，並做為功能數據表。

Python

如需下列範例中使用的命令和參數詳細數據，請參閱 功能工程 Python API 參考。

  1. 撰寫 Python 函式來計算功能。 每個函式的輸出應該是具有唯一主鍵的 Apache Spark DataFrame。 主鍵可以包含一或多個數據行。
  2. 藉由具現化 FeatureEngineeringClient 和 使用 create_table來建立功能數據表。
  3. 使用 write_table填入功能數據表。
from databricks.feature_engineering import FeatureEngineeringClient

fe = FeatureEngineeringClient()

# Prepare feature DataFrame
def compute_customer_features(data):
  ''' Feature computation code returns a DataFrame with 'customer_id' as primary key'''
  pass

customer_features_df = compute_customer_features(df)

# Create feature table with `customer_id` as the primary key.
# Take schema from DataFrame output by compute_customer_features
customer_feature_table = fe.create_table(
  name='ml.recommender_system.customer_features',
  primary_keys='customer_id',
  schema=customer_features_df.schema,
  description='Customer features'
)

# An alternative is to use `create_table` and specify the `df` argument.
# This code automatically saves the features to the underlying Delta table.

# customer_feature_table = fe.create_table(
#  ...
#  df=customer_features_df,
#  ...
# )

# To use a composite primary key, pass all primary key columns in the create_table call

# customer_feature_table = fe.create_table(
#   ...
#   primary_keys=['customer_id', 'date'],
#   ...
# )

# To create a time series table, set the timeseries_columns argument

# customer_feature_table = fe.create_table(
#   ...
#   primary_keys=['customer_id', 'date'],
#   timeseries_columns='date',
#   ...
# )

Delta 即時數據表

注意

數據表條件約束的差異實時數據表支援處於 公開預覽狀態。 下列程式代碼範例必須使用 Delta Live Tables 預覽通道來執行。

從包含主鍵條件約束之 Delta Live Tables 管線發行的任何數據表都可以當做功能數據表使用。 使用下列語法，在具有主鍵的 Delta Live Tables 管線中建立數據表：

CREATE LIVE TABLE customer_features (
  customer_id int NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id)
) AS SELECT * FROM ...;

若要建立 時間序列功能數據表，請將時間數據行新增為主鍵數據行，並指定 TIMESERIES 關鍵詞。

CREATE LIVE TABLE customer_features (
  customer_id int NOT NULL,
  ts timestamp NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id, ts TIMESERIES)
) AS SELECT * FROM ...;

建立數據表之後，您可以像其他 Delta Live Tables 數據集一樣將數據寫入其中，並做為功能數據表。

只有 Delta Live Tables SQL 介面才支援定義數據表條件約束。 若要為在 Python 中宣告的串流數據表或具體化檢視設定主鍵，請參閱 使用 Delta Live Tables 管線建立的串流數據表或具體化檢視作為功能數據表。

在 Unity 目錄中使用現有的 Delta 資料表作為功能數據表

具有主鍵的 Unity 目錄中的任何差異資料表都可以是 Unity 目錄中的功能數據表，而且您可以使用功能 UI 和 API 搭配數據表。

注意

  • 只有數據表擁有者可以宣告主鍵條件約束。 擁有者的名稱會顯示在目錄總管的數據表詳細數據頁面上。
  • 確認 Unity 目錄中的功能工程支援 Delta 資料表中的數據類型。 請參閱 支持的數據類型。
  • TIMESERIES 關鍵詞需要 Databricks Runtime 13.3 LTS 或更新版本。

如果現有的 Delta 數據表沒有 主鍵條件約束，您可以建立一個，如下所示：

  1. 將主鍵資料列設定為 NOT NULL。 針對每個主鍵資料行，執行：

    ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL

  2. 改變資料表以新增主鍵條件約束：

    ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1, pk_col2, ...)

    pk_name 是主鍵條件約束的名稱。 依照慣例，您可以使用數據表名稱（不含架構和目錄），並加上 _pk 後綴。 例如，名稱 "ml.recommender_system.customer_features" 為的數據表會以其 customer_features_pk 主鍵條件約束的名稱來表示。

    若要讓數據表成為時間序列功能數據表，請在其中一個主鍵數據行上指定 TIMESERIES 關鍵詞，如下所示：

    ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1 TIMESERIES, pk_col2, ...)

    在數據表上新增主鍵條件約束之後，數據表會出現在功能 UI 中，而且您可以使用它做為功能數據表。

使用差異實時數據表管線建立的串流數據表或具體化檢視做為功能數據表

具有主鍵的 Unity 目錄中的任何串流資料表或具體化檢視都可以是 Unity 目錄中的功能數據表，而且您可以使用功能 UI 和 API 搭配數據表。

注意

  • 數據表條件約束的差異實時數據表支援處於 公開預覽狀態。 下列程式代碼範例必須使用 Delta Live Tables 預覽通道來執行。
  • 只有數據表擁有者可以宣告主鍵條件約束。 擁有者的名稱會顯示在目錄總管的數據表詳細數據頁面上。
  • 確認 Unity 目錄中的功能工程支援 Delta 資料表中的數據類型。 請參閱 支持的數據類型。

將主鍵新增至使用 SQL 建立的串流數據表或具體化檢視

若要為使用 Delta Live Tables SQL 介面建立的現有串流數據表或具體化檢視設定主鍵，請在管理對象的筆記本中更新串流數據表或具體化檢視的架構。 然後， 重新整理數據表 以更新 Unity Catalog 物件。

以下是將主鍵加入具體化檢視的語法：

CREATE OR REFRESH MATERIALIZED VIEW existing_live_table(
  id int NOT NULL PRIMARY KEY,
  ...
) AS SELECT ...

將主鍵新增至使用 Python 建立的串流數據表或具體化檢視

若要為 Delta Live Tables 管線所建立的現有串流數據表或具體化檢視建立主鍵，即使串流數據表或具體化檢視是使用 Delta Live Tables Python 介面建立，您也必須使用 Delta Live Tables SQL 介面。 若要將主鍵新增至在 Python 中建立的串流數據表或具體化檢視，請建立新的 SQL 筆記本，以定義從現有串流數據表或具體化檢視讀取的新串流數據表或具體化檢視表。 然後，以現有 Delta Live Tables 管線或新管線中的步驟執行筆記本。

以下是新 SQL 筆記本中用來將主鍵新增至具體化檢視的語法範例：

CREATE OR REFRESH MATERIALIZED VIEW new_live_table_with_constraint(
  id int NOT NULL PRIMARY KEY,
  ...
) AS SELECT * FROM existing_live_table

控制 Unity 目錄中功能數據表的存取

Unity 目錄中功能數據表的訪問控制是由 Unity 目錄所管理。 請參閱 Unity 目錄許可權。

更新 Unity 目錄中的功能數據表

您可以藉由新增功能，或根據主鍵修改特定數據列，來更新 Unity 目錄中的功能數據表。

不應更新下列功能資料表元數據：

  • 主索引鍵。
  • 數據分割索引鍵。
  • 現有功能的名稱或數據類型。

改變它們會導致下游管線使用功能來定型和服務模型中斷。

將新功能新增至 Unity 目錄中的現有功能數據表

您可以使用下列兩種方式之一，將新功能新增至現有的功能資料表：

  • 更新現有的功能計算函式，並使用傳回的 DataFrame 執行 write_table 。 這會更新功能數據表架構，並根據主鍵合併新的特徵值。
  • 建立新的特徵計算函式來計算新的特徵值。 這個新計算函式傳回的 DataFrame 必須包含功能數據表的主要和數據分割索引鍵（如果已定義）。 使用 DataFrame 執行 write_table ，以使用相同的主鍵，將新功能寫入現有的功能數據表。

僅更新功能數據表中的特定數據列

在中使用mode = "merge"write_table。 在呼叫中 write_table 傳送之 DataFrame 中，主鍵不存在的數據列保持不變。

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
fe.write_table(
  name='ml.recommender_system.customer_features',
  df = customer_features_df,
  mode = 'merge'
)

排程作業以更新功能數據表

為了確保功能數據表中的功能一律具有最新的值，Databricks 建議您 建立一個作業 來執行筆記本，定期更新功能數據表，例如每天。 如果您已建立非排程工作，您可以將它 轉換成排程工作 ，以確保功能值一律為最新狀態。

更新功能數據表的程式代碼會使用 mode='merge'，如下列範例所示。

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()

customer_features_df = compute_customer_features(data)

fe.write_table(
  df=customer_features_df,
  name='ml.recommender_system.customer_features',
  mode='merge'
)

儲存每日功能的過去值

使用複合主鍵定義功能數據表。 在主鍵中包含日期。 例如，針對功能數據表 customer_features，您可以使用複合主鍵 （date、 customer_id） 和數據分割索引鍵 date ，以有效率地讀取。

Databricks sql

CREATE TABLE ml.recommender_system.customer_features (
  customer_id int NOT NULL,
  `date` date NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (`date`, customer_id)
)
PARTITIONED BY (`date`)
COMMENT "Customer features";

Python

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
fe.create_table(
  name='ml.recommender_system.customer_features',
  primary_keys=['date', 'customer_id'],
  partition_columns=['date'],
  schema=customer_features_df.schema,
  description='Customer features'
)

然後，您可以建立程式代碼，以從功能數據表篩選 date 讀取到感興趣的時間週期。

您也可以建立時間序列功能數據表，以在使用 或score_batch時create_training_set啟用時間點查閱。 請參閱 在 Unity 目錄中建立功能數據表。

若要讓功能數據表保持最新狀態，請設定定期排程的作業，以將功能或將新的特徵值串流至功能數據表。

建立串流功能計算管線以更新功能

若要建立串流功能計算管線，請將串流 DataFrame 當做自變數傳遞至 write_table。 這個方法會傳 StreamingQuery 回物件。

def compute_additional_customer_features(data):
  ''' Returns Streaming DataFrame
  '''
  pass

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()

customer_transactions = spark.readStream.load("dbfs:/events/customer_transactions")
stream_df = compute_additional_customer_features(customer_transactions)

fe.write_table(
  df=stream_df,
  name='ml.recommender_system.customer_features',
  mode='merge'
)

從 Unity 目錄中的功能資料表讀取

用來 read_table 讀取特徵值。

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
customer_features_df = fe.read_table(
  name='ml.recommender_system.customer_features',
)

在 Unity 目錄中搜尋和瀏覽功能資料表

使用功能 UI 來搜尋或流覽 Unity 目錄中的功能數據表。

  1. 按兩下 功能存放區圖示提要欄位中的 [功能 ] 以顯示 [功能 UI]。

  2. 選取具有目錄選取器的目錄，以檢視該目錄中所有可用的功能數據表。 在搜尋方塊中，輸入功能數據表、功能或批注的所有或部分名稱。 您也可以輸入標記的所有或部分 索引鍵或值。 搜尋文字不區分大小寫。

    功能搜尋範例

取得 Unity 目錄中功能數據表的元數據

使用 get_table 來取得功能數據表元數據。

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
ft = fe.get_table(name="ml.recommender_system.user_feature_table")
print(ft.features)

在 Unity 目錄中搭配功能數據表和功能使用標籤

您可以使用簡單的索引鍵/值組標記來分類和管理功能數據表和功能。

針對功能數據表，您可以使用目錄總管、筆記本或 SQL 查詢編輯器中的 SQL 語句，或功能工程 Python API 來建立、編輯和刪除標記。

針對功能，您可以在筆記本或 SQL 查詢編輯器中使用目錄總管或 SQL 語句來建立、編輯和刪除標籤。

請參閱 將標籤套用至 Unity 目錄安全性實體物件 和 Python API。

下列範例示範如何使用功能工程 Python API 來建立、更新和刪除功能數據表標記。

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()

# Create feature table with tags
customer_feature_table = fe.create_table(
  # ...
  tags={"tag_key_1": "tag_value_1", "tag_key_2": "tag_value_2", ...},
  # ...
)

# Upsert a tag
fe.set_feature_table_tag(name="customer_feature_table", key="tag_key_1", value="new_key_value")

# Delete a tag
fe.delete_feature_table_tag(name="customer_feature_table", key="tag_key_2")

刪除 Unity 目錄中的功能資料表

您可以使用目錄總管或使用 功能工程 Python API，直接刪除 Unity 目錄中的 Delta 資料表，以刪除 Unity 目錄中的功能數據表。

注意

  • 刪除功能數據表可能會導致上游生產者和下游取用者發生非預期的失敗（模型、端點和排程作業）。 您必須使用雲端提供者刪除已發佈的在線商店。
  • 當您刪除 Unity 目錄中的功能資料表時，也會卸除基礎 Delta 資料表。
  • drop_table Databricks Runtime 13.1 ML 或以下版本不支援。 使用 SQL 命令來刪除資料表。

您可以使用 Databricks SQL，或 FeatureEngineeringClient.drop_table 刪除 Unity 目錄中的功能數據表：

Databricks sql

DROP TABLE ml.recommender_system.customer_features;

Python

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
fe.drop_table(
  name='ml.recommender_system.customer_features'
)