Aller au contenu principal
Dernière mise à jour le

Tables de fonctionnalités dans Unity Catalog

Dans Unity Catalog, toute table Delta avec une contrainte de clé primaire peut servir de table de fonctionnalités. Créez des tables de fonctionnalités à l'aide de Databricks SQL, du client Python ou des LakeFlow Pipelines, puis mettez-les à jour, parcourez-les et gouvernez-les à l'aide de Unity Catalog.

Cette page s'applique uniquement aux workspaces qui sont activés pour Unity Catalog. Si votre Workspace n'est pas activé pour Unity Catalog, consultez Utiliser des tables de fonctionnalités dans le Magasin de fonctionnalités du Workspace (hérité).

Pour plus de détails sur les commandes et les paramètres utilisés dans les exemples de cette page, consultez la référence de l'API Python de Feature Engineering.

Exigences​

L'ingénierie des fonctionnalités dans Unity Catalog nécessite Databricks Runtime 13.2 ou une version ultérieure. De plus, le metastore Unity Catalog doit avoir le modèle de privilèges version 1.0.

Installer le client Python de Feature Data Engineering dans Unity Catalog​

Feature Data Engineering dans Unity Catalog dispose d'un client Python FeatureEngineeringClient. La classe est disponible sur PyPI avec 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 sans ML, vous devez installer le client manuellement. Utilisez la matrice de compatibilité pour trouver la version correcte de votre version de Databricks Runtime.

Python
%pip install databricks-feature-engineering

dbutils.library.restartPython()

Créez 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 métastore.

SQL
CREATE CATALOG IF NOT EXISTS <catalog-name>

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

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

SQL
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 qui inclut une contrainte de clé primaire comme table de fonctionnalités. Si la table ne dispose pas d’une clé primaire définie, vous devez mettre à jour la table à l’aide des instructions DDL ALTER TABLE pour ajouter la contrainte. Voir Utiliser une table Delta existante dans Unity Catalog comme table de fonctionnalités.

Cependant, l'ajout d'une clé primaire à une table de streaming ou à une vue matérialisée publiée dans Unity Catalog par Lakeflow Pipelines nécessite de modifier le schéma de la définition de la table de streaming ou de la vue matérialisée pour inclure la clé primaire, puis d'actualiser la table de streaming ou la vue matérialisée. Consultez Utiliser une table de streaming ou une vue matérialisée créée par les Lakeflow pipelines comme table de fonctionnalités.

Les tables de caractéristiques dans Unity Catalog sont des tables Delta. Les tables de fonctionnalités doivent avoir une clé primaire. Les tables de fonctionnalités, comme les autres assets de données dans Unity Catalog, sont accessibles à l’aide d’un espace de noms à trois niveaux : <catalog-name>.<schema-name>.<table-name>.

Vous pouvez utiliser Databricks SQL, le Python FeatureEngineeringClient ou les pipelines Lakeflow pour créer des tables de fonctionnalités dans Unity Catalog.

Vous pouvez utiliser n'importe quelle table Delta avec une contrainte de clé primaire comme table de fonctionnalités. Le code suivant montre comment créer une table avec une clé primaire :

SQL
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 fonctionnalités de séries temporelles, ajoutez une colonne de temps comme colonne de clé primaire et spécifiez le mot-clé TIMESERIES. Le mot-clé TIMESERIES nécessite Databricks Runtime 13.3 LTS ou une version ultérieure.

SQL
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 comme pour les autres tables Delta, et elle peut être utilisée comme table de fonctionnalités.

Créez une table de fonctionnalités dans Unity Catalog avec Lakeflow pipelines.​

remarque

LakeFlow Pipelines prend en charge les contraintes de table en aperçu public. Les exemples de code suivants doivent être exécutés à l'aide du canal de prévisualisation de LakeFlow Pipelines.

Toute table publiée à partir des Lakeflow pipelines qui inclut une contrainte de clé primaire peut être utilisée comme table de fonctionnalités. Pour créer une table dans un pipeline avec une clé primaire, vous pouvez utiliser Databricks SQL ou l'interface de programmation Python de Lakeflow Pipelines.

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

SQL
CREATE MATERIALIZED VIEW 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 temporelle comme colonne de clé primaire et spécifiez le mot-clé TIMESERIES.

SQL
CREATE MATERIALIZED VIEW 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 comme d'autres datasets de LakeFlow Pipelines, et elle peut être utilisée comme table de fonctionnalités.

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

Toute table Delta dans Unity Catalog 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
  • Seul le propriétaire de la table peut déclarer les contraintes de clé primaire. Le nom du propriétaire est affiché sur la page des détails de la table de l'Explorateur de catalogue.
  • Vérifiez que le type de données dans 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 nécessite Databricks Runtime 13.3 LTS ou une version ultérieure.

