Funktionsteknik i Unity-katalogen

Artikel
04/23/2024

Den här sidan beskriver hur du skapar och arbetar med funktionstabeller i Unity Catalog.

Den här sidan gäller endast för arbetsytor som är aktiverade för Unity Catalog. Om arbetsytan inte är aktiverad för Unity Catalog kan du läsa Arbeta med funktioner i Arbetsytans funktionslager.

Krav

Funktionsteknik i Unity Catalog kräver Databricks Runtime 13.2 eller senare. Dessutom måste Unity Catalog-metaarkivet ha privilege model version 1.0.

Installera funktionsteknik i Unity Catalog Python-klienten

Funktionsutveckling i Unity Catalog tillhandahåller en Python-klient FeatureEngineeringClient. Klassen är tillgänglig på PyPI med databricks-feature-engineering paketet och är förinstallerad i Databricks Runtime 13.2 ML och senare. Om du använder en databricks-körning som inte är ML måste du installera klienten manuellt. Använd kompatibilitetsmatrisen för att hitta rätt version för din Databricks Runtime-version.

%pip install databricks-feature-engineering

dbutils.library.restartPython()

Skapa en katalog och ett schema för funktionstabeller i Unity Catalog

Du måste skapa en ny katalog eller använda en befintlig katalog för funktionstabeller.

Om du vill skapa en ny katalog måste du ha behörigheten CREATE CATALOG för metaarkivet.

CREATE CATALOG IF NOT EXISTS <catalog-name>

Om du vill använda en befintlig katalog måste du ha behörigheten USE CATALOG för katalogen.

USE CATALOG <catalog-name>

Funktionstabeller i Unity Catalog måste lagras i ett schema. Om du vill skapa ett nytt schema i katalogen måste du ha behörigheten CREATE SCHEMA för katalogen.

CREATE SCHEMA IF NOT EXISTS <schema-name>

Skapa en funktionstabell i Unity Catalog

Kommentar

Du kan använda en befintlig Delta-tabell i Unity Catalog som en funktionstabell. Se Använda en befintlig Delta-tabell i Unity Catalog som en funktionstabell.

Du kan också använda en befintlig Delta Live Table i Unity Catalog som en funktionstabell. Se Använda en befintlig strömmande tabell eller materialiserad vy som skapats av en Delta Live Tables-pipeline som en funktionstabell.

Funktionstabeller i Unity Catalog är Delta-tabeller eller Delta Live Tables som hanteras av Unity Catalog. Funktionstabeller måste ha en primärnyckel. Namnet på en funktionstabell i Unity Catalog har en struktur på tre nivåer, <catalog-name>.<schema-name>.<table-name>.

Du kan använda Databricks SQL eller Python FeatureEngineeringClient för att skapa deltatabeller för funktioner i Unity Catalog. Du kan använda Delta Live Tables-pipelines för att skapa funktionen Delta Live Tables i Unity Catalog.

Databricks sql

Du kan använda valfri Delta-tabell med en primärnyckelbegränsning som en funktionstabell. Följande kod visar hur du skapar en tabell med en primärnyckel:

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

Om du vill skapa en funktionstabell för tidsserier lägger du till en tidskolumn som primärnyckelkolumn och anger nyckelordet TIMESERIES . Nyckelordet TIMESERIES kräver Databricks Runtime 13.3 LTS eller senare.

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

När tabellen har skapats kan du skriva data till den på samma sätt som du skriver andra Delta-tabeller och den kan användas som en funktionstabell.

Python

Mer information om kommandon och parametrar som används i följande exempel finns i referensen för Python API för funktionsutveckling.

Skriv Python-funktionerna för att beräkna funktionerna. Utdata för varje funktion ska vara en Apache Spark DataFrame med en unik primärnyckel. Primärnyckeln kan bestå av en eller flera kolumner.
Skapa en funktionstabell genom att instansiera en FeatureEngineeringClient och använda create_table.
Fyll i funktionstabellen med .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 live-tabeller

