Příprava funkcí v katalogu Unity

Článek
04/23/2024

Tato stránka popisuje, jak vytvořit tabulky funkcí a pracovat s tabulkami funkcí v katalogu Unity.

Tato stránka se vztahuje pouze na pracovní prostory, které jsou povolené pro katalog Unity. Pokud pro katalog Unity není povolený váš pracovní prostor, přečtěte si téma Práce s funkcemi v úložišti funkcí pracovního prostoru.

Požadavky

Příprava funkcí v katalogu Unity vyžaduje Databricks Runtime 13.2 nebo vyšší. Metastore katalogu Unity navíc musí mít model oprávnění verze 1.0.

Instalace přípravy funkcí v klientovi Python katalogu Unity

Příprava funkcí v katalogu Unity poskytuje klienta FeatureEngineeringClientPythonu . Třída je k dispozici v PyPI s balíčkem databricks-feature-engineering a je předinstalovaná v Databricks Runtime 13.2 ML a vyšší. Pokud používáte modul runtime databricks bez ML, musíte klienta nainstalovat ručně. Pomocí matice kompatibility vyhledejte správnou verzi pro vaši verzi Databricks Runtime.

%pip install databricks-feature-engineering

dbutils.library.restartPython()

Vytvoření katalogu a schématu pro tabulky funkcí v katalogu Unity

Musíte vytvořit nový katalog nebo použít existující katalog pro tabulky funkcí.

Pokud chcete vytvořit nový katalog, musíte mít CREATE CATALOG oprávnění k metastoru.

CREATE CATALOG IF NOT EXISTS <catalog-name>

Pokud chcete použít existující katalog, musíte mít USE CATALOG oprávnění k katalogu.

USE CATALOG <catalog-name>

Tabulky funkcí v katalogu Unity musí být uložené ve schématu. Pokud chcete vytvořit nové schéma v katalogu, musíte mít CREATE SCHEMA oprávnění k katalogu.

CREATE SCHEMA IF NOT EXISTS <schema-name>

Vytvoření tabulky funkcí v katalogu Unity

Poznámka:

Existující tabulku Delta v katalogu Unity můžete použít jako tabulku funkcí. Viz Použití existující tabulky Delta v Katalogu Unity jako tabulky funkcí.

Jako tabulku funkcí můžete také použít existující tabulku Delta Live Table v katalogu Unity. Viz Použití existující streamované tabulky nebo materializovaného zobrazení vytvořeného kanálem Delta Live Tables jako tabulky funkcí.

Tabulky funkcí v katalogu Unity jsou tabulky Delta nebo Tabulky Delta Live spravované katalogem Unity. Tabulky funkcí musí mít primární klíč. Název tabulky funkcí v katalogu Unity má tříúrovňovou strukturu . <catalog-name>.<schema-name>.<table-name>

Databricks SQL nebo Python FeatureEngineeringClient můžete použít k vytvoření tabulek Delta funkcí v katalogu Unity. Kanály Delta Live Tables můžete použít k vytvoření funkce Delta Live Tables v katalogu Unity.

Databricks SQL

Jako tabulku funkcí můžete použít libovolnou tabulku Delta s omezením primárního klíče. Následující kód ukazuje, jak vytvořit tabulku s primárním klíčem:

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)
);

Pokud chcete vytvořit tabulku funkcí časových řad, přidejte sloupec času jako sloupec primárního klíče a zadejte klíčové slovo TIMESERIES . Klíčové slovo TIMESERIES vyžaduje Databricks Runtime 13.3 LTS nebo vyšší.

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)
);

Po vytvoření tabulky můžete do ní zapisovat data stejným způsobem, jakým píšete jiné tabulky Delta, a můžete je použít jako tabulku funkcí.

Python

Podrobnosti o příkazech a parametrech použitých v následujících příkladech najdete v referenčních informacích k rozhraní API Pythonu pro přípravu funkcí.

Napište funkce Pythonu pro výpočet funkcí. Výstupem každé funkce by měl být datový rámec Apache Spark s jedinečným primárním klíčem. Primární klíč se může skládat z jednoho nebo více sloupců.
Vytvořte tabulku funkcí vytvořením instance a FeatureEngineeringClient použití create_table.
Naplňte tabulku funkcí pomocí write_tablefunkce .

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',
#   ...
# )

