Delen via


Werken met functietabellen in Unity Catalog

Op deze pagina wordt beschreven hoe u functietabellen maakt en gebruikt in Unity Catalog.

Deze pagina is alleen van toepassing op werkruimten die zijn ingeschakeld voor Unity Catalog. Als uw werkruimte niet is ingeschakeld voor Unity Catalog, raadpleegt u Werken met functietabellen in werkruimtefunctiearchief (verouderd).

Zie de Feature Engineering Python API-referentievoor meer informatie over de opdrachten en parameters die worden gebruikt in de voorbeelden op deze pagina.

Vereisten

Voor functie-engineering in Unity Catalog is Databricks Runtime 13.2 of hoger vereist. Bovendien moet de Unity Catalog-metastore Privilege Model versie 1.0hebben.

Functie-engineering installeren in de Python-client van Unity Catalog

Functie-engineering in Unity Catalog heeft een Python-client FeatureEngineeringClient. De klasse is beschikbaar op PyPI met het databricks-feature-engineering pakket en is vooraf geïnstalleerd in Databricks Runtime 13.3 LTS ML en hoger. Als u een niet-ML Databricks Runtime gebruikt, moet u de client handmatig installeren. Gebruik de compatibiliteitsmatrix om de juiste versie voor uw Databricks Runtime-versie te vinden.

%pip install databricks-feature-engineering

dbutils.library.restartPython()

Een catalogus en een schema maken voor functietabellen in Unity Catalog

U moet een nieuwe catalogus maken of een bestaande catalogus gebruiken voor functietabellen.

Als u een nieuwe catalogus wilt maken, moet u de CREATE CATALOG bevoegdheid hebben voor de metastore.

CREATE CATALOG IF NOT EXISTS <catalog-name>

Als u een bestaande catalogus wilt gebruiken, moet u de bevoegdheid USE CATALOG voor de catalogus hebben.

USE CATALOG <catalog-name>

Functietabellen in Unity Catalog moeten worden opgeslagen in een schema. Als u een nieuw schema in de catalogus wilt maken, moet u de bevoegdheid CREATE SCHEMA voor de catalogus hebben.

CREATE SCHEMA IF NOT EXISTS <schema-name>

Een functietabel maken in Unity Catalog

Notitie

U kunt een bestaande Delta-tabel in Unity Catalog gebruiken die een primaire-sleutelbeperking als functietabel bevat. Als voor de tabel geen primaire sleutel is gedefinieerd, moet u de tabel bijwerken met behulp van ALTER TABLE DDL-instructies om de beperking toe te voegen. Zie Een bestaande Delta-tabel in Unity Catalog gebruiken als een functietabel.

Als u echter een primaire sleutel toevoegt aan een streamingtabel of gerealiseerde weergave die is gepubliceerd naar Unity Catalog door een Delta Live Tables-pijplijn, moet u het schema van de streamingtabel of gerealiseerde weergavedefinitie wijzigen om de primaire sleutel op te nemen en vervolgens de streamingtabel of gerealiseerde weergave te vernieuwen. Zie gebruik een streamingtabel of een gematerialiseerde weergave, gemaakt door een Delta Live Tables-pijplijn, als functietabel.

Functietabellen in Unity Catalog zijn Delta-tabellen. Functietabellen moeten een primaire sleutel hebben. Functietabellen, net als andere gegevensbronnen in Unity Catalog, worden benaderd via een drielagige naamruimte: <catalog-name>.<schema-name>.<table-name>.

U kunt Databricks SQL, de Python-FeatureEngineeringClientof een Delta Live Tables-pijplijn gebruiken om functietabellen te maken in Unity Catalog.

Databricks SQL

U kunt elke Delta-tabel gebruiken met een primaire-sleutelbeperking als functietabel. De volgende code laat zien hoe u een tabel maakt met een primaire sleutel:

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

Als u een tijdreeksfunctietabelwilt maken, voegt u een tijdkolom toe als primaire-sleutelkolom en geeft u de timeSERIES- trefwoord op. Voor het trefwoord TIMESERIES is Databricks Runtime 13.3 LTS of hoger vereist.

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

Nadat de tabel is gemaakt, kunt u gegevens naar deze tabel schrijven, zoals andere Delta-tabellen, en deze kunnen worden gebruikt als een functietabel.

Python

Zie voor details over de opdrachten en parameters die in de volgende voorbeelden worden gebruikt, de Feature Engineering Python API-referentie.

  1. Schrijf de Python-functies om de functies te berekenen. De uitvoer van elke functie moet een Apache Spark DataFrame met een unieke primaire sleutel zijn. De primaire sleutel kan bestaan uit een of meer kolommen.
  2. Maak een functietabel door een FeatureEngineeringClient te instantiëren en create_tablete gebruiken.
  3. Vul de functietabel in met behulp van 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',
