Ingeniería de características en Unity Catalog

Artículo
06/28/2024

En esta página se describe cómo crear y trabajar con tablas de características en el catálogo de Unity.

Esta página solo se aplica a las áreas de trabajo habilitadas para el catálogo de Unity. Si el área de trabajo no está habilitada para Unity Catalog, consulte Uso de características en el almacén de características del área de trabajo.

Para más información sobre los comandos y parámetros usados en los ejemplos de esta página, vea la Referencia de la API de Python de ingeniería de características.

Requisitos

La ingeniería de características en el catálogo de Unity requiere Databricks Runtime 13.2 o superior. Además, el metastore del catálogo de Unity debe tener la versión 1.0 del modelo de privilegios.

Instalación de la ingeniería de características en el cliente Python del catálogo de Unity

La ingeniería de características en Unity Catalog tiene un cliente de Python FeatureEngineeringClient. La clase está disponible en PyPI con el paquete databricks-feature-engineering y está preinstalada en Databricks Runtime 13.3 LTS ML y versiones posteriores. Si usa un Databricks Runtime que no sea de ML, debe instalar el cliente manualmente. Use la matriz de compatibilidad para encontrar la versión correcta de la versión de Databricks Runtime.

%pip install databricks-feature-engineering

dbutils.library.restartPython()

Creación de un catálogo y un esquema para tablas de características en el catálogo de Unity

Es necesario crear un catálogo nuevo o usar un catálogo existente para las tablas de características.

Para crear un nuevo catálogo, se necesita tener el privilegio CREATE CATALOG en el metastore.

CREATE CATALOG IF NOT EXISTS <catalog-name>

Para usar un catálogo existente, deberá tener el privilegio USE CATALOG en el catálogo.

USE CATALOG <catalog-name>

Las tablas de características del catálogo de Unity deben almacenarse en un esquema. Para crear un nuevo esquema en el catálogo, se necesita tener el privilegio CREATE SCHEMA en el catálogo.

CREATE SCHEMA IF NOT EXISTS <schema-name>

Creación de una tabla de características en el catálogo de Unity

Nota:

Puede usar una tabla Delta existente en Unity Catalog que incluya una restricción de clave principal como tabla de características. Si la tabla no tiene definida una clave principal, debe actualizar la tabla mediante instrucciones DDL ALTER TABLE para agregar la restricción. Consulte Uso de una tabla Delta existente en el catálogo de Unity como tabla de características.

Sin embargo, agregar una clave principal a una tabla de streaming o una vista materializada publicada en Unity Catalog mediante una canalización de Delta Live Tables requiere modificar el esquema de la tabla de streaming o la definición de vista materializada para incluir la clave principal y, a continuación, actualizar la tabla de streaming o la vista materializada. Consulte Uso de una tabla de streaming o una vista materializada creada por una canalización de Delta Live Tables como tabla de características.

Las tablas de características de Unity Catalog son tablas delta. Las tablas de características deben tener una clave principal. Se accede a las tablas de características, al igual que otros recursos de datos de Unity Catalog, mediante un espacio de nombres de tres niveles: <catalog-name>.<schema-name>.<table-name>.

Puede usar Databricks SQL, Python FeatureEngineeringClient o una canalización Delta Live Tables para crear tablas de características en Unity Catalog.

Databricks SQL

Puede usar cualquier tabla de Delta con una restricción de clave principal como tabla de características. En el siguiente código se muestra cómo crear una tabla:

CREATE TABLE ml.recommender_system.customer_features (
  customer_id int NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id)
);

Para crear una tabla de características de serie temporal, agregue una columna de hora como columna de clave principal y especifique la palabra clave TIMESERIES. La palabra clave TIMESERIES requiere Databricks Runtime 13.3 LTS o superior.

CREATE TABLE ml.recommender_system.customer_features (
  customer_id int NOT NULL,
  ts timestamp NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id, ts TIMESERIES)
);