Živé tabulky Delta

Poznámka:

Omezení tabulek u dynamických tabulek Delta jsou ve verzi Public Preview. Následující příklady kódu musí být spuštěny pomocí kanálu náhledu Delta Live Tables.

Jako tabulku funkcí můžete použít libovolnou tabulku Delta Live s omezením primárního klíče. Následující kód ukazuje, jak vytvořit Delta Live Table s primárním klíčem:

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 ...;

Pokud chcete vytvořit tabulku funkcí časových řad, přidejte sloupec času jako sloupec primárního klíče a zadejte klíčové slovo 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 ...;

Po vytvoření tabulky můžete do ní zapisovat data stejným způsobem, jakým píšete jiné tabulky Delta Live, a můžete je použít jako tabulku funkcí.

Omezení tabulek pro rozdílové živé tabulky jsou podporována pouze v SQL. Pokud chcete nastavit primární klíče pro dynamické tabulky Delta, které byly deklarovány v Pythonu, přečtěte si téma Použití existující streamované tabulky nebo materializovaného zobrazení vytvořeného kanálem Delta Live Tables jako tabulkou funkcí.

Použití existující tabulky Delta v katalogu Unity jako tabulky funkcí

Libovolná tabulka Delta v katalogu Unity s primárním klíčem může být tabulka funkcí v katalogu Unity a s tabulkou můžete použít uživatelské rozhraní Funkcí a rozhraní API.

Poznámka:

Omezení primárního klíče může deklarovat pouze vlastník tabulky. Jméno vlastníka se zobrazí na stránce podrobností tabulky v Průzkumníku katalogu.
Ověřte, že je datový typ v tabulce Delta podporován technikou funkcí v katalogu Unity. Viz Podporované datové typy.
Klíčové slovo TIMESERIES vyžaduje Databricks Runtime 13.3 LTS nebo vyšší.

Pokud existující tabulka Delta nemá omezení primárního klíče, můžete ji vytvořit následujícím způsobem:

Nastavte sloupce primárního klíče na NOT NULLhodnotu . Pro každý sloupec primárního klíče spusťte:
```
ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL
```
Upravte tabulku tak, aby se přidalo omezení primárního klíče:
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1, pk_col2, ...)
```
pk_name je název omezení primárního klíče. Podle konvence můžete použít název tabulky (bez schématu a katalogu) s příponou _pk . Tabulka s názvem "ml.recommender_system.customer_features" by měla customer_features_pk například název omezení primárního klíče.

Pokud chcete vytvořit tabulku funkcí časové řady, zadejte klíčové slovo TIMESERIES na jednom ze sloupců primárního klíče následujícím způsobem:
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1 TIMESERIES, pk_col2, ...)
```
Po přidání omezení primárního klíče do tabulky se tabulka zobrazí v uživatelském rozhraní funkcí a můžete ji použít jako tabulku funkcí.

Použití existující streamované tabulky nebo materializovaného zobrazení vytvořeného kanálem Delta Live Tables jako tabulky funkcí

Jakákoli streamovaná tabulka nebo materializované zobrazení v katalogu Unity s primárním klíčem může být tabulka funkcí v katalogu Unity a můžete použít uživatelské rozhraní Funkcí a rozhraní API s tabulkou.

Poznámka:

Omezení tabulek u dynamických tabulek Delta jsou ve verzi Public Preview. Následující příklady kódu musí být spuštěny pomocí kanálu náhledu Delta Live Tables.
Omezení primárního klíče může deklarovat pouze vlastník tabulky. Jméno vlastníka se zobrazí na stránce podrobností tabulky v Průzkumníku katalogu.
Ověřte, jestli je datový typ v tabulce Delta podporován technikou funkcí v katalogu Unity. Viz Podporované datové typy.

Přidání primárního klíče do tabulky streamování nebo materializovaného zobrazení vytvořeného pomocí SQL

Pokud chcete nastavit primární klíče pro existující streamovací tabulku nebo materializované zobrazení, které se vytvořilo pomocí SQL, aktualizujte schéma streamované tabulky nebo materializovaného zobrazení v poznámkovém bloku, které tabulku spravuje. Potom aktualizujte tabulku pro omezení, která se má použít v katalogu Unity.