Si une table Delta existante ne possède pas de contrainte de clé primaire, vous pouvez en créer une comme suit :

  1. Définissez les colonnes de clé primaire sur NOT NULL. Pour chaque colonne de clé primaire, exécutez :

    SQL
    ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL

  2. Modifiez la table pour ajouter la contrainte de clé primaire :

    SQL
    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 table (sans schéma ni catalogue) avec un suffixe _pk. Par exemple, une table nommée "ml.recommender_system.customer_features" aurait customer_features_pk comme nom de sa contrainte de clé primaire.

    Pour faire de la table une table de fonctionnalités de série temporelle, spécifiez le mot-clé TIMESERIES sur l'une des colonnes de la clé primaire, comme suit :

    SQL
    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 sur la table, la table apparaît dans l'interface utilisateur des fonctionnalités et vous pouvez l'utiliser comme table de fonctionnalités.

Utiliser une table de streaming ou une vue matérialisée créée par les LakeFlow Pipelines comme table de caractéristiques​

Toute table streaming ou vue matérialisée dans Unity Catalog 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
  • LakeFlow Pipelines prend en charge les contraintes de table en aperçu public. Les exemples de code suivants doivent être exécutés à l'aide du canal de prévisualisation de LakeFlow Pipelines.
  • Seul le propriétaire de la table peut déclarer les contraintes de clé primaire. Le nom du propriétaire est affiché sur la page des détails de la table de l'Explorateur de catalogue.
  • Vérifiez que Feature Data Engineering dans Unity Catalog prend en charge le type de données dans la table Delta. Consultez Types de données pris en charge.

Pour définir les clés primaires d'une table de streaming ou d'une vue matérialisée existante, mettez à jour le schéma de la table de streaming ou de la vue matérialisée dans le notebook qui gère l'objet. Ensuite, refresh la table pour mettre à jour l'objet Unity Catalog.

Voici la syntaxe pour ajouter une clé primaire à une vue matérialisée :

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

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

Pour utiliser une vue comme table de fonctionnalités, vous devez utiliser databricks-feature-engineering version 0,7,0 ou ultérieure, qui est intégrée à Databricks Runtime 16.0 ML.

Une simple vue SELECT dans Unity Catalog peut être une table de fonctionnalités dans Unity Catalog, et vous pouvez utiliser l’API Features avec la table.

remarque
  • Une vue SELECT simple est définie comme une vue créée à partir d’une seule table Delta dans Unity Catalog qui peut être utilisée comme table de fonctionnalités, et dont les clés primaires sont sélectionnées sans clauses JOIN, GROUP BY ou DISTINCT. Les mots-clés acceptables dans l'instruction SQL sont SELECT, FROM, WHERE, ORDER BY, LIMIT et OFFSET.
  • Consultez les types de données pris en charge pour connaître les types de données pris en charge.
  • Les tables de fonctionnalités adossées à des vues n'apparaissent pas dans l'interface utilisateur des fonctionnalités.
  • Si des colonnes sont renommées dans la table Delta source, les colonnes de l'instruction SELECT pour la définition de la vue doivent être renommées en conséquence.

Voici un exemple de vue SELECT simple qui peut être utilisée comme table de fonctionnalités :

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

Les tables de fonctionnalités basées sur des vues peuvent être utilisées pour l'entraînement et l'évaluation de modèles hors ligne. Ils ne peuvent pas être publiés sur les boutiques en ligne. Les fonctionnalités de ces tables et les modèles basés sur ces fonctionnalités ne peuvent pas être servis.

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 de la table de fonctionnalités suivante ne doivent pas être mises à jour :

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

Les modifier entraînera la rupture des pipelines en aval qui utilisent des fonctionnalités pour l'entraînement et le service de modèles.

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

Vous pouvez ajouter de nouvelles fonctionnalités à une table de fonctionnalités existante de l'une des deux manières suivantes :

  • Mettez à jour la fonction de calcul de fonctionnalités existante et exécutez write_table avec le DataFrame retourné. Ceci met à jour le schéma de la table de fonctionnalités et merge les nouvelles valeurs de fonctionnalités en fonction de la clé primaire.
  • Créez une nouvelle fonction de calcul de fonctionnalité pour calculer les nouvelles valeurs de fonctionnalité. Le DataFrame renvoyé par cette nouvelle fonction de calcul doit contenir les clés primaires et de partition des tables de fonctionnalités (si définies). Exécutez write_table avec le DataFrame pour écrire les nouvelles fonctionnalités dans la table de fonctionnalités existante en utilisant la même clé primaire.

Mettre à jour uniquement des lignes spécifiques dans une table de fonctionnalités​

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.

Python
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 job pour mettre à jour une table de fonctionnalités​

Pour garantir que les fonctionnalités des tables de fonctionnalités disposent toujours des valeurs les plus récentes, Databricks vous recommande de créer un Job exécutant un Notebook pour mettre à jour votre table de fonctionnalités régulièrement, par exemple quotidiennement. Si vous avez déjà un job non planifié créé, vous pouvez le convertir en un job planifié pour vous assurer que les valeurs des fonctionnalités sont toujours à jour. See Lakeflow Jobs.

Le code de mise à jour d'une table de fonctionnalités utilise mode='merge', comme indiqué dans l'exemple suivant.