Una vez creada la tabla, puede escribir datos en ella como en otras tablas de Delta y se puede usar como tabla de características.

Python

Para obtener más información sobre los comandos y parámetros usados en los ejemplos siguientes, consulte la Referencia de la API de Python de ingeniería de características .

Escriba las funciones de Python para procesar las características. La salida de cada función debe ser un objeto DataFrame de Apache Spark con una clave principal única. La clave principal puede constar de una o varias columnas.
Crea una tabla de características a través de la creación de instancias de un FeatureEngineeringClient y mediante create_table.
Rellene la tabla de características con write_table.

from databricks.feature_engineering import FeatureEngineeringClient

fe = FeatureEngineeringClient()

# Prepare feature DataFrame
def compute_customer_features(data):
  ''' Feature computation code returns a DataFrame with 'customer_id' as primary key'''
  pass

customer_features_df = compute_customer_features(df)

# Create feature table with `customer_id` as the primary key.
# Take schema from DataFrame output by compute_customer_features
customer_feature_table = fe.create_table(
  name='ml.recommender_system.customer_features',
  primary_keys='customer_id',
  schema=customer_features_df.schema,
  description='Customer features'
)

# An alternative is to use `create_table` and specify the `df` argument.
# This code automatically saves the features to the underlying Delta table.

# customer_feature_table = fe.create_table(
#  ...
#  df=customer_features_df,
#  ...
# )

# To use a composite primary key, pass all primary key columns in the create_table call

# customer_feature_table = fe.create_table(
#   ...
#   primary_keys=['customer_id', 'date'],
#   ...
# )

# To create a time series table, set the timeseries_columns argument

# customer_feature_table = fe.create_table(
#   ...
#   primary_keys=['customer_id', 'date'],
#   timeseries_columns='date',
#   ...
# )

Creación de una tabla de características en Unity Catalog con la canalización Delta Live Tables

Nota:

La compatibilidad con Delta Live Tables para las restricciones de tabla está en versión preliminar pública. Los ejemplos de código siguientes deben ejecutarse mediante el canal de versión preliminar de Delta Live Tables.

Cualquier tabla publicada desde una canalización de Delta Live Tables que incluya una restricción de clave principal se puede usar como tabla de características. Para crear una tabla en una canalización de Delta Live Tables con una clave principal, puede usar Databricks SQL o la interfaz de programación de Python de Delta Live Tables.

Para crear una tabla en una canalización de Delta Live Tables con una clave principal, use la siguiente sintaxis :

Databricks SQL

CREATE LIVE TABLE customer_features (
  customer_id int NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id)
) AS SELECT * FROM ...;

Python

import dlt

@dlt.table(
  schema="""
          customer_id int NOT NULL,
          feat1 long,
          feat2 varchar(100),
          CONSTRAINT customer_features_pk PRIMARY KEY (customer_id)
    """)
def customer_features():
  return ...

Para crear una tabla de características de serie temporal, agregue una columna de hora como columna de clave principal y especifique la palabra clave TIMESERIES.

Databricks SQL

CREATE LIVE TABLE customer_features (
  customer_id int NOT NULL,
  ts timestamp NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (customer_id, ts TIMESERIES)
) AS SELECT * FROM ...;

Python

import dlt

@dlt.table(
  schema="""
    customer_id int NOT NULL,
    ts timestamp NOT NULL,
    feat1 long,
    feat2 varchar(100),
    CONSTRAINT customer_features_pk PRIMARY KEY (customer_id, ts TIMESERIES)
    """)
def customer_features():
  return ...

Una vez creada la tabla, puede escribir datos en ella como en otros conjuntos de datos de Delta Live Tables y se puede usar como tabla de características.

Uso de una tabla Delta existente en el catálogo de Unity como tabla de características

Cualquier tabla Delta del catálogo de Unity con una clave principal puede ser una tabla de características del catálogo de Unity y puede usar la API y la interfaz de usuario de características con la tabla.

Nota:

Solo el propietario de la tabla puede declarar restricciones de clave principal. El nombre del propietario se muestra en la página de detalles de la tabla del Explorador de catálogos.
Compruebe que el tipo de datos de la tabla Delta sea compatible con la ingeniería de características en el catálogo de Unity. Consulte Tipos de datos admitidos.
La palabra clave TIMESERIES requiere Databricks Runtime 13.3 LTS o superior.

Si una tabla Delta existente no tiene una restricción de clave principal, puede crear una de las siguientes opciones:

Establecer las columnas de clave principal en NOT NULL. Para cada columna de clave principal, ejecute:
```
ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL
```
Modificar la tabla para agregar la restricción de clave principal:
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1, pk_col2, ...)
```
pk_name es el nombre de la restricción de clave principal. Por convención, se puede usar el nombre de tabla (sin esquema y catálogo) con un sufijo _pk. Por ejemplo, una tabla con el nombre "ml.recommender_system.customer_features" tendría customer_features_pk como nombre de su restricción de clave principal.

Para que la tabla sea una tabla de características de serie temporal, especifique la palabra clave TIMESERIES en una de las columnas de clave principal, como se indica a continuación:
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1 TIMESERIES, pk_col2, ...)
```
Después de agregar la restricción de clave principal en la tabla, aparecerá en la interfaz de usuario de características y podrá usarla como tabla de características.

Uso de una tabla de streaming o una vista materializada creada por una canalización de Delta Live Tables como una tabla de características

Cualquier tabla de streaming o vista materializada del catálogo de Unity con una clave principal puede ser una tabla de características del catálogo de Unity y es posible usar la API y la interfaz de usuario de características con la tabla.

Nota:

La compatibilidad con Delta Live Tables para las restricciones de tabla está en versión preliminar pública. Los ejemplos de código siguientes deben ejecutarse mediante el canal de versión preliminar de Delta Live Tables.
Solo el propietario de la tabla puede declarar restricciones de clave principal. El nombre del propietario se muestra en la página de detalles de la tabla del Explorador de catálogos.
Compruebe que la ingeniería de características en Unity Catalog admite el tipo de datos de la tabla Delta. Consulte Tipos de datos admitidos.

Para establecer claves principales para una tabla de streaming existente o una vista materializada, actualice el esquema de la tabla de streaming o la vista materializada en el cuaderno que administre el objeto. A continuación, actualice la tabla para actualizar el objeto de Unity Catalog.

A continuación se muestra la sintaxis para agregar una clave principal a una vista materializada:

Databricks SQL

CREATE OR REFRESH MATERIALIZED VIEW existing_live_table(
  id int NOT NULL PRIMARY KEY,
  ...
) AS SELECT ...

Python

import dlt

@dlt.table(
  schema="""
    id int NOT NULL PRIMARY KEY,
    ...
    """
)
def existing_live_table():
  return ...

Control de acceso a tablas de características en el catálogo de Unity

El control de acceso a tablas de características en el catálogo de Unity se administra mediante el catálogo de Unity. Consulte Privilegios del catálogo de Unity.

Actualización de tablas de características en el catálogo de Unity

Para actualizar una tabla de características en el catálogo de Unity, agregue características nuevas o modifique filas específicas en función de la clave principal.

No se deberían actualizar los metadatos siguientes de la tabla de características:

Clave principal.
Clave de partición.
Nombre o tipo de datos de una característica existente.

Modificarlas hará que las canalizaciones de bajada que usen características para entrenar y servir modelos se interrumpan.

Adición de características nuevas a una tabla de características existente en el catálogo de Unity

Puede agregar características nuevas a una tabla de características existente de alguna de estas dos formas:

Actualice la función de cálculo de características existente y ejecute write_table con el objeto DataFrame devuelto. Esto actualiza el esquema de la tabla de características y combina los valores de las características nuevas en función de la clave principal.
Cree una función de cálculo de características para calcular los valores de las características nuevas. El objeto DataFrame que esta nueva función de cálculo devuelve debe contener las claves principales y las de partición (si se han definido) de las tablas de características. Ejecute write_table con el objeto DataFrame para escribir las características nuevas en la tabla de características existente con la misma clave principal.

