Werken met functietabellen

Artikel
10/04/2024

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

Zie de naslaginformatie 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.0 hebben.

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 beschikken over de CREATE CATALOG bevoegdheid voor de metastore.

CREATE CATALOG IF NOT EXISTS <catalog-name>

Als u een bestaande catalogus wilt gebruiken, moet u de USE CATALOG bevoegdheid 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 CREATE SCHEMA bevoegdheid 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 gebruiken in Unity Catalog 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 Een streamingtabel of gerealiseerde weergave gebruiken die is gemaakt door een Delta Live Tables-pijplijn als een functietabel.

Functietabellen in Unity Catalog zijn Delta-tabellen. Functietabellen moeten een primaire sleutel hebben. Functietabellen, zoals andere gegevensassets in Unity Catalog, worden geopend met behulp van een naamruimte op drie niveaus: <catalog-name>.<schema-name>.<table-name>

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

Databricks SQL

U kunt elke Delta-tabel met een primaire-sleutelbeperking als een functietabel gebruiken. 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 tijdreeksfunctietabel wilt maken, voegt u een tijdkolom toe als primaire-sleutelkolom en geeft u het trefwoord TIMESERIES 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 de Naslaginformatie over de Python-API voor feature engineering voor meer informatie over de opdrachten en parameters die in de volgende voorbeelden worden gebruikt.

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.
Maak een functietabel door een instantie van een FeatureEngineeringClient en gebruik te maken create_table.
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 Delta Live Tables voor tabelbeperkingen bevindt zich in openbare preview. De volgende codevoorbeelden moeten worden uitgevoerd met behulp van het preview-kanaal van Delta Live Tables.

Elke tabel die is gepubliceerd vanuit een Delta Live Tables-pijplijn die een primaire-sleutelbeperking bevat, kan worden gebruikt als 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 van Delta Live Tables gebruiken.

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 tijdreeksfunctietabel wilt maken, voegt u een tijdkolom toe als primaire-sleutelkolom en geeft u het trefwoord TIMESERIES 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-sleutelbeperking heeft, kunt u er als volgt een maken:

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
```
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" zou bijvoorbeeld de naam van de primaire-sleutelbeperking hebben customer_features_pk .

Als u de tabel een tijdreeksfunctietabel wilt 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.

Een streamingtabel of gerealiseerde weergave gebruiken die is gemaakt door een Delta Live Tables-pijplijn als een functietabel

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 Delta Live Tables voor tabelbeperkingen bevindt zich in openbare preview. De volgende codevoorbeelden moeten worden uitgevoerd met behulp van het preview-kanaal van Delta Live Tables.
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 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 deze uit write_table 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-date zijn. Zie Werkstromen plannen en organiseren.

Code voor het bijwerken van een functietabel gebruikt 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 date gebruiken voor efficiënte leesbewerkingen.

Databricks raadt u aan om vloeistofclustering in de tabel in te schakelen 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 uit de functietabelfiltering date naar de gewenste periode.

U kunt ook een functietabel voor tijdreeksen maken waarmee opzoekacties naar een bepaald tijdstip mogelijk zijn wanneer u deze gebruikt create_training_set of score_batch. 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 deze optie 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.

Klik op Functies in de zijbalk om de gebruikersinterface van functies weer te geven.
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.

Metagegevens van functietabellen ophalen in Unity Catalog

Gebruik get_table dit 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 van 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 en 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 Python-API voor functie-engineering.

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 gebruiken of FeatureEngineeringClient.drop_table een functietabel verwijderen in 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'
)

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.

Delen via

Werken met functietabellen

Vereisten

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

Een catalogus en een schema maken voor functietabellen in Unity Catalog

Een functietabel maken in Unity Catalog

Databricks SQL

Python

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

Databricks SQL

Python

Databricks SQL

Python

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

Een streamingtabel of gerealiseerde weergave gebruiken die is gemaakt door een Delta Live Tables-pijplijn als een functietabel

Databricks SQL

Python

Een functietabel bijwerken in Unity Catalog

Nieuwe functies toevoegen aan een bestaande functietabel in Unity Catalog

Alleen specifieke rijen in een functietabel bijwerken

Een taak plannen om een functietabel bij te werken

Eerdere waarden van dagelijkse functies opslaan

Databricks SQL

Python

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

Lezen uit een functietabel in Unity Catalog

Functietabellen zoeken en bladeren in Unity Catalog

Metagegevens van functietabellen ophalen in Unity Catalog

Tags gebruiken met functietabellen en -functies in Unity Catalog

Een functietabel verwijderen in Unity Catalog

Databricks SQL

Python

Feedback

Aanvullende resources

Delen via

Werken met functietabellen

Vereisten

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

Een catalogus en een schema maken voor functietabellen in Unity Catalog

Een functietabel maken in Unity Catalog

Databricks SQL

Python

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

Databricks SQL

Python

Databricks SQL

Python

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

Een streamingtabel of gerealiseerde weergave gebruiken die is gemaakt door een Delta Live Tables-pijplijn als een functietabel

Databricks SQL

Python

Een functietabel bijwerken in Unity Catalog

Nieuwe functies toevoegen aan een bestaande functietabel in Unity Catalog

Alleen specifieke rijen in een functietabel bijwerken

Een taak plannen om een functietabel bij te werken

Eerdere waarden van dagelijkse functies opslaan

Databricks SQL

Python

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

Lezen uit een functietabel in Unity Catalog

Functietabellen zoeken en bladeren in Unity Catalog

Metagegevens van functietabellen ophalen in Unity Catalog

Tags gebruiken met functietabellen en -functies in Unity Catalog

Een functietabel verwijderen in Unity Catalog

Databricks SQL

Python

Een functietabel delen in Unity Catalog in werkruimten of accounts

Feedback

Aanvullende resources