Recurso engenharia no Unity Catalog

Esta página descreve como criar e trabalhar com tabelas de recursos no Unity Catalog.

Esta página se aplica apenas ao workspace habilitado para o Unity Catalog. Se o seu espaço de trabalho não estiver habilitado para o Unity Catalog, consulte Trabalhar com recursos no Workspace Feature Store.

Requisitos

O recurso engenharia em Unity Catalog requer Databricks Runtime 13.2 ou superior. Além disso, o metastore do Unity Catalog deve ter o Privilege Model Version 1.0.

Instale o recurso Engineering no cliente Unity Catalog Python

recurso Engineering no Unity Catalog fornece um cliente Python FeatureEngineeringClient. A classe está disponível no PyPI com o pacote databricks-feature-engineering e está pré-instalada no Databricks Runtime 13.2 ML e acima. Se estiver usando um Databricks Runtime não ML, você precisará instalar o cliente manualmente. Utilize a matriz de compatibilidade para encontrar a versão correta para a sua versão do Databricks Runtime.

%pip install databricks-feature-engineering

dbutils.library.restartPython()

Crie um catálogo e um esquema para tabelas de recursos no Unity Catalog

Você deve criar um novo catálogo ou utilizar um catálogo existente para tabelas de recursos.

Para criar um novo catálogo, você deve ter o privilégio CREATE CATALOG no metastore.

CREATE CATALOG IF NOT EXISTS <catalog-name>

Para usar um catálogo existente, você deve ter o privilégio USE CATALOG no catálogo.

USE CATALOG <catalog-name>

tabelas de recursos no Unity Catalog devem ser armazenadas em um esquema. Para criar um novo esquema no catálogo, você deve ter o privilégio CREATE SCHEMA no catálogo.

CREATE SCHEMA IF NOT EXISTS <schema-name>

Crie uma tabela de recursos no Unity Catalog

Observação

O senhor pode usar uma tabela Delta existente no Unity Catalog como uma tabela de recurso. Consulte Usar uma tabela Delta existente no Unity Catalog como uma tabela de recurso.

O senhor também pode usar uma tabela existente do Delta Live Table em Unity Catalog como uma tabela de recurso. Consulte Usar uma tabela de transmissão existente ou materializada view criada por um Delta Live Tables pipeline como uma tabela de recurso.

As tabelas de recurso no Unity Catalog são tabelas Delta ou Delta Live Tables gerenciadas pelo Unity Catalog. As tabelas de recurso devem ter um primário key. O nome de uma tabela de recurso no Unity Catalog tem uma estrutura de três níveis, <catalog-name>.<schema-name>.<table-name>.

O senhor pode usar o site Databricks SQL ou o Python FeatureEngineeringClient para criar tabelas recurso Delta no Unity Catalog. O senhor pode usar o pipeline Delta Live Tables para criar recurso Delta Live Tables no Unity Catalog.

Você pode usar qualquer tabela Delta com uma restrição key primária como tabela de recursos. O código a seguir mostra como criar uma tabela com uma key primária:

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 criar uma tabela de recursos de série temporal, adicione uma coluna de tempo como uma coluna key primária e especifique a palavra-chave TIMESERIES . A palavra-chave TIMESERIES requer Databricks Runtime 13.3 LTS ou acima.

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

Depois que a tabela for criada, você poderá gravar dados nela da mesma forma que grava outras tabelas Delta e ela poderá ser usada como uma tabela de recursos.

Para obter detalhes sobre o comando e os parâmetros usados nos exemplos a seguir, consulte a referência da API Python do recurso engenharia.

  1. Escreva as funções do Python para compute os recursos. A saída de cada função deve ser um Apache Spark DataFrame com uma key primária exclusiva. A key primária pode consistir em uma ou mais colunas.

  2. Crie uma tabela de recursos instanciando um FeatureEngineeringClient e usando create_table.

  3. Preencha a tabela de recursos usando 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',
#   ...
# )

Observação

As restrições de tabela em Delta Live Tables estão em Public Preview. Os exemplos de código a seguir devem ser executados usando o canal de visualização Delta Live Tables.

O senhor pode usar qualquer tabela Delta Live com uma restrição primária key como uma tabela de recurso. O código a seguir mostra como criar uma tabela Delta Live com um primário key:

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

Para criar uma tabela de recurso de série temporal, adicione uma coluna de tempo como uma coluna primária key e especifique a palavra-chave TIMESERIES.

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

Depois que a tabela é criada, o senhor pode gravar dados nela da mesma forma que em outras Delta Live Tables, e ela pode ser usada como uma tabela de recurso.