Actualización exclusiva de filas específicas de una tabla de características

Use mode = "merge" en write_table. Las filas cuya clave principal no existe en el objeto DataFrame enviado en la llamada a write_table permanecen sin cambios.

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
fe.write_table(
  name='ml.recommender_system.customer_features',
  df = customer_features_df,
  mode = 'merge'
)

Programación de un trabajo para actualizar una tabla de características

Para asegurarse de que las características de las tablas correspondientes siempre tengan los valores más recientes, Databricks le recomienda crear un trabajo que ejecute un cuaderno para actualizar la tabla de características de forma periódica, por ejemplo, cada día. Si ya ha creado un trabajo no programado, puede convertirlo en trabajo programado para asegurarse de que los valores de las característica estén siempre actualizados.

El código para actualizar una tabla de características usa mode='merge', como se muestra en el ejemplo siguiente.

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()

customer_features_df = compute_customer_features(data)

fe.write_table(
  df=customer_features_df,
  name='ml.recommender_system.customer_features',
  mode='merge'
)

Almacenamiento de valores anteriores de características diarias

Defina una tabla de características con una clave principal compuesta. Incluya la fecha en la clave principal. Por ejemplo, en una tabla de características customer_features, puede usar una clave principal compuesta (date, customer_id) y una clave de partición date para realizar lecturas eficaces.

Databricks SQL

CREATE TABLE ml.recommender_system.customer_features (
  customer_id int NOT NULL,
  `date` date NOT NULL,
  feat1 long,
  feat2 varchar(100),
  CONSTRAINT customer_features_pk PRIMARY KEY (`date`, customer_id)
)
PARTITIONED BY (`date`)
COMMENT "Customer features";

Python

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
fe.create_table(
  name='ml.recommender_system.customer_features',
  primary_keys=['date', 'customer_id'],
  partition_columns=['date'],
  schema=customer_features_df.schema,
  description='Customer features'
)

A continuación, puede crear código para leer desde la tabla de características con el filtrado de date hasta el período de tiempo de su interés.

También puede crear una tabla de características de serie temporal que permite búsquedas puntuales al usar create_training_set o score_batch. Consulte Creación de una tabla de características en Unity Catalog.

Para mantener la tabla de características actualizada, configure un trabajo programado periódicamente para escribir características o para hacer streaming de los valores de las características nuevas a la tabla de características.

Creación de una canalización de cálculo de características de streaming para actualizar características

Para crear una canalización de cálculo de características de streaming, pase como argumento un objeto DataFrame en streaming a write_table. Este método devuelve un objeto StreamingQuery.

def compute_additional_customer_features(data):
  ''' Returns Streaming DataFrame
  '''
  pass

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()

customer_transactions = spark.readStream.load("dbfs:/events/customer_transactions")
stream_df = compute_additional_customer_features(customer_transactions)

fe.write_table(
  df=stream_df,
  name='ml.recommender_system.customer_features',
  mode='merge'
)

Lectura de tablas de características en el catálogo de Unity

Use read_table para leer los valores de las características.

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
customer_features_df = fe.read_table(
  name='ml.recommender_system.customer_features',
)

Búsqueda y exploración de tablas de características en el catálogo de Unity

Use la interfaz de usuario Características para buscar o examinar tablas de características en el catálogo de Unity.

Haga clic en Características en la barra lateral para mostrar la interfaz de usuario de Características.
Seleccione un catálogo con el selector de catálogos para ver todas las tablas de características disponibles en ese catálogo. En el cuadro de búsqueda, escriba todo o parte del nombre de una tabla de características, una característica o un comentario. También puede escribir todo o parte de la clave o el valor de una etiqueta. En la búsqueda, no se distingue entre mayúsculas y minúsculas.

