ML.FEATURES_AT_TIME 函数

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

在检索特征时，可以使用此函数对所有实体使用相同的截止时间点。如果要为多个实体检索多个时间点的特征，请使用 ML.ENTITY_FEATURES_AT_TIME 函数。

语法

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

参数

ML.FEATURES_AT_TIME 接受以下参数：

feature_table 是包含特征数据的 BigQuery 表的名称。特征表必须包含以下列：
- entity_id：STRING 列，包含与特征相关的实体的 ID。
- 一个或多个特征列。
- feature_timestamp：TIMESTAMP 列，标识特征数据的上次更新时间。
列名称不区分大小写。例如，您可以使用名为 Entity_ID 的列，而不是 entity_id。

特征表必须采用宽格式，每个特征占一列。
query_statement：STRING 值，指定返回特征数据的 GoogleSQL 查询。此查询返回的列必须与 feature_table 相同。如需了解 query_statement 子句支持的 SQL 语法，请参阅 GoogleSQL 查询语法。
time：TIMESTAMP 值，指定用作特征数据的截止时间的时间点。仅返回 feature_timestamp 列中的值等于或早于 time 值的行。默认为 CURRENT_TIMESTAMP 函数的值。
num_rows：INT64 值，指定为每个实体 ID 返回的行数。默认值为 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' |
+-----------+------+------+--------------------------+

运行此查询：

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

产生以下输出，其中实体 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.FEATURES_AT_TIME 函数返回满足截止时间点条件的输入表行，其中 feature_timestamp 列显示 time 参数中输入的时间戳。

示例

示例 1

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

示例 2

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

示例 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')])
  )
SELECT *
FROM
  ML.FEATURES_AT_TIME(
    TABLE feature_table,
    time => '2022-06-12 10:00:00+00',
    num_rows => 1,
    ignore_feature_nulls => TRUE);