As restrições de tabela para Delta Live Tables são suportadas apenas em SQL. Para definir a chave primária para Delta Live Tables que foram declaradas em Python, consulte Usar uma tabela de transmissão existente ou materializada view criada por um Delta Live Tables pipeline como uma tabela de recurso.

Use uma tabela Delta existente no Unity Catalog como uma tabela de recursos

Qualquer tabela Delta em Unity Catalog com um key primário pode ser uma tabela de recurso em Unity Catalog, e o senhor pode usar o recurso UI e API com a tabela.

Observação

  • Somente o proprietário da tabela pode declarar restrições key primária. O nome do proprietário é exibido na página de detalhes da tabela do Catalog Explorer.

  • Verifique se o tipo de dados na tabela Delta é compatível com o recurso engenharia em Unity Catalog. Consulte Tipos de dados suportados.

  • A palavra-chave TIMESERIES requer Databricks Runtime 13.3 LTS ou acima.

Se uma tabela Delta existente não tiver uma restrição key primária, o senhor poderá criar uma da seguinte forma:

  1. Defina colunas key primária como NOT NULL. Para cada coluna key primária, execução:

    ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL

  2. Altere a tabela para adicionar a restrição key primária:

    ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1, pk_col2, ...)

    pk_name é o nome da restrição key primária. Por convenção, você pode usar o nome da tabela (sem esquema e catálogo) com um sufixo _pk . Por exemplo, uma tabela com o nome "ml.recommender_system.customer_features" teria customer_features_pk como o nome de sua restrição key primária.

    Para tornar a tabela uma tabela de recursos de série temporal, especifique a palavra key TIMESERIES em uma das colunas key primária, como segue:

    ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1 TIMESERIES, pk_col2, ...)

    Depois de adicionar a restrição Primary key à tabela, ela aparecerá na UI de recurso e o senhor poderá usá-la como uma tabela de recurso.

Use uma tabela de transmissão existente ou materializada view criada por um Delta Live Tables pipeline como uma tabela de recurso

Qualquer tabela de transmissão ou materializada view em Unity Catalog com um key primário pode ser uma tabela de recurso em Unity Catalog, e o senhor pode usar a UI de recurso e API com a tabela.

Observação

  • As restrições de tabela em Delta Live Tables estão em Public Preview. Os exemplos de código a seguir devem ser executados usando o canal de visualização Delta Live Tables.

  • Somente o proprietário da tabela pode declarar restrições key primária. O nome do proprietário é exibido na página de detalhes da tabela do Catalog Explorer.

  • Verifique se o tipo de dados na tabela Delta é compatível com o recurso engenharia em Unity Catalog. Consulte Tipos de dados suportados.

Adicione o key primário a uma tabela de transmissão ou view materializado que foi criado usando o SQL

Para definir a chave primária de uma tabela de transmissão existente ou materializada view que foi criada usando SQL, atualize o esquema da tabela de transmissão ou materializada view no Notebook que gerencia a tabela. Em seguida, refresh a tabela para a restrição a ser aplicada em Unity Catalog.

O código deve ser semelhante ao seguinte:

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

Adicione o key primário a uma tabela de transmissão ou view materializado que foi criado usando o Python

Para criar uma chave primária para uma tabela de transmissão existente ou materializada view que foi criada por um Delta Live Tables pipeline, o senhor deve usar SQL, mesmo que a tabela de transmissão ou materializada view tenha sido criada usando Python. Crie uma nova SQL Notebook para definir uma nova tabela de transmissão ou view materializada que leia a partir da existente. Em seguida, execute o Notebook como um passo a passo do Delta Live Tables pipeline existente ou em um novo pipeline.

O novo SQL Notebook deve incluir um código semelhante ao seguinte:

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

Controle o acesso às tabelas de recursos no Unity Catalog

O controle de acesso para tabelas de recursos no Catálogo Unity é gerenciado pelo Catálogo Unity. Consulte PrivilégiosUnity Catalog .

Atualize uma tabela de recursos no Unity Catalog

Você pode atualizar uma tabela de recursos no Unity Catalog adicionando novos recursos ou modificando linhas específicas com base na key primária.

Os seguintes metadados da tabela de recursos não devem ser atualizados:

  • key primária.

  • key de partição.

  • Nome ou tipo de dados de um recurso existente.

Alterá-los fará com que os pipelines downstream que usam recursos para modelos de treinamento e veiculação sejam interrompidos.

Adicionar novos recursos a uma tabela de recursos existente no Unity Catalog