Kód by měl být podobný následujícímu:

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

Přidání primárního klíče do streamované tabulky nebo materializovaného zobrazení vytvořeného pomocí Pythonu

Pokud chcete vytvořit primární klíče pro existující streamovanou tabulku nebo materializované zobrazení vytvořené kanálem Delta Live Tables, musíte použít SQL, i když byla streamovaná tabulka nebo materializované zobrazení vytvořené pomocí Pythonu. Vytvořte nový poznámkový blok SQL pro definování nové tabulky streamování nebo materializovaného zobrazení, které čte z existující tabulky. Potom poznámkový blok spusťte jako krok existujícího kanálu Delta Live Tables nebo v novém kanálu.

Nový poznámkový blok SQL by měl obsahovat kód podobný následujícímu:

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

Řízení přístupu k tabulkám funkcí v katalogu Unity

Řízení přístupu pro tabulky funkcí v katalogu Unity je spravováno katalogem Unity. Viz oprávnění katalogu Unity.

Aktualizace tabulky funkcí v katalogu Unity

Tabulku funkcí v katalogu Unity můžete aktualizovat přidáním nových funkcí nebo úpravou konkrétních řádků na základě primárního klíče.

Následující metadata tabulky funkcí by se neměla aktualizovat:

Primární klíč.
Klíč oddílu.
Název nebo datový typ existující funkce

Změna způsobí přerušení podřízených kanálů, které používají funkce pro trénování a obsluhu modelů.

Přidání nových funkcí do existující tabulky funkcí v katalogu Unity

Nové funkce můžete do existující tabulky funkcí přidat jedním ze dvou způsobů:

Aktualizujte stávající výpočetní funkci funkce a spusťte write_table vrácený datový rámec. Tím se aktualizuje schéma tabulky funkcí a sloučí se nové hodnoty funkcí na základě primárního klíče.
Vytvořte novou výpočetní funkci funkce pro výpočet nových hodnot funkcí. Datový rámec vrácený touto novou výpočetní funkcí musí obsahovat primární klíče tabulek funkcí a klíče oddílů (pokud jsou definovány). Spuštěním write_table datového rámce zapište nové funkce do existující tabulky funkcí pomocí stejného primárního klíče.

Aktualizace pouze konkrétních řádků v tabulce funkcí

Použít mode = "merge" v write_table. Řádky, jejichž primární klíč v datovém rámci odeslaném write_table ve volání neexistuje, zůstanou beze změny.

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

Naplánování úlohy pro aktualizaci tabulky funkcí

Aby funkce v tabulkách funkcí vždy měly nejnovější hodnoty, doporučuje Databricks vytvořit úlohu , která spouští poznámkový blok, aby pravidelně aktualizovala tabulku funkcí, například každý den. Pokud už máte neplánovaná úloha vytvořená, můžete ji převést na naplánovanou úlohu , abyste měli jistotu, že jsou hodnoty funkcí vždy aktuální.

Kód pro aktualizaci tabulky funkcí používá mode='merge', jak je znázorněno v následujícím příkladu.

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'
)

Ukládání minulých hodnot denních funkcí

Definujte tabulku funkcí se složeným primárním klíčem. Zahrňte datum do primárního klíče. Například pro tabulku customer_featuresfunkcí můžete pro efektivní čtení použít složený primární klíč (date, customer_id) a klíč date oddílu.

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'
)

Pak můžete vytvořit kód pro čtení z filtrování date tabulky funkcí do časového období zájmu.

Můžete také vytvořit tabulku funkcí časových řad, která umožňuje vyhledávání k určitému bodu v čase při použití create_training_set nebo score_batch. Viz Vytvoření tabulky funkcí v katalogu Unity.

Pokud chcete tabulku funkcí udržovat v aktualizovaném stavu, nastavte pravidelně naplánovanou úlohu pro zápis funkcí nebo streamujte nové hodnoty funkcí do tabulky funkcí.

Vytvoření výpočetního kanálu funkce streamování pro aktualizaci funkcí

Pokud chcete vytvořit výpočetní kanál funkce streamování, předejte streamování DataFrame jako argument .write_table Tato metoda vrátí StreamingQuery objekt.

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'
)

