Función ML.ENTITY_FEATURES_AT_TIME

En este documento, se describe la función ML.ENTITY_FEATURES_AT_TIME, que te permite usar varios cortes de un momento determinado para varias 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 recuperar atributos de varias entidades en varios puntos en el tiempo. Por ejemplo, puedes recuperar los atributos creados en o antes de tres puntos diferentes en la entidad 1 y los atributos creados en o antes de otro punto diferente en el tiempo para la entidad 2. Usa la función ML.FEATURES_AT_TIME para usar el mismo límite de un momento determinado en todas las entidades cuando recuperas atributos.

Sintaxis

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

Argumentos

ML.ENTITY_FEATURES_AT_TIME toma los siguientes argumentos:

• feature_table: un valor STRING que especifica el nombre de la tabla de BigQuery que contiene los datos de 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.

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

• entity_time_table: Es un valor STRING que especifica el nombre de la tabla de BigQuery que asigna los IDs de entidad a los tiempos de búsqueda de los atributos. La tabla de tiempo de la entidad debe contener las siguientes columnas:

  • entity_id: Una columna STRING que contiene el ID de la entidad.
  • time: Es una columna TIMESTAMP que identifica un momento determinado para usarlo como hora de corte cuando se seleccionan atributos para la entidad representada por el ID de la entidad.

  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 identificada por entity_time_table no debe superar los 100 MB.

• entity_time_query_statement: Es un valor STRING que especifica una consulta de GoogleSQL que muestra los datos de tiempo de la entidad. Esta consulta debe mostrar las mismas columnas que entity_time_table. Consulta la sintaxis de consultas de Google SQL para conocer la sintaxis de SQL admitida de la cláusula entity_time_query_statement.

• num_rows: Un valor INT64 que especifica la cantidad de filas que se muestran para cada fila en entity_time_table. 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, para la siguiente tabla de atributos y la tabla de tiempo de la entidad:

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

  Tabla de tiempo de la entidad

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

  Ejecuta esta consulta:

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

ML.ENTITY_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 de la columna time de la tabla de tiempo de la entidad.

Debido a que puedes especificar varios momentos desde los cuales se recuperarán atributos para la misma entidad, es posible mostrar filas duplicadas, según las marcas de tiempo de las tablas de tiempo de entidades y atributos, y el num_rows valor que especifiques. Por ejemplo, si la única fila en la tabla de atributos para el ID de entidad 1 tiene la marca de tiempo 2022-06-11 10:00:00+00 y tienes dos filas para el ID de entidad 1 en la tabla de tiempo de entidad, que tienen marcas de tiempo posteriores, la salida de la función tiene 2 filas con los mismos datos de atributos para el ID de entidad 1.

Si se cumple alguna de las siguientes condiciones:

• No se encontraron IDs de entidad en la tabla de atributos de tiempo.
• Las filas de la tabla de atributos cuyos IDs de entidad coinciden con los de la tabla de tiempo de entidad no cumplen con los criterios de un momento determinado.

Luego, la función no muestra ningún resultado para esa fila de la tabla de tiempo de la entidad.

Ejemplos

Ejemplo 1

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

Ejemplo 2

En este ejemplo, se muestra cómo obtener predicciones a partir de un modelo basado en atributos que se crearon o actualizaron antes de las marcas de tiempo identificadas en 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)
    )
  );

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