ML.ENTITY_FEATURES_AT_TIME-Funktion

In diesem Dokument wird die Funktion ML.ENTITY_FEATURES_AT_TIME beschrieben, mit der Sie beim Abrufen von Features mehrere Zeitpunktgrenzwerte für mehrere Entitäten 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.

Verwenden Sie diese Funktion, um Features von mehreren Entitäten für mehrere Zeitpunkte abzurufen. Sie können beispielsweise Features abrufen, die zu oder vor drei verschiedenen Zeitpunkten für Entität 1 erstellt wurden, sowie Features abrufen, die zu oder vor einem anderen Zeitpunkt für Entität 2 erstellt wurden. Verwenden Sie die Funktion ML.FEATURES_AT_TIME, um beim Abrufen von Features für alle Entitäten denselben Zeitpunktgrenzwert zu verwenden.

Syntax

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

Argumente

ML.ENTITY_FEATURES_AT_TIME verwendet die folgenden Argumente:

• feature_table: ein STRING-Wert, der den Namen der BigQuery-Tabelle angibt, 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.

• feature_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 feature_query_statement-Klausel finden Sie unter GoogleSQL-Abfragesyntax.

• entity_time_table: ein STRING-Wert, der den Namen der BigQuery-Tabelle angibt, die Entitäts-IDs den Feature-Suchzeiten zuordnet. Die Entitätszeittabelle muss die folgenden Spalten enthalten:

  • entity_id: eine STRING-Spalte, die die Entitäts-ID enthält.
  • time: eine TIMESTAMP-Spalte, die einen Zeitpunkt angibt, der als Grenzwert verwendet werden soll, wenn Features für die Entität ausgewählt werden, die durch die Entitäts-ID repräsentiert wird.

  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 durch entity_time_table angegebene Tabelle darf nicht größer als 100 MB sein.

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

• num_rows: ein INT64-Wert, der die Anzahl der Zeilen angibt, die für jede Zeile in entity_time_table 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 und Entitätszeittabelle:

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

  Entitätszeittabelle

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

  Wenn diese Abfrage ausgeführt wird:

  SELECT *
  FROM
    ML.ENTITY_FEATURES_AT_TIME(
      TABLE mydataset.feature_table,
      TABLE mydataset.entity_time_table,
      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

ML.ENTITY_FEATURES_AT_TIME gibt die Eingabetabellenzeilen zurück, die die Kriterien für den Zeitpunktgrenzwert erfüllen, wobei die Spalte feature_timestamp den Zeitstempel aus der Spalte time der Entitätszeittabelle anzeigt.

Da Sie mehrere Zeitpunkte angeben können, ab denen Features für dieselbe Entität abgerufen werden sollen, ist es möglich, doppelte Zeilen zurückzugeben, abhängig von den Zeitstempeln in den Feature- und Entitätszeittabellen sowie dem angegebenen num_rows-Wert. Wenn beispielsweise die einzige Zeile in der Featuretabelle für die Entitäts-ID 1 den Zeitstempel 2022-06-11 10:00:00+00 hat und Sie in der Entitätszeittabelle zwei Zeilen für die Entitäts-ID 1 haben, die beide spätere Zeitstempel haben, enthält die Funktionsausgabe 2 Zeilen mit denselben Featuredaten für die Entitäts-ID 1.

Wenn eine der folgenden Bedingungen erfüllt ist:

• In der Featuretabelle wurden keine Entitäts-IDs aus der Entitätszeittabelle gefunden.
• Die Zeilen in der Featuretabelle, deren Entitäts-IDs mit denen in der Entitätszeittabelle übereinstimmen, erfüllen nicht die Zeitpunktkriterien.

Dann generiert die Funktion keine Ausgabe für diese Zeile der Entitätszeittabelle.

Beispiele

Beispiel 1

In diesem Beispiel wird gezeigt, wie Sie ein Modell nur mit Features neu trainieren, die vor den in mydataset.entity_time_table angegebenen Zeitstempeln erstellt oder aktualisiert wurden:

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

Beispiel 2

In diesem Beispiel wird gezeigt, wie Sie aus einem Modell Vorhersagen auf Basis eines Features abrufen, das vor den in mydataset.entity_time_table angegebenen Zeitstempeln erstellt oder aktualisiert wurde:

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

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')])
  ),
  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);