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: 특성과 관련된 항목의 ID가 포함된 STRING 열입니다.
  • 하나 이상의 특성 열입니다.
  • feature_timestamp: 특성 데이터가 마지막으로 업데이트된 시간을 식별하는 TIMESTAMP 열입니다.

  열 이름은 대소문자를 구분하지 않습니다. 예를 들어 entity_id 대신 Entity_ID 열을 사용할 수 있습니다.

  특성 테이블은 와이드 형식이어야 하며, 각 특성에 대해 하나의 열이 있어야 합니다.

• query_statement: 특성 데이터를 반환하는 GoogleSQL 쿼리를 지정하는 STRING 값입니다. 이 쿼리는 feature_table과 동일한 열을 반환해야 합니다. 지원되는 query_statement 절의 SQL 구문은 GoogleSQL 쿼리 구문을 참조하세요.

• time: 특성 데이터의 컷오프로 사용할 특정 시점을 지정하는 TIMESTAMP 값입니다. feature_timestamp 열의 값이 time 값과 같거나 이전인 행만 반환됩니다. 기본값은 CURRENT_TIMESTAMP 함수 값입니다.

• num_rows: 각 항목 ID에 대해 반환할 행 수를 지정하는 INT64 값입니다. 기본값은 1입니다.

• ignore_feature_nulls: 특성 열의 NULL 값을 바로 이전의 동일한 항목 행의 특성 열 값으로 대체할지 여부를 나타내는 BOOL 값입니다. 다음 특성 테이블의 경우를 예로 들어보겠습니다.

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

  다음과 같은 출력이 표시됩니다. 여기서 타임스탬프가 '2022-06-10 12:00:00+00'인 항목 ID 2의 행에 있는 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);