#   ...
# )

Een functietabel maken in Unity Catalog met een Delta Live Tables-pijplijn

Notitie

Ondersteuning voor tabelbeperkingen in Delta Live Tables bevindt zich in publieke preview-. De volgende codevoorbeelden moeten worden uitgevoerd met behulp van het Delta Live Tables preview-kanaal.

Elke tabel die is gepubliceerd vanuit een Delta Live Tables-pijplijn met een primaire-sleutelbeperking kan worden gebruikt als een functietabel. Als u een tabel wilt maken in een Delta Live Tables-pijplijn met een primaire sleutel, kunt u Databricks SQL of de Python-programmeerinterface voor Delta Live Tablesgebruiken.

Als u een tabel wilt maken in een Delta Live Tables-pijplijn met een primaire sleutel, gebruikt u de volgende syntaxis:

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

Als u een tijdreeksfunctietabelwilt maken, voegt u een tijdkolom toe als primaire-sleutelkolom en geeft u de timeSERIES- trefwoord op.

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

Nadat de tabel is gemaakt, kunt u er gegevens naar schrijven zoals andere Delta Live Tables-gegevenssets en deze kunnen worden gebruikt als een functietabel.

Een bestaande Delta-tabel in Unity Catalog gebruiken als een functietabel

Elke Delta-tabel in Unity Catalog met een primaire sleutel kan een functietabel in Unity Catalog zijn en u kunt de gebruikersinterface en API voor functies gebruiken met de tabel.

Notitie

  • Alleen de eigenaar van de tabel kan primaire-sleutelbeperkingen declareren. De naam van de eigenaar wordt weergegeven op de tabeldetailpagina van Catalog Explorer.
  • Controleer of het gegevenstype in de Delta-tabel wordt ondersteund door Feature Engineering in Unity Catalog. Raadpleeg Ondersteunde gegevenstypen.
  • Voor het trefwoord TIMESERIES is Databricks Runtime 13.3 LTS of hoger vereist.

Als een bestaande Delta-tabel geen primaire-sleutelbeperkingheeft, kunt u er als volgt een maken:

  1. Stel primaire-sleutelkolommen in op NOT NULL. Voer voor elke primaire sleutelkolom het volgende uit:

    ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL
    
  2. Wijzig de tabel om de primaire-sleutelbeperking toe te voegen:

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

    pk_name is de naam van de primaire-sleutelbeperking. Volgens de conventie kunt u de tabelnaam (zonder schema en catalogus) gebruiken met een _pk achtervoegsel. Een tabel met de naam "ml.recommender_system.customer_features" heeft bijvoorbeeld customer_features_pk als de naam van de primaire-sleutelbeperking.

    Als u de tabel een tijdreeksfunctietabelwilt maken, geeft u het trefwoord TIMESERIES op een van de primaire-sleutelkolommen als volgt op:

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

    Nadat u de primaire-sleutelbeperking aan de tabel hebt toegevoegd, wordt de tabel weergegeven in de gebruikersinterface functies en kunt u deze gebruiken als een functietabel.

Gebruik een streamingtabel of gematerialiseerde weergave die is gecreëerd door een Delta Live Tables-pijplijn als een kenmerktabel.

Elke streamingtabel of gerealiseerde weergave in Unity Catalog met een primaire sleutel kan een functietabel in Unity Catalog zijn en u kunt de gebruikersinterface en API voor functies gebruiken met de tabel.

Notitie

  • Ondersteuning voor tabelbeperkingen in Delta Live Tables bevindt zich in publieke preview-. De volgende codevoorbeelden moeten worden uitgevoerd met behulp van het Delta Live Tables preview-kanaal.
  • Alleen de eigenaar van de tabel kan primaire-sleutelbeperkingen declareren. De naam van de eigenaar wordt weergegeven op de tabeldetailpagina van Catalog Explorer.
  • Controleer of Feature Engineering in Unity Catalog ondersteuning biedt voor het gegevenstype in de Delta-tabel. Raadpleeg Ondersteunde gegevenstypen.

Als u primaire sleutels wilt instellen voor een bestaande streamingtabel of gerealiseerde weergave, werkt u het schema van de streamingtabel of gerealiseerde weergave bij in het notebook waarmee het object wordt beheerd. Vernieuw vervolgens de tabel om het Unity Catalog-object bij te werken.

