Função ML.ENTITY_FEATURES_AT_TIME

Neste documento, descrevemos a função ML.ENTITY_FEATURES_AT_TIME, que permite usar várias limitações pontuais para diversas entidades ao recuperar recursos, já que os recursos podem ter dependências de tempo se incluírem dados sensíveis ao tempo. de dois minutos. Para evitar o vazamento de dados, use recursos pontuais ao treinar modelos e executar inferências.

Use essa função para recuperar atributos de várias entidades em vários pontos no tempo. Por exemplo, é possível recuperar os recursos criados em ou antes de três momentos diferentes para a entidade 1 e os recursos criados em ou antes de outro momento diferente para a entidade 2. Use a função ML.FEATURES_AT_TIME para aplicar a mesma interrupção pontual para todas as entidades ao recuperar recursos.

Sintaxe

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

Argumentos

ML.ENTITY_FEATURES_AT_TIME usa os seguintes argumentos:

• feature_table: um valor STRING que especifica 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.

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

• entity_time_table: um valor STRING que especifica o nome da tabela do BigQuery que mapeia os IDs de entidade para os tempos de pesquisa de atributos. A tabela de horários da entidade precisa ter as seguintes colunas:

  • entity_id: uma coluna STRING que contém o ID da entidade.
  • time: uma coluna TIMESTAMP que identifica um momento a ser usado como horário limite ao selecionar recursos para a entidade representada pelo ID.

  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 identificada por entity_time_table não pode ter mais de 100 MB.

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

• num_rows: um valor INT64 que especifica o número de linhas a serem retornadas para cada linha em entity_time_table. 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 e a tabela de horário da entidade a seguir:

  Tabela de recursos

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

  Tabela de horários da entidade

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

  Executando esta consulta:

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

ML.ENTITY_FEATURES_AT_TIME retorna as linhas da tabela de entrada que atendem aos critérios de corte pontual, com a coluna feature_timestamp mostrando o carimbo de data/hora da coluna time da tabela de horários da entidade.

Como é possível especificar vários pontos no tempo para recuperar atributos da mesma entidade, é possível retornar linhas duplicadas, dependendo dos carimbos de data/hora nas tabelas de horários de atributos e entidades e o num_rows valor especificado por você. Por exemplo, se a única linha na tabela de atributos do ID da entidade 1 tiver um carimbo de data/hora 2022-06-11 10:00:00+00 e você tiver duas linhas para o ID 1 na tabela de horários da entidade que tenham carimbos de data/hora posteriores, a função tem duas linhas com os mesmos dados de recursos para o ID da entidade 1.

Se uma das condições a seguir for verdadeira:

• Nenhum ID de entidade da tabela de horários de entidades foi encontrado na tabela de recursos.
• As linhas na tabela de atributos com códigos de entidade que correspondem aos da tabela de horários não atendem aos critérios específicos.

A função não retorna nenhuma saída para essa linha da tabela de horários da entidade.

Examples

Exemplo 1

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

Exemplo 2

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

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