Função ML.FEATURES_AT_TIME

Neste documento, descrevemos a função ML.FEATURES_AT_TIME, que permite usar um limite de tempo para todas as entidades ao recuperar recursos, já que os recursos podem ter dependências de tempo se incluírem dados sensíveis ao tempo. Para evitar o vazamento de dados, use recursos pontuais ao treinar modelos e executar inferências.

Use essa função para aplicar o mesmo limite de tempo para todas as entidades ao recuperar recursos. Use a função ML.ENTITY_FEATURES_AT_TIME para recuperar recursos de vários pontos no tempo para várias entidades.

Sintaxe

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

Argumentos

ML.FEATURES_AT_TIME usa os seguintes argumentos:

• feature_table é o nome da tabela do BigQuery que contém os dados do recurso. A tabela de recursos precisa ter as seguintes colunas:

  • entity_id: uma coluna STRING que contém o ID da entidade relacionada aos atributos.
  • Uma ou mais colunas de atributos.
  • feature_timestamp: uma coluna TIMESTAMP que identifica quando os dados do elemento foram atualizados pela última vez.

  Os nomes das colunas não diferenciam maiúsculas de minúsculas. Por exemplo, é possível usar uma coluna chamada Entity_ID em vez de entity_id.

  A tabela de recursos precisa estar no formato ampla, com uma coluna para cada recurso.

• query_statement: um valor STRING que especifica uma consulta do GoogleSQL que retorna os dados do recurso. Essa consulta precisa retornar as mesmas colunas que feature_table. Consulte a sintaxe de consulta do GoogleSQL para saber mais sobre a compatibilidade da cláusula query_statement.

• time: um valor TIMESTAMP que especifica o ponto no tempo a ser usado como um limite para dados de recursos. Apenas as linhas em que o valor na coluna feature_timestamp é igual ou anterior ao valor de time são retornadas. O padrão é o valor da função CURRENT_TIMESTAMP.

• num_rows: um valor INT64 que especifica o número de linhas a serem retornadas para cada ID de entidade. O padrão é 1.

• ignore_feature_nulls: um valor BOOL que indica se é necessário substituir um valor NULL em uma coluna de atributo pelo valor da coluna de atributo da linha da mesma entidade que a precede imediatamente no tempo. Por exemplo, para a tabela de recursos a seguir:

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

  Executando esta consulta:

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

  Resulta no resultado a seguir, em que o valor f2 da linha do ID da entidade 2 com carimbo de data/hora '2022-06-10 12:00:00+00' é substituído pelo valor NULL na linha com carimbo de data/hora '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' |
  +-----------+------+------+--------------------------+
  

  Se não houver um valor de substituição disponível, por exemplo, sem uma linha anterior para o ID da entidade, um valor NULL será retornado.

  O valor padrão é FALSE.

Saída

A função ML.FEATURES_AT_TIME retorna as linhas da tabela de entrada que atendem aos critérios de limite de horário, com a coluna feature_timestamp mostrando o carimbo de data/hora que foi inserido no argumento time.

Examples

Exemplo 1

Neste exemplo, mostramos como treinar novamente um modelo usando apenas recursos que foram criados ou atualizados antes de 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);

Exemplo 2

Neste exemplo, mostramos como receber previsões de um modelo com base nos recursos criados ou atualizados antes de 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)
    )
  );

Exemplo 3:

Este é um exemplo elaborado que pode ser usado para ver a saída da função:

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