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
: einSTRING
-Wert, der den Namen der BigQuery-Tabelle angibt, die die Featuredaten enthält. Die Featuretabelle muss die folgenden Spalten enthalten:entity_id
: eineSTRING
-Spalte, die die ID der Entität enthält, auf die sich die Features beziehen.- Eine oder mehrere Featurespalten.
feature_timestamp
: eineTIMESTAMP
-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 vonentity_id
verwenden.Die Featuretabelle muss das breite Format mit einer Spalte pro Feature haben.
feature_query_statement
: einSTRING
-Wert, der eine GoogleSQL-Abfrage angibt, die die Featuredaten zurückgibt. Diese Abfrage muss die gleichen Spalten wiefeature_table
zurückgeben. Informationen zur unterstützten SQL-Syntax derfeature_query_statement
-Klausel finden Sie unter GoogleSQL-Abfragesyntax.entity_time_table
: einSTRING
-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
: eineSTRING
-Spalte, die die Entitäts-ID enthält.time
: eineTIMESTAMP
-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 vonentity_id
verwenden.Die durch
entity_time_table
angegebene Tabelle darf nicht größer als 100 MB sein.entity_time_query_statement
: einSTRING
-Wert, der eine GoogleSQL-Abfrage angibt, die die Entitätszeitdaten zurückgibt. Diese Abfrage muss die gleichen Spalten wieentity_time_table
zurückgeben. Informationen zur unterstützten SQL-Syntax derentity_time_query_statement
-Klausel finden Sie unter GoogleSQL-Abfragesyntax.num_rows
: einINT64
-Wert, der die Anzahl der Zeilen angibt, die für jede Zeile inentity_time_table
zurückgegeben werden sollen. Die Standardeinstellung ist1
.ignore_feature_nulls
: einBOOL
-Wert, der angibt, ob einNULL
-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 WertNULL
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);