Fonction ML.FEATURES_AT_TIME

Ce document décrit la fonction ML.FEATURES_AT_TIME, qui vous permet d'utiliser une limite à un moment précis pour toutes les 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 afin d'utiliser la même limite à un moment précis pour toutes les entités lors de la récupération de caractéristiques. La fonction ML.ENTITY_FEATURES_AT_TIME permet de récupérer des caractéristiques à partir de plusieurs moments pour plusieurs entités.

Syntaxe

ML.FEATURES_AT_TIME(
   { TABLE feature_table | (query_statement) }
   [, time => TIMESTAMP][, num_rows => INT64][, ignore_feature_nulls => BOOL])

Arguments

ML.FEATURES_AT_TIME utilise les arguments suivants :

• feature_table est le nom de la table BigQuery qui contient 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.

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

• time : valeur TIMESTAMP spécifiant le moment précis à utiliser comme limite pour les données de caractéristiques. Seules les lignes dont la valeur dans la colonne feature_timestamp est égale ou antérieure à la valeur time sont renvoyées. Il s'agit par défaut de la valeur de la fonction CURRENT_TIMESTAMP.

• num_rows : valeur INT64 spécifiant le nombre de lignes à renvoyer pour chaque ID d'entité. 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 des caractéristiques suivante :

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

  Si vous exécutez cette requête :

  SELECT *
  FROM
    ML.FEATURES_AT_TIME(
      TABLE mydataset.feature_table,
      time => '2022-06-11 10:00:00+00',
      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

La fonction ML.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 saisi dans l'argument time.

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 2023-01-01 12:00:00+00 :

CREATE OR REPLACE
  `mydataset.mymodel` OPTIONS (WARM_START = TRUE)
AS
SELECT * EXCEPT (feature_timestamp, entity_id)
FROM
  ML.FEATURES_AT_TIME(
    TABLE `mydataset.feature_table`,
    time => '2023-01-01 12:00:00+00',
    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 2023-01-01 12:00:00+00 :

SELECT
  *
FROM
  ML.PREDICT(
    MODEL `mydataset.mymodel`,
    (
      SELECT * EXCEPT (feature_timestamp, entity_id)
      FROM
        ML.FEATURES_AT_TIME(
          TABLE `mydataset.feature_table`,
          time => '2023-01-01 12:00:00+00',
          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')])
  )
SELECT *
FROM
  ML.FEATURES_AT_TIME(
    TABLE feature_table,
    time => '2022-06-12 10:00:00+00',
    num_rows => 1,
    ignore_feature_nulls => TRUE);