Kommentar

Tabellbegränsningar för Delta Live Tables finns i offentlig förhandsversion. Följande kodexempel måste köras med förhandsgranskningskanalen Delta Live Tables.

Du kan använda valfri Delta Live Table med en primärnyckelbegränsning som en funktionstabell. Följande kod visar hur du skapar en Delta Live Table med en primärnyckel:

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

Om du vill skapa en funktionstabell för tidsserier lägger du till en tidskolumn som primärnyckelkolumn och anger nyckelordet 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 ...;

När tabellen har skapats kan du skriva data till den på samma sätt som du skriver andra Delta Live Tables och den kan användas som en funktionstabell.

Tabellbegränsningar för Delta Live Tables stöds endast i SQL. Om du vill ange primära nycklar för Delta Live Tables som har deklarerats i Python läser du Använda en befintlig strömmande tabell eller materialiserad vy som skapats av en Delta Live Tables-pipeline som en funktionstabell.

Använda en befintlig Delta-tabell i Unity Catalog som en funktionstabell

Alla Delta-tabeller i Unity Catalog med en primärnyckel kan vara en funktionstabell i Unity Catalog, och du kan använda funktionsgränssnittet och API:et med tabellen.

Kommentar

Endast tabellägaren kan deklarera restriktioner för primärnyckel. Ägarens namn visas på tabellinformationssidan i Katalogutforskaren.
Kontrollera att datatypen i Delta-tabellen stöds av Funktionsteknik i Unity Catalog. Se Datatyper som stöds.
Nyckelordet TIMESERIES kräver Databricks Runtime 13.3 LTS eller senare.

Om en befintlig Delta-tabell inte har någon primärnyckelbegränsning kan du skapa en på följande sätt:

Ange primärnyckelkolumner till NOT NULL. Kör för varje primärnyckelkolumn:
```
ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL
```
Ändra tabellen för att lägga till primärnyckelvillkoret:
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1, pk_col2, ...)
```
pk_name är namnet på restriktionen för primärnyckel. Enligt konventionen kan du använda tabellnamnet (utan schema och katalog) med ett _pk suffix. Till exempel skulle en tabell med namnet "ml.recommender_system.customer_features" ha customer_features_pk som namn på dess primärnyckelvillkor.

Om du vill göra tabellen till en funktionstabell för tidsserier anger du nyckelordet TIMESERIES i en av primärnyckelkolumnerna enligt följande:
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1 TIMESERIES, pk_col2, ...)
```
När du har lagt till primärnyckelbegränsningen i tabellen visas tabellen i funktionsgränssnittet och du kan använda den som en funktionstabell.

Använda en befintlig direktuppspelningstabell eller materialiserad vy som skapats av en Delta Live Tables-pipeline som en funktionstabell

Alla strömmande tabeller eller materialiserade vyer i Unity Catalog med en primärnyckel kan vara en funktionstabell i Unity Catalog, och du kan använda funktionsgränssnittet och API:et med tabellen.

Kommentar

Tabellbegränsningar för Delta Live Tables finns i offentlig förhandsversion. Följande kodexempel måste köras med förhandsgranskningskanalen Delta Live Tables.
Endast tabellägaren kan deklarera restriktioner för primärnyckel. Ägarens namn visas på tabellinformationssidan i Katalogutforskaren.
Kontrollera att datatypen i Delta-tabellen stöds av Funktionsteknik i Unity Catalog. Se Datatyper som stöds.

Lägg till primärnyckel i en direktuppspelningstabell eller materialiserad vy som skapades med SQL

Om du vill ange primära nycklar för en befintlig strömmande tabell eller materialiserad vy som skapades med SQL uppdaterar du schemat för den strömmande tabellen eller den materialiserade vyn i notebook-filen som hanterar tabellen. Uppdatera sedan tabellen för villkoret som ska tillämpas i Unity Catalog.

Koden bör likna följande:

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

