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