Fonction ML.ENTITY_FEATURES_AT_TIME

Ce document décrit la fonction ML.ENTITY_FEATURES_AT_TIME, qui vous permet d'utiliser plusieurs limites à un moment précis pour plusieurs entités lors de la récupération de caractéristiques. Celles-ci peuvent en effet présenter des dépendances temporelles si elles incluent des données à durée limitée. Pour éviter les fuites de données, utilisez les caractéristiques à un moment précis lors de l'entraînement de modèles et de l'exécution d'inférences.

Utilisez cette fonction pour récupérer les caractéristiques de plusieurs entités à plusieurs moments précis. Par exemple, vous pouvez récupérer les caractéristiques créées à un moment précis ou avant trois moments précis différents pour l'entité 1, et les caractéristiques créées à un moment précis ou avant un autre moment pour l'entité 2. Lorsque vous récupérez des caractéristiques, utilisez la fonction ML.FEATURES_AT_TIME pour utiliser la même limite à un moment précis pour toutes les entités.

Syntaxe

ML.ENTITY_FEATURES_AT_TIME(
  { TABLE feature_table | (feature_query_statement) },
  { TABLE entity_time_table | (entity_time_query_statement) }
  [, num_rows => INT64][, ignore_feature_nulls => BOOL])

Arguments

ML.ENTITY_FEATURES_AT_TIME utilise les arguments suivants :

• feature_table : valeur STRING qui spécifie le nom de la table BigQuery contenant les données de caractéristiques. La table des caractéristiques doit contenir les colonnes suivantes :

  • entity_id : colonne STRING contenant l'ID de l'entité associée aux caractéristiques.
  • Une ou plusieurs colonnes de caractéristiques.
  • feature_timestamp : colonne TIMESTAMP identifiant la dernière mise à jour des données de caractéristiques.

  Les noms de colonnes ne sont pas sensibles à la casse. Par exemple, vous pouvez utiliser une colonne nommée Entity_ID au lieu de entity_id.

  La table des caractéristiques doit être au format wide et contenir une colonne pour chaque caractéristique.

• feature_query_statement : valeur STRING spécifiant une requête GoogleSQL qui renvoie les données de caractéristiques. Cette requête doit renvoyer les mêmes colonnes que feature_table. Consultez la page Syntaxe des requêtes GoogleSQL pour connaître la syntaxe SQL compatible avec la clause feature_query_statement.

• entity_time_table : valeur STRING spécifiant le nom de la table BigQuery qui mappe les ID d'entité aux délais de recherche des caractéristiques. La table de temps des entités doit contenir les colonnes suivantes :

  • entity_id : colonne STRING contenant l'ID d'entité.
  • time : colonne TIMESTAMP qui identifie un moment précis à utiliser comme heure limite lors de la sélection de caractéristiques pour l'entité représentée par un ID.

  Les noms de colonnes ne sont pas sensibles à la casse. Par exemple, vous pouvez utiliser une colonne nommée Entity_ID au lieu de entity_id.

  La table identifiée par entity_time_table ne doit pas dépasser 100 Mo.

• entity_time_query_statement : valeur STRING spécifiant une requête GoogleSQL qui renvoie les données temporelles des entités. Cette requête doit renvoyer les mêmes colonnes que entity_time_table. Consultez la page Syntaxe des requêtes GoogleSQL pour connaître la syntaxe SQL compatible avec la clause entity_time_query_statement.

• num_rows : valeur INT64 spécifiant le nombre de lignes à renvoyer pour chaque ligne figurant dans entity_time_table. La valeur par défaut est 1.

• ignore_feature_nulls : valeur BOOL qui indique s'il faut remplacer une valeur NULL d'une colonne de caractéristiques par la valeur de la colonne de caractéristiques figurant sur la ligne de la même entité qui la précède immédiatement dans le temps. Par exemple, pour la table de caractéristiques et la table de temps des entités suivantes :

  Table des caractéristiques

  +-----------+------+------+--------------------------+
  | entity_id | f1   | f2   | feature_timestamp        |
  +-----------+------+------+--------------------------+
  | '2'       | 5.0  | 8.0  | '2022-06-10 09:00:00+00' |
  +-----------+------+------+--------------------------+
  | '2'       | 2.0  | 4.0  | '2022-06-10 12:00:00+00' |
  +-----------+------+------+--------------------------+
  | '2'       | 7.0  | NULL | '2022-06-11 10:00:00+00' |
  +-----------+------+------+--------------------------+
  

  Table de temps des entités

  +-----------+--------------------------+
  | entity_id | time                     |
  +-----------+--------------------------+
  | '2'       | '2022-06-11 10:00:00+00' |
  +-----------+--------------------------+
  

  Si vous exécutez cette requête :

  SELECT *
  FROM
    ML.ENTITY_FEATURES_AT_TIME(
      TABLE mydataset.feature_table,
      TABLE mydataset.entity_time_table,
      num_rows => 1,
      ignore_feature_nulls => TRUE);

  Elle renvoie la sortie suivante, où la valeur f2 de la ligne de l'ID d'entité 2 horodatée '2022-06-10 12:00:00+00' est remplacée par la valeur NULL dans la ligne horodatée '2022-06-11 10:00:00+00' :

  +-----------+------+------+--------------------------+
  | entity_id | f1   | f2   | feature_timestamp        |
  +-----------+------+------+--------------------------+
  | '2'       | 7.0  | 4.0  | '2022-06-11 10:00:00+00' |
  +-----------+------+------+--------------------------+
  

  Si aucune valeur de remplacement n'est disponible, par exemple lorsqu'il n'existe pas de ligne précédente pour cet ID d'entité, une valeur NULL est renvoyée.

  La valeur par défaut est FALSE.