Čtení z tabulky funkcí v katalogu Unity

Slouží read_table ke čtení hodnot funkcí.

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

Vyhledávání a procházení tabulek funkcí v katalogu Unity

Pomocí uživatelského rozhraní funkcí můžete vyhledávat nebo procházet tabulky funkcí v katalogu Unity.

Kliknutím na Funkce na bočním panelu zobrazíte uživatelské rozhraní funkcí.
Výběrem katalogu selektorem katalogu zobrazíte všechny dostupné tabulky funkcí v daném katalogu. Do vyhledávacího pole zadejte celý název tabulky funkcí, funkce nebo komentář nebo jeho část. Můžete také zadat celý klíč nebo část klíče nebo hodnoty značky. Hledaný text nerozlišuje velká a malá písmena.

Získání metadat tabulek funkcí v katalogu Unity

Slouží get_table k získání metadat tabulky funkcí.

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

Použití značek s tabulkami funkcí a funkcemi v katalogu Unity

Značky, které jsou jednoduché páry klíč-hodnota, můžete použít ke kategorizaci a správě tabulek a funkcí funkcí.

V případě tabulek funkcí můžete vytvářet, upravovat a odstraňovat značky pomocí uživatelského rozhraní Průzkumníka katalogu, Databricks SQL nebo rozhraní Python API pro přípravu funkcí.

Pro funkce můžete vytvářet, upravovat a odstraňovat značky pomocí uživatelského rozhraní Průzkumníka katalogu nebo Databricks SQL.

Následující příklad ukazuje, jak pomocí rozhraní API Pythonu pro přípravu funkcí vytvářet, aktualizovat a odstraňovat značky tabulek funkcí.

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")

Odstranění tabulky funkcí v katalogu Unity

Tabulku funkcí v katalogu Unity můžete odstranit přímo odstraněním tabulky Delta v katalogu Unity pomocí Průzkumníka katalogu nebo pomocí rozhraní Python API pro přípravu funkcí.

Poznámka:

Odstranění tabulky funkcí může vést k neočekávaným chybám v nadřazených producentech a podřízených konzumentech (modely, koncové body a plánované úlohy). U poskytovatele cloudu musíte odstranit publikovaná online úložiště.
Když odstraníte tabulku funkcí v katalogu Unity, odstraní se také podkladová tabulka Delta.
drop_table Databricks Runtime 13.1 ML nebo níže se nepodporuje. K odstranění tabulky použijte příkaz SQL.

Databricks SQL nebo FeatureEngineeringClient.drop_table můžete odstranit tabulku funkcí v katalogu 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'
)

Příprava funkcí v katalogu Unity

Požadavky

Instalace přípravy funkcí v klientovi Python katalogu Unity

Vytvoření katalogu a schématu pro tabulky funkcí v katalogu Unity

Vytvoření tabulky funkcí v katalogu Unity

Databricks SQL

Python

Živé tabulky Delta

Použití existující tabulky Delta v katalogu Unity jako tabulky funkcí

Použití existující streamované tabulky nebo materializovaného zobrazení vytvořeného kanálem Delta Live Tables jako tabulky funkcí

Přidání primárního klíče do tabulky streamování nebo materializovaného zobrazení vytvořeného pomocí SQL

Přidání primárního klíče do streamované tabulky nebo materializovaného zobrazení vytvořeného pomocí Pythonu

Řízení přístupu k tabulkám funkcí v katalogu Unity

Aktualizace tabulky funkcí v katalogu Unity

Přidání nových funkcí do existující tabulky funkcí v katalogu Unity

Aktualizace pouze konkrétních řádků v tabulce funkcí

Naplánování úlohy pro aktualizaci tabulky funkcí

Ukládání minulých hodnot denních funkcí

Databricks SQL

Python

Vytvoření výpočetního kanálu funkce streamování pro aktualizaci funkcí

Čtení z tabulky funkcí v katalogu Unity

Vyhledávání a procházení tabulek funkcí v katalogu Unity

Získání metadat tabulek funkcí v katalogu Unity

Použití značek s tabulkami funkcí a funkcemi v katalogu Unity

Odstranění tabulky funkcí v katalogu Unity

Databricks SQL

Python

Další materiály