Lägg till primärnyckel i en strömmande tabell eller materialiserad vy som skapades med Python

Om du vill skapa primära nycklar för en befintlig strömmande tabell eller materialiserad vy som skapades av en Delta Live Tables-pipeline måste du använda SQL, även om den strömmande tabellen eller den materialiserade vyn skapades med Python. Skapa en ny SQL-notebook-fil för att definiera en ny strömmande tabell eller materialiserad vy som läser från den befintliga. Kör sedan notebook-filen som ett steg i den befintliga Delta Live Tables-pipelinen eller i en ny pipeline.

Den nya SQL-notebook-filen bör innehålla kod som liknar följande:

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

Kontrollera åtkomsten till funktionstabeller i Unity Catalog

Åtkomstkontroll för funktionstabeller i Unity Catalog hanteras av Unity Catalog. Se Behörigheter för Unity-katalogen.

Uppdatera en funktionstabell i Unity Catalog

Du kan uppdatera en funktionstabell i Unity Catalog genom att lägga till nya funktioner eller genom att ändra specifika rader baserat på primärnyckeln.

Följande metadata för funktionstabellen bör inte uppdateras:

Primär nyckel.
Partitionsnyckel.
Namn eller datatyp för en befintlig funktion.

Om du ändrar dem bryts nedströmspipelines som använder funktioner för träning och servering av modeller.

Lägga till nya funktioner i en befintlig funktionstabell i Unity Catalog

Du kan lägga till nya funktioner i en befintlig funktionstabell på något av två sätt:

Uppdatera den befintliga funktionen för funktionsberäkning och kör write_table med den returnerade DataFrame. Detta uppdaterar funktionstabellschemat och sammanfogar nya funktionsvärden baserat på primärnyckeln.
Skapa en ny funktionsberäkningsfunktion för att beräkna de nya funktionsvärdena. Den DataFrame som returneras av den nya beräkningsfunktionen måste innehålla funktionstabellernas primära nycklar och partitionsnycklar (om den definieras). Kör write_table med DataFrame för att skriva de nya funktionerna till den befintliga funktionstabellen med samma primärnyckel.

Uppdatera endast specifika rader i en funktionstabell

Använd mode = "merge" i write_table. Rader vars primärnyckel inte finns i dataramen som skickades i anropet write_table förblir oförändrade.

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

Schemalägga ett jobb för att uppdatera en funktionstabell

För att säkerställa att funktioner i funktionstabeller alltid har de senaste värdena rekommenderar Databricks att du skapar ett jobb som kör en notebook-fil för att regelbundet uppdatera funktionstabellen, till exempel varje dag. Om du redan har skapat ett icke-schemalagt jobb kan du konvertera det till ett schemalagt jobb för att se till att funktionsvärdena alltid är uppdaterade.

Kod för att uppdatera en funktionstabell använder mode='merge', som visas i följande exempel.

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

Lagra tidigare värden för dagliga funktioner

Definiera en funktionstabell med en sammansatt primärnyckel. Inkludera datumet i primärnyckeln. För en funktionstabell customer_featureskan du till exempel använda en sammansatt primärnyckel (date, customer_id) och partitionsnyckel date för effektiva läsningar.

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

Du kan sedan skapa kod som ska läsas från funktionstabellfiltreringen date till den aktuella tidsperioden.

Du kan också skapa en funktionstabell för tidsserier som aktiverar uppslag till tidpunkt när du använder create_training_set eller score_batch. Se Skapa en funktionstabell i Unity Catalog.

För att hålla funktionstabellen uppdaterad konfigurerar du ett regelbundet schemalagt jobb för att skriva funktioner eller strömmar nya funktionsvärden till funktionstabellen.

Skapa en pipeline för strömningsfunktionsberäkning för att uppdatera funktioner

Om du vill skapa en pipeline för strömningsfunktionsberäkning skickar du en strömning DataFrame som ett argument till write_table. Den här metoden returnerar ett 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'
)

