Función ML.ENTITY_FEATURES_AT_TIME
En este documento, se describe la función ML.ENTITY_FEATURES_AT_TIME
, que te permite usar varios cortes de un momento determinado para varias entidades cuando recuperas atributos, ya que los atributos pueden tener dependencias de tiempo si incluyen datos sensibles al tiempo. Para evitar la filtración de datos, usa las funciones de un momento determinado cuando entrenes modelos y ejecute inferencias.
Usa esta función para recuperar atributos de varias entidades en varios puntos en el tiempo. Por ejemplo, puedes recuperar los atributos creados en o antes de tres puntos diferentes en la entidad 1 y los atributos creados en o antes de otro punto diferente en el tiempo para la entidad 2. Usa la función ML.FEATURES_AT_TIME
para usar el mismo límite de un momento determinado en todas las entidades cuando recuperas atributos.
Sintaxis
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
toma los siguientes argumentos:
feature_table
: un valorSTRING
que especifica el nombre de la tabla de BigQuery que contiene los datos de atributos. La tabla de atributos debe contener las siguientes columnas:entity_id
: una columnaSTRING
que contiene el ID de la entidad relacionada con los atributos.- Una o más columnas de atributos.
feature_timestamp
: una columnaTIMESTAMP
que identifica cuándo se actualizaron los datos de los atributos por última vez.
Los nombres de columna no distinguen mayúsculas de minúsculas. Por ejemplo, puedes usar una columna llamada
Entity_ID
en lugar deentity_id
.La tabla de atributos debe estar en formato ancho y una columna para cada atributo.
feature_query_statement
: un valorSTRING
que especifica una consulta de GoogleSQL que muestra los datos del atributo. Esta consulta debe mostrar las mismas columnas quefeature_table
. Consulta la sintaxis de consultas de Google SQL para conocer la sintaxis de SQL admitida de la cláusulafeature_query_statement
.entity_time_table
: Es un valorSTRING
que especifica el nombre de la tabla de BigQuery que asigna los IDs de entidad a los tiempos de búsqueda de los atributos. La tabla de tiempo de la entidad debe contener las siguientes columnas:entity_id
: Una columnaSTRING
que contiene el ID de la entidad.time
: Es una columnaTIMESTAMP
que identifica un momento determinado para usarlo como hora de corte cuando se seleccionan atributos para la entidad representada por el ID de la entidad.
Los nombres de columna no distinguen mayúsculas de minúsculas. Por ejemplo, puedes usar una columna llamada
Entity_ID
en lugar deentity_id
.La tabla identificada por
entity_time_table
no debe superar los 100 MB.entity_time_query_statement
: Es un valorSTRING
que especifica una consulta de GoogleSQL que muestra los datos de tiempo de la entidad. Esta consulta debe mostrar las mismas columnas queentity_time_table
. Consulta la sintaxis de consultas de Google SQL para conocer la sintaxis de SQL admitida de la cláusulaentity_time_query_statement
.num_rows
: Un valorINT64
que especifica la cantidad de filas que se muestran para cada fila enentity_time_table
. La configuración predeterminada es1
.ignore_feature_nulls
: un valorBOOL
que indica si se debe reemplazar un valor deNULL
en una columna de atributos por el valor de la columna de atributos de la fila de la misma entidad que lo precede de inmediato. Por ejemplo, para la siguiente tabla de atributos y la tabla de tiempo de la entidad:Tabla de atributos
+-----------+------+------+--------------------------+ | 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' | +-----------+------+------+--------------------------+
Tabla de tiempo de la entidad
+-----------+--------------------------+ | entity_id | time | +-----------+--------------------------+ | '2' | '2022-06-11 10:00:00+00' | +-----------+--------------------------+
Ejecuta 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);
Da como resultado el siguiente resultado, en el que el valor
f2
de la fila del ID de entidad 2 con la marca de tiempo'2022-06-10 12:00:00+00'
se reemplaza por el valorNULL
en la fila con la marca de tiempo'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' | +-----------+------+------+--------------------------+
Si no hay un valor de reemplazo disponible, por ejemplo, si no hay una fila anterior para ese ID de entidad, se muestra un valor
NULL
.La configuración predeterminada es
FALSE
.
Salida
ML.ENTITY_FEATURES_AT_TIME
muestra las filas de la tabla de entrada que cumplen con los criterios de corte de un momento determinado, y la columna feature_timestamp
muestra la marca de tiempo de la columna time
de la tabla de tiempo de la entidad.
Debido a que puedes especificar varios momentos desde los cuales se recuperarán atributos para la misma entidad, es posible mostrar filas duplicadas, según las marcas de tiempo de las tablas de tiempo de entidades y atributos, y el num_rows
valor que especifiques. Por ejemplo, si la única fila en la tabla de atributos para el ID de entidad 1 tiene la marca de tiempo 2022-06-11 10:00:00+00
y tienes dos filas para el ID de entidad 1 en la tabla de tiempo de entidad, que tienen marcas de tiempo posteriores, la salida de la función tiene 2 filas con los mismos datos de atributos para el ID de entidad 1.
Si se cumple alguna de las siguientes condiciones:
- No se encontraron IDs de entidad en la tabla de atributos de tiempo.
- Las filas de la tabla de atributos cuyos IDs de entidad coinciden con los de la tabla de tiempo de entidad no cumplen con los criterios de un momento determinado.
Luego, la función no muestra ningún resultado para esa fila de la tabla de tiempo de la entidad.
Ejemplos
Ejemplo 1
En este ejemplo, se muestra cómo volver a entrenar un modelo con los atributos que se crearon o actualizaron antes de las marcas de tiempo identificadas en 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);
Ejemplo 2
En este ejemplo, se muestra cómo obtener predicciones a partir de un modelo basado en atributos que se crearon o actualizaron antes de las marcas de tiempo identificadas en 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) ) );
Ejemplo 3
Este es un ejemplo conveniente que puedes usar para ver el resultado de la función:
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);