Ingénierie des fonctionnalités dans le catalogue Unity

Article
04/24/2024

Cette page décrit comment créer et utiliser des tables de fonctionnalités dans Unity Catalog.

Cette page s'applique uniquement aux espaces de travail qui sont activés pour Unity Catalog. Si votre espace de travail n’est pas activé pour Unity Catalog, consultez Utiliser des caractéristiques dans Workspace Feature Store.

Spécifications

L’ingénierie de caractéristiques dans Unity Catalog exige Databricks Runtime 13.2 ou versions ultérieures. En outre, le metastore Unity Catalog doit disposer de Privilege Model version 1.0.

Installer l'ingénierie des fonctionnalités dans Unity Catalog - Client Python

L’ingénierie des fonctionnalités dans Unity Catalog fournit un client Python FeatureEngineeringClient. La classe est disponible sur PyPI dans le package databricks-feature-engineering et est préinstallée dans Databricks Runtime 13.2 ML et ses versions ultérieures. Si vous utilisez un Databricks Runtime qui n’est pas sur ML, vous devez installer manuellement le client. Utilisez la matrice de compatibilité pour trouver la version adaptée à votre version Databricks Runtime.

%pip install databricks-feature-engineering

dbutils.library.restartPython()

Créer un catalogue et un schéma pour les tables de fonctionnalités dans Unity Catalog

Vous devez créer un nouveau catalogue ou utiliser un catalogue existant pour les tables de fonctionnalités.

Pour créer un nouveau catalogue, vous devez disposer du privilège CREATE CATALOG sur le metastore.

CREATE CATALOG IF NOT EXISTS <catalog-name>

Pour utiliser un catalogue existant, vous devez disposer du privilège USE CATALOG sur le catalogue.

USE CATALOG <catalog-name>

Les tables de fonctionnalités dans Unity Catalog doivent être stockées dans un schéma. Pour créer un nouveau schéma dans le catalogue, vous devez disposer du privilège CREATE SCHEMA sur le catalogue.

CREATE SCHEMA IF NOT EXISTS <schema-name>

Créer une table de fonctionnalités dans Unity Catalog

Remarque

Vous pouvez utiliser une table Delta existante dans Unity Catalog comme table de fonctionnalités. Consultez Utiliser une table Delta existante dans Unity Catalog comme table de fonctionnalités.

Vous pouvez également utiliser une table Delta Live existante dans Unity Catalog comme table de fonctionnalités. Consultez Utiliser une table de diffusion en continu existante ou une vue matérialisée créée par un pipeline Delta Live Tables en tant que table de fonctionnalités.

Les tables de fonctionnalités dans Unity Catalog sont des tables Delta ou Delta Live gérées par Unity Catalog. Chaque table de fonctionnalités doit avoir une clé primaire. Le nom d’une table de fonctionnalités dans Unity Catalog a une structure à trois niveaux, <catalog-name>.<schema-name>.<table-name>.

Vous pouvez utiliser Databricks SQL ou le FeatureEngineeringClient Python pour créer des tables de caractéristiques dans Unity Catalog. Vous pouvez utiliser des pipelines de tables Delta Live Tables pour créer des fonctionnalités Delta Live Tables dans le catalogue Unity.

Databricks SQL

Vous pouvez utiliser n’importe quelle table Delta avec une Contrainte de clé primaire comme table de caractéristiques. Le code suivant montre comment créer une table avec une clé primaire :

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

Pour créer une table de caractéristiques de série chronologique, ajoutez une colonne heure en tant que colonne de clé primaire et spécifiez le mot clé TIMESERIES. Le mot clé TIMESERIES requiert Databricks Runtime 13.3 LTS ou une version ultérieure.

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

Une fois la table créée, vous pouvez y écrire des données de la même façon que vous écrivez d’autres tables Delta, et elles peuvent être utilisées comme table de caractéristiques.

Python

Pour plus d’informations sur les commandes et les paramètres utilisés dans les exemples suivants, consultez les Informations de référence sur l’API Python d’ingénierie de caractéristiques.

Écrivez les fonctions Python pour calculer les caractéristiques. La sortie de chaque fonction doit être un DataFrame Apache Spark avec une clé primaire unique. La clé primaire peut être constituée d’une ou de plusieurs colonnes.
Créez une table de fonctionnalités en instanciant un FeatureEngineeringClient et en utilisant create_table.
Remplissez la table de caractéristiques en utilisant 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',
#   ...
# )

Tables Delta Live

Remarque

