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: 특성 데이터가 포함된 BigQuery 테이블의 이름을 지정하는 STRING 값입니다. 특성 테이블에는 다음 열이 포함되어야 합니다.

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

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

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

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

• entity_time_table: 항목 조회 시간에 항목 ID를 매핑하는 BigQuery 테이블의 이름을 지정하는 STRING 값입니다. 항목 시간 테이블에는 다음 열이 포함되어야 합니다.

  • entity_id: 항목 ID가 포함된 STRING 열입니다.
  • time: 항목 ID로 표시된 항목의 특성을 선택할 때 마감 시간으로 사용할 특정 시점을 식별하는 TIMESTAMP 열입니다.

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

  entity_time_table에서 식별된 테이블은 100MB 이하여야 합니다.

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

• num_rows: entity_time_table의 각 행에 반환할 행 수를 지정하는 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' |
  +-----------+------+------+--------------------------+
  

  항목 시간 테이블

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

  다음과 같은 출력이 표시됩니다. 여기서 타임스탬프가 '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.ENTITY_FEATURES_AT_TIME는 특정 시점 마감 기준을 충족하는 입력 테이블 행을 반환합니다. feature_timestamp 열에는 항목 시간 테이블의 time 열에 있는 타임스탬프가 표시됩니다.

동일한 항목의 특성을 검색할 특정 시점을 여러 개 지정할 수 있으므로 특성 및 항목 시간 테이블의 타임스탬프 및 지정한 num_rows 값에 따라 중복된 행을 반환할 수 있습니다. 예를 들어 항목 ID 1의 특성 테이블에 있는 유일한 행의 타임스탬프가 2022-06-11 10:00:00+00이고 항목 시간 테이블에 항목 ID 1에 대해 더 늦은 타임스탬프가 있는 두 개의 행이 있는 경우 함수 출력에 항목 ID 1에 대해 동일한 특성 데이터가 있는 행이 2개 포함됩니다.

다음 조건 중 하나에 해당하는 경우:

• 항목 시간 테이블의 항목 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);