Läsa från en funktionstabell i Unity Catalog

Använd read_table för att läsa funktionsvärden.

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

Sök och bläddra bland funktionstabeller i Unity Catalog

Använd funktionsgränssnittet för att söka efter eller bläddra bland funktionstabeller i Unity Catalog.

Klicka på Funktioner i sidopanelen för att visa användargränssnittet för funktioner.
Välj katalog med katalogväljaren för att visa alla tillgängliga funktionstabeller i katalogen. I sökrutan anger du hela eller en del av namnet på en funktionstabell, en funktion eller en kommentar. Du kan också ange hela eller en del av nyckeln eller värdet för en tagg. Söktexten är skiftlägeskänslig.

Hämta metadata för funktionstabeller i Unity Catalog

Använd get_table för att hämta metadata för funktionstabeller.

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

Använda taggar med funktionstabeller och funktioner i Unity Catalog

Du kan använda taggar, som är enkla nyckel/värde-par, för att kategorisera och hantera dina funktionstabeller och funktioner.

För funktionstabeller kan du skapa, redigera och ta bort taggar med hjälp av Katalogutforskarens användargränssnitt, Databricks SQL eller Python-API:et för funktionsutveckling.

För funktioner kan du skapa, redigera och ta bort taggar med hjälp av Katalogutforskarens användargränssnitt eller Databricks SQL.

I följande exempel visas hur du använder Python-API:et för funktionsutveckling för att skapa, uppdatera och ta bort funktionstabelltaggar.

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

Ta bort en funktionstabell i Unity Catalog

Du kan ta bort en funktionstabell i Unity Catalog genom att direkt ta bort Delta-tabellen i Unity Catalog med hjälp av Katalogutforskaren eller med hjälp av Python-API:et för funktionsutveckling.

Kommentar

Om du tar bort en funktionstabell kan det leda till oväntade fel i överordnade producenter och nedströmsanvändare (modeller, slutpunkter och schemalagda jobb). Du måste ta bort publicerade onlinebutiker med din molnleverantör.
När du tar bort en funktionstabell i Unity Catalog tas även den underliggande Delta-tabellen bort.
drop_table stöds inte i Databricks Runtime 13.1 ML eller lägre. Använd SQL-kommandot för att ta bort tabellen.

Du kan använda Databricks SQL eller FeatureEngineeringClient.drop_table för att ta bort en funktionstabell i Unity Catalog:

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

Funktionsteknik i Unity-katalogen

Krav

Installera funktionsteknik i Unity Catalog Python-klienten

Skapa en katalog och ett schema för funktionstabeller i Unity Catalog

Skapa en funktionstabell i Unity Catalog

Databricks sql

Python

Delta live-tabeller

Använda en befintlig Delta-tabell i Unity Catalog som en funktionstabell

Använda en befintlig direktuppspelningstabell eller materialiserad vy som skapats av en Delta Live Tables-pipeline som en funktionstabell

Lägg till primärnyckel i en direktuppspelningstabell eller materialiserad vy som skapades med SQL

Lägg till primärnyckel i en strömmande tabell eller materialiserad vy som skapades med Python

Kontrollera åtkomsten till funktionstabeller i Unity Catalog

Uppdatera en funktionstabell i Unity Catalog

Lägga till nya funktioner i en befintlig funktionstabell i Unity Catalog

Uppdatera endast specifika rader i en funktionstabell

Schemalägga ett jobb för att uppdatera en funktionstabell

Lagra tidigare värden för dagliga funktioner

Databricks sql

Python

Skapa en pipeline för strömningsfunktionsberäkning för att uppdatera funktioner

Läsa från en funktionstabell i Unity Catalog

Sök och bläddra bland funktionstabeller i Unity Catalog

Hämta metadata för funktionstabeller i Unity Catalog

Använda taggar med funktionstabeller och funktioner i Unity Catalog

Ta bort en funktionstabell i Unity Catalog

Databricks sql

Python

Ytterligare resurser