ML.FEATURES_AT_TIME-Funktion

In diesem Dokument wird die Funktion ML.FEATURES_AT_TIME beschrieben, mit der Sie für alle Entitäten beim Abrufen von Features einen Zeitpunktgrenzwert verwenden können, da Features Zeitabhängigkeiten haben können, wenn sie zeitabhängige Daten enthalten. Verwenden Sie beim Trainieren von Modellen und Ausführen von Inferenzen Zeitpunkt-Features, um Datenlecks zu vermeiden.

Mit dieser Funktion können Sie beim Abrufen von Features für alle Entitäten denselben Zeitpunktgrenzwert verwenden. Mit der Funktion ML.ENTITY_FEATURES_AT_TIME können Sie Features für mehrere Zeitpunkte für mehrere Entitäten abrufen.

Syntax

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

Argumente

ML.FEATURES_AT_TIME verwendet die folgenden Argumente:

• feature_table ist der Name der BigQuery-Tabelle, die die Featuredaten enthält. Die Featuretabelle muss die folgenden Spalten enthalten:

  • entity_id: eine STRING-Spalte, die die ID der Entität enthält, auf die sich die Features beziehen.
  • Eine oder mehrere Featurespalten.
  • feature_timestamp: eine TIMESTAMP-Spalte, die angibt, wann die Featuredaten zuletzt aktualisiert wurden.

  Bei den Spaltennamen wird die Groß-/Kleinschreibung nicht berücksichtigt. Sie können beispielsweise eine Spalte namens Entity_ID anstelle von entity_id verwenden.

  Die Featuretabelle muss das breite Format mit einer Spalte pro Feature haben.

• query_statement: ein STRING-Wert, der eine GoogleSQL-Abfrage angibt, die die Featuredaten zurückgibt. Diese Abfrage muss die gleichen Spalten wie feature_table zurückgeben. Informationen zur unterstützten SQL-Syntax der query_statement-Klausel finden Sie unter GoogleSQL-Abfragesyntax.

• time: ein TIMESTAMP-Wert, der den Zeitpunkt angibt, der als Grenzwert für Featuredaten verwendet werden soll. Es werden nur Zeilen zurückgegeben, in denen der Wert in der Spalte feature_timestamp gleich oder früher als der Wert time ist. Die Standardeinstellung ist der Wert der Funktion CURRENT_TIMESTAMP.

• num_rows: ein INT64-Wert, der die Anzahl der Zeilen angibt, die für jede Entitäts-ID zurückgegeben werden sollen. Die Standardeinstellung ist 1.

• ignore_feature_nulls: ein BOOL-Wert, der angibt, ob ein NULL-Wert in einer Featurespalte durch den Featurespaltenwert aus der Zeile für dieselbe Entität ersetzt werden soll, die zeitlich unmittelbar vorangeht. Nehmen wir als Beispiel die folgende Featuretabelle:

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

  Wenn diese Abfrage ausgeführt wird:

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

  Wird Folgendes ausgegeben, wobei der Wert f2 aus der Zeile für Entitäts-ID 2 mit dem Zeitstempel '2022-06-10 12:00:00+00' durch den Wert NULL in der Zeile mit dem Zeitstempel '2022-06-11 10:00:00+00' ersetzt wird:

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

  Wenn es keinen Ersetzungswert gibt, z. B. wenn für diese Entitäts-ID keine vorherige Zeile vorhanden ist, wird ein NULL-Wert zurückgegeben.

  Die Standardeinstellung ist FALSE.

Ausgabe

Die Funktion ML.FEATURES_AT_TIME gibt die Zeilen der Eingabetabelle zurück, die die Kriterien für den Zeitpunktgrenzwert erfüllen, wobei die Spalte feature_timestamp den Zeitstempel enthält, der im Argument time eingegeben wurde.

Beispiele

Beispiel 1

In diesem Beispiel wird gezeigt, wie Sie ein Modell nur mit Features neu trainieren, die vor 2023-01-01 12:00:00+00 erstellt oder aktualisiert wurden:

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

Beispiel 2

In diesem Beispiel wird gezeigt, wie Sie aus einem Modell Vorhersagen auf Basis eines Features abrufen, das vor 2023-01-01 12:00:00+00 erstellt oder aktualisiert wurde:

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

Beispiel 3:

Dies ist ein etwas gekünsteltes Beispiel, mit dem Sie die Ausgabe der Funktion sehen können:

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