Hier volgt de syntaxis voor het toevoegen van een primaire sleutel aan een gerealiseerde weergave:

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

Een bestaande weergave gebruiken in Unity Catalog als een functietabel

Als u een weergave als een functietabel wilt gebruiken, moet u databricks-feature-engineering versie 0.7.0 of hoger gebruiken, die is ingebouwd in Databricks Runtime 16.0 ML.

Een eenvoudige SELECT weergave in Unity Catalog kan een functietabel zijn in Unity Catalog en u kunt de Functies-API gebruiken met de tabel.

Notitie

  • Een eenvoudige SELECT weergave wordt gedefinieerd als een weergave die is gemaakt op basis van één Delta-tabel in Unity Catalog die kan worden gebruikt als een functietabel en waarvan de primaire sleutels worden geselecteerd zonder JOIN, GROUP BYof DISTINCT-componenten. Acceptabele trefwoorden in de SQL-instructie zijn SELECT, FROM, WHERE, ORDER BY, LIMITen OFFSET.
  • Zie Ondersteunde gegevenstypen voor ondersteunde gegevenstypen.
  • Functietabellen die gebaseerd zijn op weergaven, verschijnen niet in de functiesinterface.
  • Als de naam van kolommen in de delta-brontabel wordt gewijzigd, moeten de kolommen in de instructie SELECT voor de weergavedefinitie worden gewijzigd zodat deze overeenkomen.

Hier volgt een voorbeeld van een eenvoudige SELECT weergave die kan worden gebruikt als een functietabel:

CREATE OR REPLACE VIEW ml.recommender_system.content_recommendation_subset AS
SELECT
    user_id,
    content_id,
    user_age,
    user_gender,
    content_genre,
    content_release_year,
    user_content_watch_duration,
    user_content_like_dislike_ratio
FROM
    ml.recommender_system.content_recommendations_features
WHERE
    user_age BETWEEN 18 AND 35
    AND content_genre IN ('Drama', 'Comedy', 'Action')
    AND content_release_year >= 2010
    AND user_content_watch_duration > 60;

Functietabellen op basis van weergaven kunnen worden gebruikt voor offline modeltraining en -evaluatie. Ze kunnen niet worden gepubliceerd op online winkels. Functies van deze tabellen en modellen op basis van deze functies kunnen niet worden geleverd.

Een functietabel bijwerken in Unity Catalog

U kunt een functietabel in Unity Catalog bijwerken door nieuwe functies toe te voegen of door specifieke rijen te wijzigen op basis van de primaire sleutel.

De metagegevens van de volgende functietabel moeten niet worden bijgewerkt:

  • Primaire sleutel.
  • Partitiesleutel.
  • Naam of gegevenstype van een bestaande functie.

Als u deze wijzigt, worden downstreampijplijnen die gebruikmaken van functies voor het trainen en bedienen van modellen verbroken.

Nieuwe functies toevoegen aan een bestaande functietabel in Unity Catalog

U kunt op twee manieren nieuwe functies toevoegen aan een bestaande functietabel:

  • Werk de bestaande functie voor functieberekening bij en voer write_table uit met het geretourneerde DataFrame. Hiermee wordt het schema van de functietabel bijgewerkt en worden nieuwe functiewaarden samengevoegd op basis van de primaire sleutel.
  • Maak een nieuwe functie voor functieberekening om de nieuwe functiewaarden te berekenen. Het DataFrame dat door deze nieuwe rekenfunctie wordt geretourneerd, moet de primaire en partitiesleutels van de functietabellen bevatten (indien gedefinieerd). Voer write_table uit met het DataFrame om de nieuwe functies naar de bestaande functietabel te schrijven met behulp van dezelfde primaire sleutel.

Alleen specifieke rijen in een functietabel bijwerken

Gebruiken mode = "merge" in write_table. Rijen waarvan de primaire sleutel niet bestaat in het DataFrame dat in de write_table aanroep wordt verzonden, blijven ongewijzigd.

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

Een taak plannen om een functietabel bij te werken

Om ervoor te zorgen dat functies in functietabellen altijd de meest recente waarden hebben, raadt Databricks u aan een taak te maken waarmee een notebook wordt uitgevoerd om uw functietabel regelmatig bij te werken, zoals elke dag. Als u al een niet-geplande taak hebt gemaakt, kunt u deze converteren naar een geplande taak om ervoor te zorgen dat de functiewaarden altijd up-to-datum zijn. Zie Werkstromen plannen en organiseren.

Code voor het bijwerken van een functietabel maakt gebruik van mode='merge', zoals wordt weergegeven in het volgende voorbeeld.

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

