Arbeta med funktionstabeller

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 din arbetsyta inte är aktiverad för Unity Catalog läser du Arbeta med funktionstabeller i funktionsarkivet för arbetsytan.

Mer information om de kommandon och parametrar som används i exemplen på den här sidan finns i referensen för Python API för funktionsutveckling.

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

Funktionsteknik i Unity Catalog har en Python-klient FeatureEngineeringClient. Klassen är tillgänglig på PyPI med databricks-feature-engineering paketet och är förinstallerad i Databricks Runtime 13.3 LTS 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

Funktionstabeller i Unity Catalog är Delta-tabeller. Funktionstabeller måste ha en primärnyckel. Funktionstabeller, liksom andra datatillgångar i Unity Catalog, nås med hjälp av ett namnområde på tre nivåer: <catalog-name>.<schema-name>.<table-name>.

Du kan använda Databricks SQL, Python FeatureEngineeringClienteller en Delta Live Tables-pipeline för att skapa funktionstabeller i Unity Catalog.

Databricks SQL

Du kan använda valfri Delta-tabell med en primärnyckelbegränsning som 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 som 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.

1. 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.
2. Skapa en funktionstabell genom att instansiera en FeatureEngineeringClient och använda create_table.
3. 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',
#   ...
# )

Skapa en funktionstabell i Unity Catalog med Delta Live Tables-pipeline

Alla tabeller som publiceras från en Delta Live Tables-pipeline som innehåller en primärnyckelbegränsning kan användas som en funktionstabell. Om du vill skapa en tabell i en Delta Live Tables-pipeline med en primärnyckel kan du använda antingen Databricks SQL eller Python-programmeringsgränssnittet Delta Live Tables.

Om du vill skapa en tabell i en Delta Live Tables-pipeline med en primärnyckel använder du följande syntax:

Databricks SQL

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

Python

import dlt

@dlt.table(
  schema="""
          customer_id int NOT NULL,
          feat1 long,
          feat2 varchar(100),
          CONSTRAINT customer_features_pk PRIMARY KEY (customer_id)
    """)
def customer_features():
  return ...

Om du vill skapa en funktionstabell för tidsserier lägger du till en tidskolumn som primärnyckelkolumn och anger nyckelordet TIMESERIES .

Databricks SQL

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

Python

import dlt

@dlt.table(
  schema="""
    customer_id int NOT NULL,
    ts timestamp NOT NULL,
    feat1 long,
    feat2 varchar(100),
    CONSTRAINT customer_features_pk PRIMARY KEY (customer_id, ts TIMESERIES)
    """)
def customer_features():
  return ...

När tabellen har skapats kan du skriva data till den som andra Delta Live Tables-datauppsättningar, och de kan användas 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.

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

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

2. Ändra tabellen för att lägga till den primära nyckelbegränsningen:

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

   pk_name är namnet på den primära nyckelbegränsningen. Enligt konventionen kan du använda tabellnamnet (utan schema och katalog) med ett _pk suffix. En tabell med namnet "ml.recommender_system.customer_features" skulle till exempel ha customer_features_pk som namn på den primära nyckelbegränsningen.

   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 den primära nyckelbegränsningen i tabellen visas tabellen i användargränssnittet för funktioner och du kan använda den som en funktionstabell.

Använda en strömmande tabell 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.

Om du vill ange primära nycklar för en befintlig strömmande tabell eller materialiserad vy uppdaterar du schemat för den strömmande tabellen eller den materialiserade vyn i anteckningsboken som hanterar objektet. Uppdatera sedan tabellen för att uppdatera Unity Catalog-objektet.

Följande är syntaxen för att lägga till en primärnyckel i en materialiserad vy:

Databricks SQL

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

Python

import dlt

@dlt.table(
  schema="""
    id int NOT NULL PRIMARY KEY,
    ...
    """
)
def existing_live_table():
  return ...

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 dataram 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 säkerställa att funktionsvärdena alltid är uppdaterade. Se Schemalägg och samordna arbetsflöden.

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 rekommenderar att du aktiverar flytande klustring i tabellen för effektiva läsningar. Om du inte använder flytande klustring anger du datumkolumnen som en partitionsnyckel för bättre läsprestanda.

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)
)
-- If you are not using liquid clustering, uncomment the following line.
-- 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'],
  # If you are not using liquid clustering, uncomment the following line.
  # 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ömma 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.table("prod.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.

1. Klicka på Funktioner i sidopanelen för att visa användargränssnittet för funktioner.

2. 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 Catalog Explorer, SQL-instruktioner i en notebook- eller SQL-frågeredigerare eller Python API för funktionsutveckling.

För funktioner kan du skapa, redigera och ta bort taggar med hjälp av Catalog Explorer- eller SQL-instruktioner i en notebook- eller SQL-frågeredigerare.

Se Tillämpa taggar på skyddsbara objekt i Unity Catalog och Funktionsutveckling och Funktionslager för arbetsyta Python API.

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.

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

Dela en funktionstabell i Unity Catalog mellan arbetsytor eller konton

En funktionstabell i Unity Catalog är tillgänglig för alla arbetsytor som tilldelats tabellens Unity Catalog-metaarkiv.

Om du vill dela en funktionstabell med arbetsytor som inte är tilldelade till samma Unity Catalog-metaarkiv använder du Deltadelning.