ML.ENTITY_FEATURES_AT_TIME 函数

本文档介绍 ML.ENTITY_FEATURES_AT_TIME 函数，此函数可让您在检索特征时对多个实体使用多个截止时间点，因为如果特征包含时间敏感数据，则可能具有时间依赖项。为避免数据泄露，请在训练模型和运行推断时使用时间点功能。

使用此函数可以从多个实体检索多个时间点的特征。例如，您可以检索实体 1 在不晚于三个不同时间点创建的特征，以及检索实体 2 在不晚于另一个不同时间点创建的特征。在检索特征时，可以使用 ML.FEATURES_AT_TIME 函数对所有实体使用相同的截止时间点。

语法

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

参数

ML.ENTITY_FEATURES_AT_TIME 接受以下参数：

• feature_table：STRING 值，指定包含特征数据的 BigQuery 表的名称。特征表必须包含以下列：

  • entity_id：STRING 列，包含与特征相关的实体的 ID。
  • 一个或多个特征列。
  • feature_timestamp：TIMESTAMP 列，标识特征数据的上次更新时间。

  列名称不区分大小写。例如，您可以使用名为 Entity_ID 的列，而不是 entity_id。

  特征表必须采用宽格式，每个特征占一列。

• feature_query_statement：STRING 值，指定返回特征数据的 GoogleSQL 查询。此查询返回的列必须与 feature_table 相同。如需了解 feature_query_statement 子句支持的 SQL 语法，请参阅 GoogleSQL 查询语法。

• entity_time_table：STRING 值，指定将实体 ID 映射到特征查找时间的 BigQuery 表的名称。实体时间表必须包含以下列：

  • entity_id：包含实体 ID 的 STRING 列。
  • time：TIMESTAMP 列，标识在为实体 ID 表示的实体选择特征时用作截止时间的时间点。

  列名称不区分大小写。例如，您可以使用名为 Entity_ID 的列，而不是 entity_id。

  由 entity_time_table 标识的表不得大于 100 MB。

• entity_time_query_statement：STRING 值，指定返回实体时间数据的 GoogleSQL 查询。此查询返回的列必须与 entity_time_table 相同。如需了解 entity_time_query_statement 子句支持的 SQL 语法，请参阅 GoogleSQL 查询语法。

• num_rows：INT64 值，指定对于 entity_time_table 中的每一行要返回的行数。默认值为 1。

• ignore_feature_nulls：BOOL 值，指示是否将特征列中的 NULL 值替换为同一实体时间上最接近的前一行中的该特征列值。例如，对于以下特征表和实体时间表：

  特征表

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

  实体时间表

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

  运行此查询：

  SELECT *
  FROM
    ML.ENTITY_FEATURES_AT_TIME(
      TABLE mydataset.feature_table,
      TABLE mydataset.entity_time_table,
      num_rows => 1,
      ignore_feature_nulls => TRUE);
  

  产生以下输出，其中实体 ID 2 时间戳为 '2022-06-10 12:00:00+00' 的行中的 f2 值替换了时间戳为 '2022-06-11 10:00:00+00' 的行中的 NULL 值：

  +-----------+------+------+--------------------------+
  | entity_id | f1   | f2   | feature_timestamp        |
  +-----------+------+------+--------------------------+
  | '2'       | 7.0  | 4.0  | '2022-06-11 10:00:00+00' |
  +-----------+------+------+--------------------------+
  

  如果没有可用的替换值（例如，该实体 ID 没有更早的行），则返回 NULL 值。

  默认值为 FALSE。

输出

ML.ENTITY_FEATURES_AT_TIME 返回满足截止时间点条件的输入表行，其中 feature_timestamp 列显示实体时间表的 time 列中的时间戳。

由于您可以指定从同一实体的多个时间点检索特征，因此根据特征和实体时间表中的时间戳以及您指定的 num_rows 值，可能会返回重复的行。例如，如果特征表中实体 ID 1 只有一行，并具有时间戳 2022-06-11 10:00:00+00；同时，实体时间表中实体 ID 1 有两行，并均具有较晚的时间戳。则函数输出会包含两行，并均具有相同的实体 ID 1 特征值。

如果满足以下任一条件：

• 未在特征表中找到实体时间表中的实体 ID。
• 特征表中实体 ID 与实体时间表中实体 ID 匹配的行不满足时间点条件。

那么该函数不会返回该实体时间表行的任何输出。

示例

示例 1

此示例展示了如何仅使用在 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);

示例 2

此示例展示了如何根据在 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)
    )
  );

示例 3

这是一个虚构的示例，可用于查看函数的输出：

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