Eerdere waarden van dagelijkse functies opslaan

Definieer een functietabel met een samengestelde primaire sleutel. Neem de datum op in de primaire sleutel. Voor een functietabel customer_featureskunt u bijvoorbeeld een samengestelde primaire sleutel (date, customer_id) en partitiesleutel gebruiken date voor efficiënte leesbewerkingen.

Databricks raadt u aan vloeibare clustering in te schakelen in de tabel voor efficiënte leesbewerkingen. Als u geen liquide clustering gebruikt, stelt u de datumkolom in als partitiesleutel voor betere leesprestaties.

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

Vervolgens kunt u code maken om te lezen van de functietabelfiltering date naar de gewenste periode.

U kunt ook een functietabel voor tijdreeksen maken waarmee zoekacties naar een bepaald tijdstip mogelijk zijn wanneer u create_training_set of score_batchgebruikt. Zie Een functietabel maken in Unity Catalog.

Als u de functietabel up-to-date wilt houden, stelt u een regelmatig geplande taak in om functies te schrijven of nieuwe functiewaarden naar de functietabel te streamen.

Een pijplijn voor het berekenen van streamingfuncties maken om functies bij te werken

Als u een berekeningspijplijn voor streamingfuncties wilt maken, geeft u een streaming DataFrame door als argument aan write_table. Deze methode retourneert een StreamingQuery-object.

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

Lezen uit een functietabel in Unity Catalog

Gebruik read_table om functiewaarden te lezen.

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

functietabellen zoeken en bladeren in Unity Catalog

Gebruik de gebruikersinterface voor functies om functietabellen in Unity Catalog te zoeken of te doorzoeken.

  1. Klik op Pictogram functiearchiefFuncties in de zijbalk om de gebruikersinterface van functies weer te geven.

  2. Selecteer catalogus met de cataloguskiezer om alle beschikbare functietabellen in die catalogus weer te geven. Voer in het zoekvak alle of een deel van de naam van een functietabel, een functie of een opmerking in. U kunt ook alle of een deel van de sleutel of waarde van een tag invoeren. Zoektekst is niet hoofdlettergevoelig.

    Voorbeeld van zoeken in functies

Metagegevens van functietabellen ophalen in Unity Catalog

Gebruik get_table om metagegevens van functietabellen op te halen.

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

Tags gebruiken met functietabellen en -functies in Unity Catalog

U kunt tags, die eenvoudige sleutel-waardeparen zijn, gebruiken om uw functietabellen en -functies te categoriseren en te beheren.

Voor functietabellen kunt u tags maken, bewerken en verwijderen met behulp van Catalog Explorer, SQL-instructies in een notebook of SQL-query-editor, of de Python-API voor Feature Engineering.

Voor functies kunt u tags maken, bewerken en verwijderen met behulp van Catalog Explorer of SQL-instructies in een notebook of SQL-queryeditor.

Zie Tags toepassen op beveiligbare objecten van Unity Catalog en Feature Engineering and Workspace Feature Store Python API.

In het volgende voorbeeld ziet u hoe u de Python-API van Feature Engineering gebruikt om tags voor functietabellen te maken, bij te werken en te verwijderen.

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

Een functietabel verwijderen in Unity Catalog

U kunt een functietabel in Unity Catalog verwijderen door de Delta-tabel in Unity Catalog rechtstreeks te verwijderen met behulp van Catalog Explorer of met behulp van de Feature Engineering Python API.

Notitie

  • Het verwijderen van een functietabel kan leiden tot onverwachte fouten in upstream-producenten en downstreamgebruikers (modellen, eindpunten en geplande taken). U moet gepubliceerde online winkels verwijderen bij uw cloudprovider.
  • Wanneer u een functietabel verwijdert in Unity Catalog, wordt de onderliggende Delta-tabel ook verwijderd.
  • drop_table wordt niet ondersteund in Databricks Runtime 13.1 ML of lager. Gebruik de SQL-opdracht om de tabel te verwijderen.

U kunt Databricks SQL of FeatureEngineeringClient.drop_table gebruiken om een functietabel in Unity Catalog te verwijderen:

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

Een kenmerktabel delen in Unity Catalog tussen werkruimten of accounts

Een functietabel in Unity Catalog is toegankelijk voor alle werkruimten die zijn toegewezen aan de Unity Catalog-metastore van de tabel.

Als u een functietabel wilt delen met werkruimten die niet zijn toegewezen aan dezelfde Unity Catalog-metastore, gebruikt u Delta Sharing-.