Fungsi ML.FEATURES_AT_TIME

Dokumen ini menjelaskan fungsi ML.FEATURES_AT_TIME, yang memungkinkan Anda menggunakan batas waktu tertentu untuk semua entity saat mengambil fitur, karena fitur dapat memiliki dependensi waktu jika menyertakan data yang sensitif terhadap waktu. Untuk menghindari kebocoran data, gunakan fitur titik waktu saat melatih model dan menjalankan inferensi.

Gunakan fungsi ini untuk menggunakan batas titik waktu yang sama untuk semua entity saat mengambil fitur. Gunakan ML.ENTITY_FEATURES_AT_TIME fungsi untuk mengambil fitur dari beberapa titik waktu untuk beberapa entity.

Sintaksis

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

Argumen

ML.FEATURES_AT_TIME menggunakan argumen berikut:

• feature_table adalah nama tabel BigQuery yang berisi data fitur. Tabel fitur harus berisi kolom berikut:

  • entity_id: kolom STRING yang berisi ID entity yang terkait dengan fitur.
  • Satu atau beberapa kolom fitur.
  • feature_timestamp: kolom TIMESTAMP yang mengidentifikasi kapan data fitur terakhir diperbarui.

  Nama kolom tidak peka huruf besar/kecil. Misalnya, Anda dapat menggunakan kolom bernama Entity_ID, bukan entity_id.

  Tabel fitur harus dalam format lebar, dengan satu kolom untuk setiap fitur.

• query_statement: nilai STRING yang menentukan kueri GoogleSQL yang menampilkan data fitur. Kueri ini harus menampilkan kolom yang sama dengan feature_table. Lihat sintaksis kueri GoogleSQL untuk mengetahui sintaksis SQL yang didukung dalam klausa query_statement.

• time: nilai TIMESTAMP yang menentukan titik waktu yang akan digunakan sebagai batas untuk data fitur. Hanya baris yang nilai di kolom feature_timestamp-nya sama dengan atau lebih awal dari nilai time yang ditampilkan. Default atas nilai fungsi CURRENT_TIMESTAMP.

• num_rows: nilai INT64 yang menentukan jumlah baris yang akan ditampilkan untuk setiap ID entity. Setelan defaultnya adalah 1.

• ignore_feature_nulls: nilai BOOL yang menunjukkan apakah akan mengganti nilai NULL di kolom fitur dengan nilai kolom fitur dari baris untuk entity yang sama yang mendahuluinya tepat pada waktunya. Misalnya, untuk tabel fitur berikut:

  +-----------+------+------+--------------------------+
  | 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' |
  +-----------+------+------+--------------------------+
  

  Menjalankan kueri ini:

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

  Menghasilkan output berikut, dengan nilai f2 dari baris untuk ID entity 2 yang diberi stempel waktu '2022-06-10 12:00:00+00' diganti dengan nilai NULL dalam baris yang diberi stempel waktu '2022-06-11 10:00:00+00':

  +-----------+------+------+--------------------------+
  | entity_id | f1   | f2   | feature_timestamp        |
  +-----------+------+------+--------------------------+
  | '2'       | 7.0  | 4.0  | '2022-06-11 10:00:00+00' |
  +-----------+------+------+--------------------------+
  

  Jika tidak ada nilai pengganti yang tersedia, misalnya, jika tidak ada baris sebelumnya untuk ID entity tersebut, nilai NULL akan ditampilkan.

  Nilai defaultnya adalah FALSE.

Output

Fungsi ML.FEATURES_AT_TIME menampilkan baris tabel input yang memenuhi kriteria batas waktu tertentu, dengan kolom feature_timestamp yang menampilkan stempel waktu yang dimasukkan dalam argumen time.

Contoh

Contoh 1

Contoh ini menunjukkan cara melatih ulang model hanya menggunakan fitur yang dibuat atau diperbarui sebelum 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);

Contoh 2

Contoh ini menunjukkan cara mendapatkan prediksi dari model berdasarkan fitur yang dibuat atau diperbarui sebelum 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)
    )
  );

Contoh 3

Berikut adalah contoh rumit yang dapat Anda gunakan untuk melihat output fungsi:

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