Sortie

ML.ENTITY_FEATURES_AT_TIME renvoie les lignes de la table d'entrée qui correspondent aux critères de limite à un moment précis, avec la colonne feature_timestamp affichant le code temporel de la colonne time de la table de temps des entités.

Étant donné que vous pouvez spécifier plusieurs moments précis à partir desquels extraire des caractéristiques pour la même entité, il est possible de renvoyer des lignes en double en fonction des codes temporels des tables de caractéristiques et de temps des entités, et la valeur num_rows que vous spécifiez. Par exemple, si la seule ligne de la table des caractéristiques pour l'ID d'entité 1 est horodatée 2022-06-11 10:00:00+00 et que vous disposez de deux lignes pour l'ID d'entité 1 dans la table de temps des entités, dont les codes temporels sont postérieurs, la sortie de la fonction comporte deux lignes avec les mêmes données de caractéristiques pour l'ID d'entité 1.

Si l'une des conditions suivantes est remplie :

• Aucun ID d'entité de la table de temps des entités n'est trouvé dans la table de caractéristiques.
• Les lignes de la table de caractéristiques dont les ID d'entité correspondent à celles de la table de temps des entités ne répondent pas aux critères à un moment précis.

La fonction ne renvoie aucun résultat pour cette ligne de la table de temps des entités.

Examples

Exemple 1

Cet exemple montre comment réentraîner un modèle en n'utilisant que des caractéristiques créées ou mises à jour avant les codes temporels identifiés dans mydataset.entity_time_table :

CREATE OR REPLACE
  `mydataset.mymodel` OPTIONS (WARM_START = TRUE)
AS
SELECT * EXCEPT (feature_timestamp, entity_id)
FROM
  ML.ENTITY_FEATURES_AT_TIME(
    TABLE `mydataset.feature_table`,
    TABLE `mydataset.entity_time_table`,
    num_rows => 1,
    ignore_feature_nulls => TRUE);

Exemple 2

Cet exemple montre comment obtenir des prédictions à partir d'un modèle en fonction des caractéristiques créées ou mises à jour avant les codes temporels identifiés dans mydataset.entity_time_table :

SELECT
  *
FROM
  ML.PREDICT(
    MODEL `mydataset.mymodel`,
    (
      SELECT * EXCEPT (feature_timestamp, entity_id)
      FROM
        ML.ENTITY_FEATURES_AT_TIME(
          TABLE `mydataset.feature_table`,
          TABLE `mydataset.entity_time_table`,
          num_rows => 1,
          ignore_feature_nulls => TRUE)
    )
  );

Exemple 3

Voici un exemple factice que vous pouvez utiliser pour afficher la sortie de la fonction :

WITH
  feature_table AS (
    SELECT * FROM UNNEST(
      ARRAY<STRUCT<entity_id STRING, f_1 FLOAT64, f_2 FLOAT64, feature_timestamp TIMESTAMP>>[
        ('id1', 1.0, 1.0, TIMESTAMP '2022-06-10 12:00:00+00'),
        ('id2', 12.0, 24.0, TIMESTAMP '2022-06-11 12:00:00+00'),
        ('id1', 11.0, NULL, TIMESTAMP '2022-06-11 12:00:00+00'),
        ('id1', 6.0, 12.0, TIMESTAMP '2022-06-11 10:00:00+00'),
        ('id2', 2.0, 4.0, TIMESTAMP '2022-06-10 12:00:00+00'),
        ('id2', 7.0, NULL, TIMESTAMP '2022-06-11 10:00:00+00')])
  ),
  entity_time_table AS (
    SELECT * FROM UNNEST(
      ARRAY<STRUCT<entity_id STRING, time TIMESTAMP>>[
        ('id1', TIMESTAMP '2022-06-12 12:00:00+00'),
        ('id2', TIMESTAMP '2022-06-11 10:00:00+00'),
        ('id1', TIMESTAMP '2022-06-10 13:00:00+00')])
  )
SELECT *
FROM
  ML.ENTITY_FEATURES_AT_TIME(
    TABLE feature_table, TABLE entity_time_table, num_rows => 1, ignore_feature_nulls => TRUE);