Engenharia de recursos no catálogo Unity

Artigo
04/23/2024

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

Esta página se aplica somente a espaços de trabalho habilitados para o Catálogo Unity. Se o seu espaço de trabalho não estiver habilitado para o Catálogo Unity, consulte Trabalhar com recursos no Repositório de Recursos do Espaço de Trabalho.

Requisitos

A engenharia de recursos no Unity Catalog requer o Databricks Runtime 13.2 ou superior. Além disso, o metastore do Unity Catalog deve ter o Privilege Model Versão 1.0.

Instalar o Feature Engineering no cliente Python do Unity Catalog

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

%pip install databricks-feature-engineering

dbutils.library.restartPython()

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

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

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

CREATE CATALOG IF NOT EXISTS <catalog-name>

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

USE CATALOG <catalog-name>

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

CREATE SCHEMA IF NOT EXISTS <schema-name>

Criar uma tabela de recursos no Unity Catalog

Nota

Você pode usar uma tabela Delta existente no Unity Catalog como uma tabela de recursos. Consulte Usar uma tabela Delta existente no Unity Catalog como uma tabela de recursos.

Você também pode usar uma tabela Delta Live existente no Unity Catalog como uma tabela de recursos. Consulte Usar uma tabela de streaming existente ou uma exibição materializada criada por um pipeline Delta Live Tables como uma tabela de recursos.

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

Você pode usar o Databricks, SQL ou Python FeatureEngineeringClient para criar tabelas Delta de recursos no Unity Catalog. Você pode usar pipelines Delta Live Tables para criar o recurso Delta Live Tables no Unity Catalog.

Databricks sql |

Você pode usar qualquer tabela Delta com uma restrição de chave primária como uma tabela de recursos. O código a seguir mostra como criar uma tabela com uma chave 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 de chave primária e especifique a palavra-chave TIMESERIES. A palavra-chave TIMESERIES requer Databricks Runtime 13.3 LTS ou 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)
);

Depois que a tabela é criada, você pode gravar dados nela da mesma forma que escreve outras tabelas Delta e ela pode ser usada como uma tabela de recursos.

Python

Para obter detalhes sobre os comandos e parâmetros usados nos exemplos a seguir, consulte a referência da API Python do Feature Engineering.

Escreva as funções Python para calcular os recursos. A saída de cada função deve ser um Apache Spark DataFrame com uma chave primária exclusiva. A chave primária pode consistir em uma ou mais colunas.
Crie uma tabela de recursos instanciando a FeatureEngineeringClient e usando create_tableo .
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',
#   ...
# )

Mesas ao vivo Delta

Nota

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

Você pode usar qualquer Tabela Delta Live com uma Restrição de Chave Primária como uma tabela de recursos. O código a seguir mostra como criar uma tabela Delta Live com uma chave primária:

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 recursos de série temporal, adicione uma coluna de tempo como uma coluna de chave primária 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, você pode gravar dados nela da mesma forma que escreve outras Delta Live Tables, e ela pode ser usada como uma tabela de recursos.

As restrições de tabela para Delta Live Tables só são suportadas em SQL. Para definir chaves primárias para Delta Live Tables que foram declaradas em Python, consulte Usar uma tabela de streaming existente ou uma exibição materializada criada por um pipeline Delta Live Tables como uma tabela de recursos.

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

Qualquer tabela Delta no Unity Catalog com uma chave primária pode ser uma tabela de recursos no Unity Catalog, e você pode usar a interface do usuário de recursos e a API com a tabela.

Nota

Apenas o proprietário da tabela pode declarar Restrições de Chave 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 é suportado pelo Feature Engineering no Unity Catalog. Veja Tipos de dados suportados.
A palavra-chave TIMESERIES requer Databricks Runtime 13.3 LTS ou superior.

Se uma tabela Delta existente não tiver uma Restrição de Chave Primária, você poderá criar uma da seguinte maneira:

