Utiliser des tables de caractéristiques

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 les tables de caractéristiques du magasin de caractéristiques d’espace de travail.

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

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 de caractéristiques dans Unity Catalog dispose d’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.3 LTS ML et versions ultérieures. Si vous utilisez un Databricks Runtime non ML, vous devez installer manuellement le client. Utilisez la matrice de compatibilité pour rechercher la version approprié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

Les tables de caractéristiques dans Unity Catalog sont des Tables Delta. Chaque table de fonctionnalités doit avoir une clé primaire. L’accès aux tables de caractéristiques, comme d’autres ressources de données dans Unity Catalog, s’effectue en utilisant un espace de noms à trois niveaux : <catalog-name>.<schema-name>.<table-name>.

Vous pouvez utiliser Databricks SQL, le FeatureEngineeringClient Python ou un pipeline Delta Live Tables pour créer des tables de caractéristiques dans Unity Catalog.

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 qu’avec d’autres tables Delta et l’utiliser 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.

1. É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.
2. Créez une table de fonctionnalités en instanciant un FeatureEngineeringClient et en utilisant create_table.
3. 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',
#   ...
# )

Créer une table de fonctionnalités dans Unity Catalog avec le pipeline Delta Live Tables

Vous pouvez utiliser en tant que table de caractéristiques une table publiée à partir d’un pipeline Delta Live Tables qui inclut une contrainte de clé primaire. Pour créer une table dans un pipeline Delta Live Tables avec une clé primaire, vous pouvez utiliser Databricks SQL ou l’interface de programmation Python Delta Live Tables.

Pour créer une table dans un pipeline Delta Live Tables avec une clé primaire, utilisez la syntaxe suivante :

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

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.

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

Une fois la table créée, vous pouvez y écrire des données de la même façon qu’avec d’autres jeux de données Delta Live Tables et l’utiliser comme table de caractéristiques.

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.

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

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

2. 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, ...)
   

   pk_name est le nom de la contrainte de clé primaire. 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" aura 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 votre ajout de la contrainte de clé primaire à la table, vous pouvez voir la table dans l’interface utilisateur de caractéristiques et l’utiliser comme table de caractéristiques.

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

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.

Pour définir les clés primaires d’une table de diffusion en continu ou d’une vue matérialisée existantes, mettez à jour le schéma de la table de diffusion en continu ou de la vue matérialisée dans le notebook qui gère l’objet. Ensuite, actualisez la table pour mettre à jour l’objet Unity Catalog.

Vous utilisez la syntaxe suivante pour ajouter une clé primaire à une vue dématérialisée :

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

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 de partition et primaires 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 veiller à ce que les valeurs des caractéristiques soient toujours à jour. Consultez Planifier et orchestrer des flux de travail.

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 vous recommande d’activer le clustering liquide sur la table pour des lectures efficaces. Si vous n’utilisez pas le clustering liquide, définissez la colonne de date comme clé de partition pour améliorer les performances de lecture.

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

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 des caractéristiques ou diffusez en continu de nouvelles valeurs de caractéristiques dans 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.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'
)

Lire à partir d’une table de caractéristiques 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.

1. Cliquez sur Fonctionnalités dans la barre latérale pour afficher l’interface utilisateur des fonctionnalités.

2. 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’Explorateur de catalogues, d’instructions SQL dans un notebook ou l’éditeur de requête SQL ou de l’API Python d’ingénierie de caractéristiques.

Pour les fonctionnalités, vous pouvez créer, modifier et supprimer des balises à l’aide de l’Explorateur de catalogues ou d’instructions SQL dans un notebook ou l’éditeur de requête SQL.

Consultez Appliquer des balises aux objets sécurisables Unity Catalog et Ingénierie de caractéristiques et API Python du Feature Store de l’espace de travail.

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.

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

Partager une table de fonctionnalités dans le catalogue Unity entre des espaces de travail ou des comptes

Une table de fonctionnalités dans le catalogue Unity est accessible à tous les espaces de travail affectés au metastore du catalogue Unity de la table.

Pour partager une table de fonctionnalités avec des espaces de travail qui ne sont pas affectés au même metastore du catalogue Unity, utilisez le partage Delta.