Fungsi ML.ENTITY_FEATURES_AT_TIME

Dokumen ini menjelaskan fungsi ML.ENTITY_FEATURES_AT_TIME, yang memungkinkan Anda menggunakan beberapa batas waktu untuk beberapa 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 mengambil fitur dari beberapa entity untuk beberapa titik waktu. Misalnya, Anda dapat mengambil fitur yang dibuat pada atau sebelum tiga titik waktu yang berbeda untuk entity 1, dan fitur yang dibuat pada atau sebelum titik waktu yang berbeda untuk entity 2. Gunakan fungsi ML.FEATURES_AT_TIME untuk menggunakan batas waktu tertentu yang sama untuk semua entity saat mengambil fitur.

Sintaksis

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

Argumen

ML.ENTITY_FEATURES_AT_TIME menggunakan argumen berikut:

• feature_table: nilai STRING yang menentukan 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.

• feature_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 feature_query_statement.

• entity_time_table: nilai STRING yang menentukan nama tabel BigQuery yang memetakan ID entity ke waktu pencarian fitur. Tabel waktu entity harus berisi kolom berikut:

  • entity_id: kolom STRING yang berisi ID entity.
  • time: kolom TIMESTAMP yang mengidentifikasi titik waktu yang akan digunakan sebagai batas waktu saat memilih fitur untuk entity yang diwakili oleh ID entity.

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

  Tabel yang diidentifikasi oleh entity_time_table tidak boleh lebih besar dari 100 MB.

• entity_time_query_statement: nilai STRING yang menentukan kueri GoogleSQL yang menampilkan data waktu entity. Kueri ini harus menampilkan kolom yang sama dengan entity_time_table. Lihat sintaksis kueri GoogleSQL untuk mengetahui sintaksis SQL yang didukung dalam klausa entity_time_query_statement.

• num_rows: nilai INT64 yang menentukan jumlah baris yang akan ditampilkan untuk setiap baris dalam entity_time_table. 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 dan tabel waktu entity berikut:

  Tabel fitur

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

  Tabel waktu entity

  +-----------+--------------------------+
  | entity_id | time                     |
  +-----------+--------------------------+
  | '2'       | '2022-06-11 10:00:00+00' |
  +-----------+--------------------------+
  

  Menjalankan kueri ini:

  SELECT *
  FROM
    ML.ENTITY_FEATURES_AT_TIME(
      TABLE mydataset.feature_table,
      TABLE mydataset.entity_time_table,
      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

ML.ENTITY_FEATURES_AT_TIME menampilkan baris tabel input yang memenuhi kriteria batas waktu, dengan kolom feature_timestamp yang menampilkan stempel waktu dari kolom time tabel waktu entity.

Karena Anda dapat menentukan beberapa titik dalam waktu untuk mengambil fitur untuk entity yang sama, baris duplikat dapat ditampilkan, bergantung pada stempel waktu dalam tabel waktu fitur dan entity, serta num_rows nilai yang Anda tentukan. Misalnya, jika satu-satunya baris dalam tabel fitur untuk ID entity 1 memiliki stempel waktu 2022-06-11 10:00:00+00, dan Anda memiliki dua baris untuk ID entity 1 dalam tabel waktu entity yang keduanya memiliki stempel waktu lebih lama, fungsi output memiliki 2 baris dengan data fitur yang sama untuk ID entity 1.

Jika salah satu kondisi berikut terpenuhi:

• Tidak ada ID entity dari tabel waktu entity yang ditemukan dalam tabel fitur.
• Baris dalam tabel fitur yang ID entity-nya cocok dengan yang ada di tabel waktu entity tidak memenuhi kriteria titik waktu.

Kemudian, fungsi ini tidak menampilkan output apa pun untuk baris tabel waktu entity tersebut.

Contoh

Contoh 1

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

Contoh 2

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

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')])
  ),
  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);