Les contraintes de table sur les tables Delta Live se trouvent dans la préversion publique. Les exemples de code suivants doivent être exécutés à l’aide du canal en préversion Delta Live Tables.

Vous pouvez utiliser n’importe quelle table Delta Live disposant d’une contrainte de clé primaire comme table de caractéristiques. Le code suivant montre comment créer une table Delta Live avec une clé primaire :

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

Pour créer une table de caractéristiques de série chronologique, ajoutez une colonne heure en tant que colonne de clé primaire et spécifiez le mot clé 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 ...;

Une fois la table créée, vous pouvez y écrire des données de la même façon que pour d’autres tables Delta Live, et elle peut être utilisée comme table de caractéristiques.

Les contraintes de table pour les tables dynamiques Delta (Delta Live Tables) sont uniquement prises en charge par SQL. Pour définir des clés primaires pour les tables Delta Live déclarées en Python, voir Utiliser une table de flux existante ou une vue matérialisée créée par un pipeline Delta Live Tables en tant que table de fonctionnalités.

Utiliser une table Delta existante dans Unity Catalog comme table de fonctionnalités

Toute table Delta dans Unity Catalog dotée d’une clé primaire peut être une table de fonctionnalités dans Unity Catalog et vous pouvez utiliser l’interface utilisateur de fonctionnalité et l’API avec la table.

Remarque

Seul le propriétaire de la table peut déclarer des contraintes de clé primaire. Le nom du propriétaire est indiqué sur la page de détails de la table dans Catalog Explorer.
Vérifiez que le type de données de la table Delta est pris en charge par l’ingénierie des fonctionnalités dans Unity Catalog. Consultez Types de données pris en charge.
Le mot clé TIMESERIES requiert Databricks Runtime 13.3 LTS ou une version ultérieure.

Si une table Delta existante ne dispose pas de contrainte de clé primaire, vous pouvez en créer une de la manière suivante :

Définissez les colonnes de clés primaires sur NOT NULL. Pour chaque colonne de clé primaire, exécutez :
```
ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL
```
Modifiez la table pour y ajouter la contrainte de clé primaire :
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1, pk_col2, ...)
```
Le nom de la contrainte de clé primaire est pk_name. Par convention, vous pouvez utiliser le nom de la table (sans schéma ni catalogue) avec un suffixe _pk. Par exemple, une table portant le nom "ml.recommender_system.customer_features" aurait comme nom customer_features_pk pour sa contrainte de clé primaire.

Pour transformer la table en une table de caractéristiques de série chronologique, spécifiez le mot clé TIMESERIES sur l’une des colonnes de clés primaires, comme suit :
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1 TIMESERIES, pk_col2, ...)
```
Après avoir ajouté la contrainte de clé primaire à la table, vous pouvez voir la table dans l’interface utilisateur de fonctionnalités et vous pouvez l’utiliser comme une table de fonctionnalités.

Utiliser une table de diffusion en continu existante ou une vue matérialisée créée par un pipeline Delta Live Tables en tant que table de fonctionnalités

Toute table de flux ou vue matérialisée dans le catalogue Unity avec une clé primaire peut être une table de fonctionnalités dans Unity Catalog, et vous pouvez utiliser l’interface utilisateur et l’API des fonctionnalités avec la table.

Remarque

Les contraintes de table sur les tables Delta Live se trouvent dans la préversion publique. Les exemples de code suivants doivent être exécutés à l’aide du canal en préversion Delta Live Tables.
Seul le propriétaire de la table peut déclarer des contraintes de clé primaire. Le nom du propriétaire est indiqué sur la page de détails de la table dans Catalog Explorer.
Vérifiez que le type de données de la table Delta est pris en charge par l’ingénierie des fonctionnalités dans Unity Catalog. Consultez Types de données pris en charge.

Ajoutez une clé primaire à une table de diffusion en continu ou une vue matérialisée créée à l’aide de SQL

Pour définir les clés primaires d’une table de flux ou d’une vue matérialisée existante qui a été créée à l’aide de SQL, mettez à jour le schéma de la table de flux ou de la vue matérialisée dans l’ordinateur portable qui gère la table. Ensuite, actualisez la table de la contrainte à appliquer dans Unity Catalog.

Le code doit ressembler à ce qui suit :

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

Ajoutez une clé primaire à une table de diffusion en continu ou une vue matérialisée créée à l’aide de Python

