La función ML.FEATURES_AT_TIME

En este documento, se describe la función ML.FEATURES_AT_TIME, que te permite usar un cortes de un momento determinado para todas las entidades cuando recuperas atributos, ya que los atributos pueden tener dependencias de tiempo si incluyen datos sensibles al tiempo. Para evitar la filtración de datos, usa las funciones de un momento determinado cuando entrenes modelos y ejecute inferencias.

Usa esta función para usar el mismo corte de un momento determinado para todas las entidades cuando se recuperan los atributos. Usa la función ML.ENTITY_FEATURES_AT_TIME para recuperar atributos de varios puntos en el tiempo para varias entidades.

Sintaxis

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

Argumentos

ML.FEATURES_AT_TIME toma los siguientes argumentos:

• feature_table es el nombre de la tabla de BigQuery que contiene los datos de los atributos. La tabla de atributos debe contener las siguientes columnas:

  • entity_id: una columna STRING que contiene el ID de la entidad relacionada con los atributos.
  • Una o más columnas de atributos.
  • feature_timestamp: una columna TIMESTAMP que identifica cuándo se actualizaron los datos de los atributos por última vez.

  Los nombres de columna no distinguen mayúsculas de minúsculas. Por ejemplo, puedes usar una columna llamada Entity_ID en lugar de entity_id.

  La tabla de atributos debe estar en formato ancho y una columna para cada atributo.

• query_statement: un valor STRING que especifica una consulta de GoogleSQL que muestra los datos del atributo. Esta consulta debe mostrar las mismas columnas que feature_table. Consulta la sintaxis de consultas de Google SQL para conocer la sintaxis de SQL admitida de la cláusula query_statement.

• time: un valor TIMESTAMP que especifica el momento determinado que se usará como un corte para los datos de atributos. Solo se muestran las filas en las que el valor de la columna feature_timestamp es igual o anterior al valor de time. El valor predeterminado es el valor de la función CURRENT_TIMESTAMP.

• num_rows: un valor INT64 que especifica la cantidad de filas que se mostrarán para cada ID de entidad. La configuración predeterminada es 1.

• ignore_feature_nulls: un valor BOOL que indica si se debe reemplazar un valor de NULL en una columna de atributos por el valor de la columna de atributos de la fila de la misma entidad que lo precede de inmediato. Por ejemplo, en la siguiente tabla de atributos:

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

  Ejecuta esta consulta:

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

  Da como resultado el siguiente resultado, en el que el valor f2 de la fila del ID de entidad 2 con la marca de tiempo '2022-06-10 12:00:00+00' se reemplaza por el valor NULL en la fila con la marca de tiempo '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' |
  +-----------+------+------+--------------------------+
  

  Si no hay un valor de reemplazo disponible, por ejemplo, si no hay una fila anterior para ese ID de entidad, se muestra un valor NULL.

  La configuración predeterminada es FALSE.

Salida

La función ML.FEATURES_AT_TIME muestra las filas de la tabla de entrada que cumplen con los criterios de corte de un momento determinado, y la columna feature_timestamp muestra la marca de tiempo que se ingresó en el argumento time.

Ejemplos

Ejemplo 1

En este ejemplo, se muestra cómo volver a entrenar un modelo con solo los atributos que se crearon o actualizaron antes del 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);

Ejemplo 2

En este ejemplo, se muestra cómo obtener predicciones de un modelo según los atributos que se crearon o actualizaron antes de 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)
    )
  );

Ejemplo 3

Este es un ejemplo conveniente que puedes usar para ver el resultado de la función:

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