Você pode adicionar novos recursos a uma tabela de recursos existente de duas maneiras:

  • Atualize a função de computação de recurso existente e a execução write_table com o DataFrame retornado. Isso atualiza o esquema da tabela de recursos e merge novos valores de recursos com base na key primária.

  • Crie uma nova função de cálculo de recursos para calcular os novos valores de recursos. O DataFrame retornado por esta nova função de computação deve conter a key primária e key de partição das tabelas de recursos (se definidas). execução write_table com o DataFrame para gravar os novos recursos na tabela de recursos existente, usando a mesma key primária.

Atualize apenas linhas específicas em uma tabela de recursos

Use mode = "merge" em write_table. As linhas cuja key primária não existe no DataFrame enviado na chamada write_table permanecem inalteradas.

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

programar um Job para atualizar uma tabela de características

Para garantir que os recursos nas tabelas de recursos sempre tenham os valores mais recentes, a Databricks recomenda que você crie um Job que execute um Notebook para atualizar sua tabela de recursos regularmente, como todos os dias. Se você já possui um Job não agendado criado, você pode convertê-lo para um Jobagendado para garantir que os valores do recurso estejam sempre atualizados.

O código para atualizar uma tabela de recursos usa mode='merge', conforme mostrado no exemplo a seguir.

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

Armazenar valores anteriores de recursos diários

Defina uma tabela de recursos com uma key primária composta. Inclua a data na key primária. Por exemplo, para uma tabela de recursos customer_features, você pode usar uma key primária composta (date, customer_id) e key de partição date para leituras eficientes.

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

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

Você pode então criar um código para ler da tabela de recursos filtrando date para o período de interesse.

Você também pode criar uma tabela de recursos de série temporal que permite pesquisas pontuais quando você usa create_training_set ou score_batch. Consulte Criar uma tabela de recursos no Unity Catalog.

Para manter a tabela de recursos atualizada, configure um Job agendado regularmente para gravar recursos ou transmita novos valores de recursos para a tabela de recursos.

Crie um pipeline de computação de recursos transmitidos para atualizar os recursos

Para criar um pipeline de computação de recurso de transmissão, passe um DataFrame de transmissão como um argumento para write_table. Este método retorna um 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'
)

Leia a partir de uma tabela de recursos no Unity Catalog

Use read_table para ler os valores do recurso.

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

Pesquise e navegue nas tabelas de recursos no Unity Catalog

Use a interface do usuário de recursos para pesquisar ou navegar nas tabelas de recursos no Unity Catalog.

  1. Clique Ícone Feature Store recurso na barra lateral para exibir a UI do recurso.

  2. Selecione catálogo com o seletor de catálogo para view todas as tabelas de recursos disponíveis nesse catálogo. Na caixa de pesquisa, insira todo ou parte do nome de uma tabela de recursos, um recurso ou um comentário. Você também pode inserir toda ou parte da key ou valor de uma tag. O texto de pesquisa não diferencia maiúsculas de minúsculas.

    Exemplo de pesquisa de recursos

Obtenha metadados de tabelas de recursos no Unity Catalog

Use get_table para obter os metadados da tabela de recursos.

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

Use tags com tabelas de recurso e recurso em Unity Catalog

O senhor pode usar tags, que são simples par chave-valor, para categorizar e gerenciar suas tabelas de recursos e recursos.

Para tabelas de recursos, o senhor pode criar, editar e excluir tags usando a UI do Catalog Explorer, Databricks SQLou o recurso engenharia Python API .

Para recurso, o senhor pode criar, editar e excluir tags usando a interface do usuário do Catalog Explorer ou o Databricks SQL.

O exemplo a seguir mostra como usar o recurso engenharia Python API para criar, atualizar e excluir a tabela de recursos tags.

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

Excluir uma tabela de recursos no Unity Catalog

O senhor pode excluir uma tabela de recurso em Unity Catalog excluindo diretamente a tabela Delta em Unity Catalog usando o Catalog Explorer ou usando o recurso engenharia Python API .

Observação

  • A exclusão de uma tabela de recursos pode levar a falhas inesperadas em produtores upstream e consumidores downstream (models, endpoint e Schedule Job). Você deve excluir as lojas online publicadas com seu provedor de cloud .

  • Quando você exclui uma tabela de recursos no Unity Catalog, a tabela Delta subjacente também é descartada.

  • drop_table não tem suporte no Databricks Runtime 13.1 ML ou abaixo. Use o comando SQL para excluir a tabela.

Você pode usar Databricks SQL ou FeatureEngineeringClient.drop_table para excluir uma tabela de recursos no Unity Catalog:

DROP TABLE ml.recommender_system.customer_features;

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