Pour créer des clés primaires pour une table de flux existante ou une vue matérialisée créée par un pipeline Delta Live Tables, vous devez utiliser SQL, même si la table de flux ou la vue matérialisée a été créée à l’aide de Python. Créez un nouveau bloc-notes SQL pour définir une nouvelle table en continu ou une vue matérialisée qui lit à partir de la table existante. Exécutez ensuite le bloc-notes en tant qu’étape du pipeline de tables dynamiques Delta existant ou dans un nouveau pipeline.

Le nouveau bloc-notes SQL doit inclure du code similaire à ce qui suit :

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

Contrôler l’accès aux tables de fonctionnalités dans Unity Catalog

Le contrôle d’accès aux tables de fonctionnalités dans Unity Catalog est géré par Unity Catalog. Consultez Privilèges Unity Catalog.

Mettre à jour une table de fonctionnalités dans Unity Catalog

Vous pouvez mettre à jour une table de fonctionnalités dans Unity Catalog en ajoutant de nouvelles fonctionnalités ou en modifiant des lignes spécifiques en fonction de la clé primaire.

Les métadonnées suivantes de la table de fonctionnalités ne doivent pas être mises à jour :

Clé primaire
Clé de partition.
Nom ou type de données d’une fonctionnalité existante.

Leur modification entraîne l’arrêt des pipelines en aval qui utilisent des fonctionnalités pour la formation et le service des modèles.

Ajouter de nouvelles fonctionnalités à une table de fonctionnalités existante dans Unity Catalog

Vous pouvez ajouter de nouvelles caractéristiques à une table de caractéristiques existante de l’une des deux manières suivantes :

Mettez à jour la fonction de calcul de caractéristique existante et exécutez write_table avec le DataFrame retourné. Cette opération met à jour le schéma de la table de caractéristiques et fusionne les nouvelles valeurs de caractéristiques en fonction de la clé primaire.
Créez une fonction de calcul de caractéristique pour calculer les nouvelles valeurs de caractéristiques. Le DataFrame retourné par cette nouvelle fonction de calcul doit contenir les clés primaires et les clés de partition des tables de caractéristiques (si elles sont définies). Exécutez write_table avec le DataFrame pour écrire les nouvelles caractéristiques dans la table de caractéristiques existante, en utilisant la même clé primaire.

Mettre à jour uniquement des lignes spécifiques dans une table de caractéristiques

Utilisez mode = "merge" dans write_table. Les lignes dont la clé primaire n’existe pas dans le DataFrame envoyé dans l’appel write_table restent inchangées.

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

Planifier un travail pour mettre à jour une table de caractéristiques

Pour que les caractéristiques dans les tables de caractéristiques possèdent toujours les valeurs les plus récentes, Databricks recommande de créer un travail qui exécute un notebook afin de mettre à jour votre table de caractéristiques régulièrement, par exemple tous les jours. Si vous avez déjà créé un travail non planifié, vous pouvez le convertir en travail planifié pour vous assurer que les valeurs des caractéristiques sont toujours à jour.

Le code pour mettre à jour une table de caractéristiques utilise mode='merge', comme illustré dans l’exemple suivant.

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

Stocker les valeurs passées des caractéristiques quotidiennes

Définissez une table de caractéristiques avec une clé primaire composite. Incluez la date dans la clé primaire. Par exemple, pour une table de caractéristiques customer_features, vous pouvez utiliser une clé primaire composite (date, customer_id) et une clé de partition date afin d’effectuer des lectures efficaces.

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

Vous pouvez ensuite créer du code pour effectuer des opérations de lecture dans la table de caractéristiques en filtrant date sur la période digne d’intérêt.

Vous pouvez également créer une table de caractéristiques de série chronologique qui active les recherches ponctuelles lorsque vous utilisez create_training_set ou score_batch. Veuillez consulter Créer une table de caractéristiques dans Unity Catalog.

Pour tenir à jour la table de caractéristiques, configurez un travail régulièrement planifié pour écrire les caractéristiques ou envoyer en streaming les nouvelles valeurs de caractéristiques à la table de caractéristiques.

Créer un pipeline de calcul de caractéristique en streaming pour mettre à jour les caractéristiques

Pour créer un pipeline de calcul de caractéristique en streaming, transmettez un streaming DataFrame en tant qu’argument à write_table. La méthode retourne un objet StreamingQuery.

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

Lire à partir d’une table de fonctionnalités dans Unity Catalog

Utilisez read_table pour lire les valeurs de caractéristique.

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

Rechercher et parcourir des tables de fonctionnalités dans Unity Catalog

