La funzione ML.FEATURES_AT_TIME

Questo documento descrive la funzione ML.FEATURES_AT_TIME, che consente di utilizzare un limite temporale specifico per tutte le entità quando si recuperano le funzionalità, poiché le caratteristiche possono avere dipendenze temporali se includono dati sensibili al tempo. Per evitare fuga di dati, utilizza le funzionalità point-in-time durante l'addestramento di modelli e l'esecuzione dell'inferenza.

Utilizza questa funzione per utilizzare lo stesso limite point-in-time per tutte le entità durante il recupero delle caratteristiche. Utilizza la funzione ML.ENTITY_FEATURES_AT_TIME per recuperare le caratteristiche da più punti nel tempo per più entità.

Sintassi

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

Argomenti

ML.FEATURES_AT_TIME accetta i seguenti argomenti:

• feature_table è il nome della tabella BigQuery che contiene i dati delle caratteristiche. La tabella delle caratteristiche deve contenere le seguenti colonne:

  • entity_id: una colonna STRING contenente l'ID dell'entità relativa alle caratteristiche.
  • Una o più colonne di funzionalità.
  • feature_timestamp: una colonna TIMESTAMP che identifica la data dell'ultimo aggiornamento dei dati sulle caratteristiche.

  I nomi delle colonne non fanno distinzione tra maiuscole e minuscole. Ad esempio, puoi utilizzare una colonna denominata Entity_ID anziché entity_id.

  La tabella degli elementi deve essere in formato larga, con una colonna per ogni elemento.

• query_statement: un valore STRING che specifica una query GoogleSQL che restituisce i dati della funzionalità. Questa query deve restituire le stesse colonne di feature_table. Consulta la pagina sulla sintassi delle query GoogleSQL per conoscere la sintassi SQL supportata della clausola query_statement.

• time: un valore TIMESTAMP che specifica il momento in cui utilizzare come limite per i dati della funzionalità. Vengono restituite solo le righe in cui il valore nella colonna feature_timestamp è uguale o precedente al valore time. Il valore predefinito è il valore della funzione CURRENT_TIMESTAMP.

• num_rows: un valore INT64 che specifica il numero di righe da restituire per ogni ID entità. Il valore predefinito è 1.

• ignore_feature_nulls: un valore BOOL che indica se sostituire un valore NULL in una colonna delle caratteristiche con il valore della colonna delle caratteristiche dalla riga della stessa entità che la precede immediatamente nel tempo. Ad esempio, per la seguente tabella delle funzionalità:

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

  Esecuzione di questa query:

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

  Restituisce il seguente output, dove il valore f2 della riga per l'ID entità 2 con timestamp '2022-06-10 12:00:00+00' viene sostituito per il valore NULL nella riga con timestamp '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' |
  +-----------+------+------+--------------------------+
  

  Se non è disponibile alcun valore sostitutivo, ad esempio se non è presente una riga precedente per quell'ID entità, viene restituito un valore NULL.

  Il valore predefinito è FALSE.

Output

La funzione ML.FEATURES_AT_TIME restituisce le righe della tabella di input che soddisfano i criteri di interruzione point-in-time. La colonna feature_timestamp mostra il timestamp inserito nell'argomento time.

Esempi

Esempio 1

Questo esempio mostra come riaddestrare un modello utilizzando solo le caratteristiche create o aggiornate prima del giorno 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);

Esempio 2

Questo esempio mostra come ottenere previsioni da un modello basato su caratteristiche create o aggiornate prima del giorno 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)
    )
  );

Esempio 3

Questo è un esempio artificioso che puoi utilizzare per vedere l'output della funzione:

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