Defina colunas de chave primária como NOT NULL. Para cada coluna de chave primária, execute:
```
ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL
```
Altere a tabela para adicionar a restrição de chave primária:
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1, pk_col2, ...)
```
pk_name é o nome da Restrição de Chave Primária. Por convenção, você pode usar o nome da tabela (sem esquema e catálogo) com um _pk sufixo. Por exemplo, uma tabela com o nome "ml.recommender_system.customer_features" teria customer_features_pk como nome sua Restrição de Chave Primária.

Para tornar a tabela uma tabela de recursos de série temporal, especifique a palavra-chave TIMESERIES em uma das colunas de chave primária, da seguinte maneira:
```
ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1 TIMESERIES, pk_col2, ...)
```
Depois de adicionar a Restrição de Chave Primária na tabela, a tabela aparece na interface do usuário Recursos e você pode usá-la como uma tabela de recursos.

Usar uma tabela de streaming existente ou uma exibição materializada criada por um pipeline Delta Live Tables como uma tabela de recursos

Qualquer tabela de streaming ou exibição materializada no Unity Catalog com uma chave primária pode ser uma tabela de recursos no Unity Catalog, e você pode usar a interface do usuário de recursos e a API com a tabela.

Nota

As restrições de tabela no Delta Live Tables estão em Visualização Pública. Os exemplos de código a seguir devem ser executados usando o canal de visualização Delta Live Tables.
Apenas o proprietário da tabela pode declarar Restrições de Chave 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 é suportado pelo Feature Engineering no Unity Catalog. Veja Tipos de dados suportados.

Adicionar chave primária a uma tabela de streaming ou exibição materializada que foi criada usando SQL

Para definir chaves primárias para uma tabela de streaming existente ou uma exibição materializada que estava sendo criada usando SQL, atualize o esquema da tabela de streaming ou a exibição materializada no bloco de anotações que gerencia a tabela. Em seguida, atualize a tabela para que a restrição seja aplicada no 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 ...

Adicionar chave primária a uma tabela de streaming ou exibição materializada que foi criada usando Python

Para criar chaves primárias para uma tabela de streaming existente ou uma exibição materializada que foi criada por um pipeline Delta Live Tables, você deve usar SQL, mesmo que a tabela de streaming ou a exibição materializada tenha sido criada usando Python. Crie um novo bloco de anotações SQL para definir uma nova tabela de streaming ou uma exibição materializada que leia a partir da existente. Em seguida, execute o bloco de anotações como uma etapa do pipeline Delta Live Tables existente ou em um novo pipeline.

O novo bloco de anotações SQL deve incluir 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

Controlar o acesso a tabelas de recursos no Catálogo Unity

O controle de acesso para tabelas de recursos no Unity Catalog é gerenciado pelo Unity Catalog. Consulte Privilégios do catálogo Unity.

Atualizar uma tabela de recursos no Catálogo Unity

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

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

Chave primária.
Chave de partição.
Nome ou tipo de dados de um recurso existente.

Alterá-los fará com que pipelines downstream que usam recursos para treinamento e modelos de serviço se rompam.

Adicionar novos recursos a uma tabela de recursos existente no Catálogo Unity

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 execute write_table com o DataFrame retornado. Isso atualiza o esquema da tabela de recursos e mescla novos valores de recursos com base na chave primária.
Crie uma nova função de computação de recurso para calcular os novos valores de recurso. O DataFrame retornado por essa nova função de computação deve conter as chaves primárias e as chaves de partição das tabelas de recursos (se definidas). Execute write_table com o DataFrame para gravar os novos recursos na tabela de recursos existente, usando a mesma chave primária.

Atualizar apenas linhas específicas em uma tabela de recursos

Utilização mode = "merge" em write_table. As linhas cuja chave primária não existe no DataFrame enviado na write_table chamada 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'
)

Agendar um trabalho para atualizar uma tabela de recursos

Para garantir que os recursos nas tabelas de recursos sempre tenham os valores mais recentes, o Databricks recomenda que você crie um trabalho que execute um bloco de anotações para atualizar sua tabela de recursos regularmente, como todos os dias. Se você já tiver um trabalho não agendado criado, poderá convertê-lo em um trabalho agendado 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'
)

Armazene valores anteriores de recursos diários

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

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

Em seguida, você pode criar código para ler a partir da filtragem date da tabela de recursos para o período de tempo de interesse.

Você também pode criar uma tabela de recursos de série temporal que permite pesquisas point-in-time quando você usa create_training_set ou score_batch. Consulte Criar uma tabela de recursos no Catálogo Unity.

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

Criar um pipeline de computação de recurso de streaming para atualizar recursos

Para criar um pipeline de computação de recurso de streaming, passe um streaming DataFrame como argumento para write_table. Esse método retorna um StreamingQuery objeto.

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

Ler a partir de uma tabela de recursos no Catálogo Unity

Use read_table para ler valores de recurso.

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

Pesquisar e procurar tabelas de recursos no Catálogo Unity

Use a interface do usuário Recursos para pesquisar ou procurar tabelas de recursos no Catálogo Unity.

Clique em Recursos na barra lateral para exibir a interface do usuário Recursos.
Selecione catálogo com o seletor de catálogo para exibir todas as tabelas de recursos disponíveis nesse catálogo. Na caixa de pesquisa, introduza todo ou parte do nome de uma tabela de funcionalidades, de uma funcionalidade ou de um comentário. Você também pode inserir toda ou parte da chave ou do valor de uma tag. O texto de pesquisa não diferencia maiúsculas de minúsculas.

Obter metadados de tabelas de recursos no Unity Catalog

Use get_table para obter 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)

Usar tags com tabelas de recursos e recursos no Unity Catalog

Você pode usar tags, que são pares chave-valor simples, para categorizar e gerenciar suas tabelas e recursos de recursos.

Para tabelas de recursos, você pode criar, editar e excluir tags usando a interface do usuário do Catalog Explorer, o Databricks SQL ou a API Python do Feature Engineering.

Para recursos, você 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 a API Python do Feature Engineering para criar, atualizar e excluir tags de tabela de recursos.

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

Você pode excluir uma tabela de recursos no Catálogo Unity excluindo diretamente a tabela Delta no Catálogo Unity usando o Catalog Explorer ou usando a API Python de Engenharia de Recursos.

Nota

A exclusão de uma tabela de recursos pode levar a falhas inesperadas em produtores e consumidores a jusante (modelos, pontos finais e trabalhos agendados). Tem de eliminar as lojas online publicadas com o seu fornecedor de serviços na nuvem.
Quando você exclui uma tabela de recursos no Unity Catalog, a tabela Delta subjacente também é descartada.
drop_table não é suportado no Databricks Runtime 13.1 ML ou inferior. Use o comando SQL para excluir a tabela.

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

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

Engenharia de recursos no catálogo Unity

Requisitos

Instalar o Feature Engineering no cliente Python do Unity Catalog

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

Criar uma tabela de recursos no Unity Catalog

Databricks sql |

Python

Mesas ao vivo Delta

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

Usar uma tabela de streaming existente ou uma exibição materializada criada por um pipeline Delta Live Tables como uma tabela de recursos

Adicionar chave primária a uma tabela de streaming ou exibição materializada que foi criada usando SQL

Adicionar chave primária a uma tabela de streaming ou exibição materializada que foi criada usando Python

Controlar o acesso a tabelas de recursos no Catálogo Unity

Atualizar uma tabela de recursos no Catálogo Unity

Adicionar novos recursos a uma tabela de recursos existente no Catálogo Unity

Atualizar apenas linhas específicas em uma tabela de recursos

Agendar um trabalho para atualizar uma tabela de recursos

Armazene valores anteriores de recursos diários

Databricks sql |

Python

Criar um pipeline de computação de recurso de streaming para atualizar recursos

Ler a partir de uma tabela de recursos no Catálogo Unity

Pesquisar e procurar tabelas de recursos no Catálogo Unity

Obter metadados de tabelas de recursos no Unity Catalog

Usar tags com tabelas de recursos e recursos no Unity Catalog

Excluir uma tabela de recursos no Unity Catalog

Databricks sql |

Python

Recursos adicionais