Utilisez l’IU des fonctionnalités pour rechercher ou parcourir des tables de fonctionnalités dans Unity Catalog.

Cliquez sur l’Fonctionnalités dans la barre latérale pour afficher l’IU des Fonctionnalités.
Sélectionnez un catalogue à l’aide du sélecteur de catalogue pour afficher toutes les tables de fonctionnalités disponibles dans ce catalogue. Dans la zone de recherche, vous pouvez entrer tout ou partie du nom d’une table de fonctionnalités, d’une fonctionnalité ou d’un commentaire. Vous pouvez également entrer tout ou partie de la clé ou valeur d’une étiquette. Le texte de la recherche ne respecte pas la casse.

Obtenir les métadonnées des tables de fonctionnalités dans Unity Catalog

Utilisez get_table pour obtenir des métadonnées de table de fonctionnalités.

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

Utilisez des balises avec des tables de fonctionnalités et des fonctionnalités dans Unity Catalog

Vous pouvez utiliser des balises, qui sont des paires clé-valeur simples, pour catégoriser et gérer vos tables de fonctionnalités et vos fonctionnalités.

Pour les tables de fonctionnalités, vous pouvez créer, modifier et supprimer des balises à l’aide de l’interface utilisateur de l’explorateur de catalogues, de Databricks SQL ou de l’API Python pour l’ingénierie des fonctionnalités.

Pour les fonctionnalités, vous pouvez créer, modifier et supprimer des balises à l’aide de l’interface utilisateur de l’explorateur de catalogues ou de Databricks SQL.

L’exemple suivant montre comment utiliser l’ingénierie de caractéristiques d’API Python pour créer, mettre à jour et supprimer des balises de tables de fonctionnalités.

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

Supprimer une table de fonctionnalités dans Unity Catalog

Vous pouvez supprimer une table de fonctionnalités dans Unity Catalog en supprimant directement la table Delta dans Unity Catalog à l’aide de l’explorateur de catalogue ou en utilisant l’ingénierie de caractéristiques d’API Python.

Remarque

La suppression d’une table de caractéristiques peut entraîner des défaillances inattendues dans les producteurs en amont et les consommateurs en aval (modèles, points de terminaison et travaux planifiés). Vous devez supprimer les magasins en ligne publiés avec votre fournisseur cloud.
Lorsque vous supprimez une table de fonctionnalités dans Unity Catalog, la table Delta sous-jacente est également supprimée.
drop_table n’est pas prise en charge dans Databricks Runtime 13.1 ML ou ses versions antérieures. Utilisez la commande SQL pour supprimer la table.

Vous pouvez utiliser Databricks SQL ou FeatureEngineeringClient.drop_table pour supprimer une table de fonctionnalités dans 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'
)

Ingénierie des fonctionnalités dans le catalogue Unity

Spécifications

Installer l'ingénierie des fonctionnalités dans Unity Catalog - Client Python

Créer un catalogue et un schéma pour les tables de fonctionnalités dans Unity Catalog

Créer une table de fonctionnalités dans Unity Catalog

Databricks SQL

Python

Tables Delta Live

Utiliser une table Delta existante dans Unity Catalog comme table de fonctionnalités

Utiliser une table de diffusion en continu existante ou une vue matérialisée créée par un pipeline Delta Live Tables en tant que table de fonctionnalités

Ajoutez une clé primaire à une table de diffusion en continu ou une vue matérialisée créée à l’aide de SQL

Ajoutez une clé primaire à une table de diffusion en continu ou une vue matérialisée créée à l’aide de Python

Contrôler l’accès aux tables de fonctionnalités dans Unity Catalog

Mettre à jour une table de fonctionnalités dans Unity Catalog

Ajouter de nouvelles fonctionnalités à une table de fonctionnalités existante dans Unity Catalog

Mettre à jour uniquement des lignes spécifiques dans une table de caractéristiques

Planifier un travail pour mettre à jour une table de caractéristiques

Stocker les valeurs passées des caractéristiques quotidiennes

Databricks SQL

Python

Créer un pipeline de calcul de caractéristique en streaming pour mettre à jour les caractéristiques

Lire à partir d’une table de fonctionnalités dans Unity Catalog

Rechercher et parcourir des tables de fonctionnalités dans Unity Catalog

Obtenir les métadonnées des tables de fonctionnalités dans Unity Catalog

Utilisez des balises avec des tables de fonctionnalités et des fonctionnalités dans Unity Catalog

Supprimer une table de fonctionnalités dans Unity Catalog

Databricks SQL

Python

Ressources supplémentaires