Obtención de metadatos de tablas de características en el catálogo de Unity

Use get_table para obtener metadatos de tabla de características.

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
ft = fe.get_table(name="ml.recommender_system.user_feature_table")
print(ft.features)

Uso de etiquetas con tablas de características y características en el catálogo de Unity

Es posible usar etiquetas, que son pares clave-valor simples, para clasificar y administrar las tablas de características y las características.

En el caso de las tablas de características, puede crear, editar y eliminar etiquetas mediante el Explorador de catálogos, las instrucciones SQL de un cuaderno o el editor de consultas SQL, o la API de Python de ingeniería de características.

En el caso de las características, puede crear, editar y eliminar etiquetas mediante el Explorador de catálogos o las instrucciones SQL de un cuaderno o el editor de consultas SQL.

Vea Aplicar etiquetas a objetos protegibles de Unity Catalog y la API de Python.

En el ejemplo siguiente, se muestra cómo usar la API de Python de ingeniería de características para crear, actualizar y eliminar etiquetas de tabla de características.

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()

# Create feature table with tags
customer_feature_table = fe.create_table(
  # ...
  tags={"tag_key_1": "tag_value_1", "tag_key_2": "tag_value_2", ...},
  # ...
)

# Upsert a tag
fe.set_feature_table_tag(name="customer_feature_table", key="tag_key_1", value="new_key_value")

# Delete a tag
fe.delete_feature_table_tag(name="customer_feature_table", key="tag_key_2")

Eliminar tablas de características en el catálogo de Unity

Es posible eliminar tablas de características del catálogo de Unity mediante la eliminación directa de la tabla Delta del catálogo de Unity a través del Explorador de catálogos o bien de la API de Python de ingeniería de características.

Nota:

La eliminación de una tabla de características puede producir errores inesperados en los productores y los consumidores (modelos, puntos de conexión y trabajos programados). Debe eliminar los almacenes en línea publicados con el proveedor de nube.
Al eliminar una tabla de características en el catálogo de Unity, también se eliminará la tabla Delta subyacente.
No se admite drop_table en Databricks Runtime 13.1 ML o versiones anteriores. Use el comando SQL para eliminar la tabla.

Puede usar Databricks SQL o FeatureEngineeringClient.drop_table para eliminar una tabla de características en el Catálogo de Unity:

Databricks SQL

DROP TABLE ml.recommender_system.customer_features;

Python

from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
fe.drop_table(
  name='ml.recommender_system.customer_features'
)

Compartir a través de

Ingeniería de características en Unity Catalog

Requisitos

Instalación de la ingeniería de características en el cliente Python del catálogo de Unity

Creación de un catálogo y un esquema para tablas de características en el catálogo de Unity

Creación de una tabla de características en el catálogo de Unity

Databricks SQL

Python

Creación de una tabla de características en Unity Catalog con la canalización Delta Live Tables

Databricks SQL

Python

Databricks SQL

Python

Uso de una tabla Delta existente en el catálogo de Unity como tabla de características

Uso de una tabla de streaming o una vista materializada creada por una canalización de Delta Live Tables como una tabla de características

Databricks SQL

Python

Control de acceso a tablas de características en el catálogo de Unity

Actualización de tablas de características en el catálogo de Unity

Adición de características nuevas a una tabla de características existente en el catálogo de Unity

Actualización exclusiva de filas específicas de una tabla de características

Programación de un trabajo para actualizar una tabla de características

Almacenamiento de valores anteriores de características diarias

Databricks SQL

Python

Creación de una canalización de cálculo de características de streaming para actualizar características

Lectura de tablas de características en el catálogo de Unity

Búsqueda y exploración de tablas de características en el catálogo de Unity

Obtención de metadatos de tablas de características en el catálogo de Unity

Uso de etiquetas con tablas de características y características en el catálogo de Unity

Eliminar tablas de características en el catálogo de Unity

Databricks SQL

Python

Comentarios

Comentarios

Recursos adicionales