La funzione ML.ENTITY_FEATURES_AT_TIME

Questo documento descrive la funzione ML.ENTITY_FEATURES_AT_TIME, che consente di utilizzare più interruzioni point-in-time per più entità durante il recupero delle caratteristiche, poiché le funzionalità 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 recuperare caratteristiche da più entità per più punti nel tempo. Ad esempio, puoi recuperare le caratteristiche create prima o in tre momenti diversi per l'entità 1 e le caratteristiche create prima o in un altro momento diverso per l'entità 2. Utilizza la funzione ML.FEATURES_AT_TIME per utilizzare lo stesso limite temporale per tutte le entità quando recuperi le caratteristiche.

Sintassi

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

Argomenti

ML.ENTITY_FEATURES_AT_TIME accetta i seguenti argomenti:

• feature_table: un valore STRING che specifica il nome della tabella BigQuery contenente 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.

• feature_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 feature_query_statement.

• entity_time_table: un valore STRING che specifica il nome della tabella BigQuery che mappa gli ID entità ai tempi di ricerca delle caratteristiche. La tabella temporale delle entità deve contenere le seguenti colonne:

  • entity_id: una colonna STRING contenente l'ID entità.
  • time: una colonna TIMESTAMP che identifica un momento specifico da utilizzare come orario limite quando selezioni le funzionalità per l'entità rappresentata dall'ID entità.

  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 identificata da entity_time_table non deve superare 100 MB.

• entity_time_query_statement: un valore STRING che specifica una query GoogleSQL che restituisce i dati relativi alla durata dell'entità. Questa query deve restituire le stesse colonne di entity_time_table. Consulta la pagina sulla sintassi delle query GoogleSQL per conoscere la sintassi SQL supportata della clausola entity_time_query_statement.

• num_rows: un valore INT64 che specifica il numero di righe da restituire per ogni riga in entity_time_table. 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à e della tabella temporale delle entità:

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

  Orari delle entità

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

  Esecuzione di questa query:

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

ML.ENTITY_FEATURES_AT_TIME restituisce le righe della tabella di input che soddisfano i criteri di interruzione point-in-time, con la colonna feature_timestamp che mostra il timestamp dalla colonna time della tabella temporale dell'entità.

Poiché puoi specificare più punti nel tempo da cui recuperare le caratteristiche per la stessa entità, è possibile restituire righe duplicate, a seconda dei timestamp nelle tabelle temporali delle caratteristiche e delle entità e il valore num_rows specificato. Ad esempio, se l'unica riga nella tabella delle funzionalità per l'ID entità 1 ha il timestamp 2022-06-11 10:00:00+00 e nella tabella temporale dell'entità sono presenti due righe per l'ID entità 1 che hanno entrambe timestamp successivi, l'output della funzione avrà 2 righe con gli stessi dati delle caratteristiche per l'ID entità 1.

Se si verifica una delle seguenti condizioni:

• Nessun ID entità della tabella temporale delle entità trovato nella tabella delle funzionalità.
• Le righe nella tabella delle caratteristiche i cui ID entità corrispondono a quelli nella tabella temporale delle entità non soddisfano i criteri del momento.

Quindi la funzione non restituisce alcun output per quella riga della tabella tempo dell'entità.

Esempi

Esempio 1

Questo esempio mostra come riaddestrare un modello utilizzando solo le caratteristiche che sono state create o aggiornate prima dei timestamp identificati in mydataset.entity_time_table:

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

Esempio 2

Questo esempio mostra come ottenere previsioni da un modello in base alle caratteristiche create o aggiornate prima dei timestamp identificati in mydataset.entity_time_table:

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

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