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_idSTRING 列,包含与特征相关的实体的 ID。
    • 一个或多个特征列。
    • feature_timestampTIMESTAMP 列,标识特征数据的上次更新时间。

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

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

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

  • timeTIMESTAMP 值,指定用作特征数据的截止时间的时间点。仅返回 feature_timestamp 列中的值等于或早于 time 值的行。默认为 CURRENT_TIMESTAMP 函数的值。

  • num_rowsINT64 值,指定为每个实体 ID 返回的行数。默认值为 1

  • ignore_feature_nullsBOOL 值,指示是否将特征列中的 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);