Python
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 fonctionnalités quotidiennes​

Définissez une table de fonctionnalités avec une clé primaire composite. Incluez la date dans la clé primaire. Par exemple, pour une table de fonctionnalités customer_features, vous pourriez utiliser une clé primaire composite (date, customer_id) et une clé de partition date pour des lectures efficaces.

Databricks vous recommande d'activer le liquid clustering sur la table pour des lectures efficaces. Si vous n'utilisez pas le liquid clustering, définissez la colonne de date comme clé de partition pour une meilleure performance de lecture.

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

Vous pouvez ensuite créer du code pour lire à partir de la table de fonctionnalités en filtrant date à la période d'intérêt.

Vous pouvez également créer une table de fonctionnalités de séries chronologiques qui permet des recherches à des points spécifiques du temps lorsque vous utilisez create_training_set ou score_batch. Consultez Créer une table de fonctionnalités dans Unity Catalog.

Pour maintenir la table de fonctionnalités à jour, mettez en place un Job planifié régulièrement pour écrire des fonctionnalités ou Stream de nouvelles valeurs de fonctionnalité dans la table de fonctionnalités.

Créer un pipeline de calcul de fonctionnalités en streaming pour mettre à jour les fonctionnalités​

Pour créer un pipeline de calcul de caractéristiques en streaming, passez un DataFrame en streaming comme argument à write_table. Cette méthode renvoie un StreamingQuery objet.

Python
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 fonctionnalités dans Unity Catalog​

Utilisez read_table pour lire les valeurs des fonctionnalités.

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

Rechercher et parcourir les tables de fonctionnalités dans Unity Catalog​

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

  1. Cliquez sur Icône du Magasin de fonctionnalités Fonctionnalités dans la barre latérale pour afficher l'interface utilisateur des fonctionnalités.

  2. Veuillez sélectionner le catalogue à l'aide du sélecteur de catalogue afin de consulter toutes les tables de fonctionnalités disponibles dans ce catalogue. Dans la zone de recherche, saisissez tout ou partie du nom d'une table de fonctionnalités, d'une fonctionnalité ou d'un commentaire. Vous pouvez également saisir tout ou partie de la clé ou de la valeur d'un tag. Le texte de recherche ne respecte pas la casse.

    Exemple de recherche de fonctionnalité

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

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

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

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

Vous pouvez utiliser des balises, qui sont de simples paires clé-valeur, 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 tags à l'aide de l'Explorateur de catalogues, d'instructions SQL dans un Notebook ou un éditeur de query SQL, ou de l'API Python d'ingénierie de Data Engineering.

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 un éditeur de query SQL.

Consultez Appliquer des balises aux objets sécurisables Unity Catalog et API Python de Feature Engineering.

L’exemple suivant montre comment utiliser l'API Python de Feature Engineering pour créer, mettre à jour et supprimer des tags de table de fonctionnalités.

Python
from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()

# Create feature table with tags
customer_feature_table = fe.create_table(
  # ...
  tags={&quot;tag_key_1&quot;: &quot;tag_value_1&quot;, &quot;tag_key_2&quot;: &quot;tag_value_2&quot;, ...},
  # ...
)

# 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 catalogues ou à l'aide de l'API Python de Feature Engineering.

remarque
  • La suppression d'une table de fonctionnalités peut entraîner des défaillances imprévues chez les producteurs en amont et les consommateurs en aval (modèles, Endpoint et Job planifiés). Vous devez supprimer les boutiques en ligne publiées 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 pris en charge dans Databricks Runtime 13,1 ML ou version antérieure. 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 :

SQL
DROP TABLE ml.recommender_system.customer_features;

Partager une table de fonctionnalités dans Unity Catalog entre les Workspace ou les comptes​

Une table de fonctionnalités dans Unity Catalog est accessible à tous les workspaces attribués au metastore Unity Catalog de la table.

Pour partager une table de caractéristiques avec des workspaces qui ne sont pas attribués au même metastore Unity Catalog, utilisez OpenSharing.

Dépannage​

Message d'erreur : Feature tables must have a primary key

La table de caractéristiques doit avoir une contrainte de clé primaire. Voir Utiliser une table Delta existante dans Unity Catalog comme table de caractéristiques.

Exemples de Notebooks​

Le Notebook de base montre comment créer une table de fonctionnalités, l'utiliser pour entraîner un modèle et exécuter un scoring par batch à l'aide de la recherche automatique de fonctionnalités. Il affiche également l'interface utilisateur d'ingénierie des fonctionnalités, que vous pouvez utiliser pour rechercher des fonctionnalités et comprendre comment celles-ci sont créées et utilisées.

Notebook d'exemple de Feature Engineering de base dans Unity Catalog

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

Le Notebook d'exemple du taxi illustre le processus de création de fonctionnalités, leur mise à jour et leur utilisation pour l'entraînement de modèles et l'inférence par batch.

Notebook d'exemple de Feature Engineering dans Unity Catalog pour les taxis

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks
Sur cette page