Engenharia de Recursos no Catálogo do Unity
Esta página descreve como criar e trabalhar com tabelas de recursos no Unity Catalog.
Esta página se aplica somente a workspaces habilitados para o Unity Catalog. Se o workspace não estiver habilitado para o Unity Catalog, consulte Trabalhar com recursos no Repositório de Recursos do Workspace.
Requisitos
A Engenharia de Recursos no Catálogo do Unity requer o Databricks Runtime 13.2 ou superior. Além disso, o metastore do Unity Catalog deve ter o Modelo de Privilégios versão 1.0.
Instalar a Engenharia de Recursos no cliente Python do Catálogo do Unity
A Engenharia de Recursos no Catálogo do Unity tem 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.3 LTS ML e superior. Se você usar um Databricks Runtime não ML, deverá instalar o cliente manualmente. Use a matriz de compatibilidade para localizar a versão correta 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 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>
As tabelas de recursos no Unity Catalog deve ser armazenado 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>
Criar uma tabela de recursos no Unity Catalog
Observação
Você pode usar uma tabela Delta existente no Catálogo do Unity que inclui uma restrição de chave primária como uma tabela de recursos. Se a tabela não tiver uma chave primária definida, você deverá atualizar a tabela usando instruções DDL ALTER TABLE para adicionar a restrição. Consulte Usar uma tabela Delta existente no Unity Catalog como uma tabela de recursos.
No entanto, adicionar uma chave primária a uma tabela de streaming ou exibição materializada que foi publicada no Catálogo do Unity por um pipeline de Tabelas Dinâmicas Delta requer modificar o esquema da tabela de streaming ou a definição de exibição materializada para incluir a chave primária e atualizar a tabela de streaming ou a exibição materializada. Consulte Usar uma tabela de streaming ou uma exibição materializada criada por um pipeline de Tabelas Dinâmicas Delta como uma tabela de recursos.
As tabelas de recursos no Catálogo do Unity são tabelas Delta. Tabelas de recursos devem ter uma chave primária. As tabelas de recursos, como outros ativos de dados no Catálogo do Unity, são acessadas usando um namespace de três níveis: <catalog-name>.<schema-name>.<table-name>.
Você pode usar o SQL do Databricks, o FeatureEngineeringClient Python ou um pipeline de Tabelas Dinâmicas Delta para criar tabelas de recursos no Catálogo do Unity.
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 o 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 for criada, você poderá gravar dados nela como outras tabelas Delta e elas poderão ser usadas 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 da engenharia de recursos.
- Escrever as funções do Python para calcular os recursos. A saída de cada função deve ser um DataFrame do Apache Spark com uma chave primária exclusiva. A chave primária pode consistir em uma ou mais colunas.
- Crie uma tabela de recursos instanciando
FeatureEngineeringCliente usandocreate_table. - 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',
# ...
# )
Tabelas Dinâmicas Delta
Observação
O suporte a Tabelas Dinâmicas Delta para restrições de tabela está na Versão Prévia Pública. Os exemplos de código a seguir devem ser executados usando o canal de versão prévia do Delta Live Tables.
Qualquer tabela publicada de um pipeline de Tabelas Dinâmicas Delta que inclua uma restrição de chave primária pode ser usada como uma tabela de recursos. Use a seguinte sintaxe para criar uma tabela em um pipeline de Tabelas Dinâmicas Delta 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 for criada, você poderá gravar dados nele, como outros conjuntos de dados de Tabelas Dinâmicas Delta, e eles podem ser usados como uma tabela de recursos.
A definição de restrições de tabela tem suporte apenas pela interface SQL de Tabelas Dinâmicas Delta. Para definir chaves primárias para tabelas de streaming ou exibições materializadas que foram declaradas no Python, consulte Usar uma tabela de streaming ou uma exibição materializada criada por um pipeline de Tabelas Dinâmicas Delta como uma tabela de recursos.
Usar uma tabela Delta existente no Unity Catalog como uma tabela de recursos
Qualquer tabela Delta no Catálogo do Unity com uma chave primária pode ser uma tabela de recursos no Catálogo do Unity, e você pode usar a interface do usuário e a API de recursos com a tabela.
Observação
- Somente 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 Gerenciador de Catálogos.
- Verifique se o tipo de dados na tabela Delta é compatível com a Engenharia de Recursos no Catálogo do Unity. Confira Tipos de dados com suporte.
- A palavra-chave TIMESERIES requer o 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:
Primeiro, 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 NULLAltere 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 sufixo_pk. Por exemplo, uma tabela com o nome"ml.recommender_system.customer_features"teriacustomer_features_pkcomo o nome de 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 à tabela, a tabela será exibida na interface do usuário dos recursos e você poderá usá-la como uma tabela de recursos.
Usar uma tabela de streaming ou uma exibição materializada criada por um pipeline de Tabelas Dinâmicas Delta como uma tabela de recursos
Qualquer tabela de streaming ou exibição materializada no Catálogo do Unity com uma chave primária pode ser uma tabela de recursos no Catálogo do Unity, e você pode usar a interface do usuário de recursos e a API com a tabela.
Observação
- O suporte a Tabelas Dinâmicas Delta para restrições de tabela está na Versão Prévia Pública. Os exemplos de código a seguir devem ser executados usando o canal de versão prévia do Delta Live Tables.
- Somente 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 Gerenciador de Catálogos.
- Verifique se a Engenharia de Recursos no Catálogo do Unity dá suporte ao tipo de dados na tabela Delta. Confira Tipos de dados com suporte.
Adicionar uma 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 exibição materializada que foi criada usando a interface SQL de Tabelas Dinâmicas Delta, atualize o esquema da tabela de streaming ou o modo de exibição materializado no notebook que gerencia o objeto. Em seguida, atualize a tabela para atualizar o objeto do Catálogo do Unity.
Veja a seguir a sintaxe para adicionar uma chave primária a uma exibição materializada:
CREATE OR REFRESH MATERIALIZED VIEW existing_live_table(
id int NOT NULL PRIMARY KEY,
...
) AS SELECT ...
Adicionar a 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 de Tabelas Dinâmicas Delta, você deve usar a interface SQL de Tabelas Dinâmicas Delta, mesmo que a tabela de streaming ou o modo de exibição materializado tenha sido criado usando a interface Python das Tabelas Dinâmicas Delta. Para adicionar uma chave primária a uma tabela de streaming ou exibição materializada criada no Python, crie um novo bloco de anotações SQL para definir uma nova tabela de streaming ou uma exibição materializada que leia da tabela de streaming existente ou do modo de exibição materializado. Em seguida, execute o notebook como uma etapa do pipeline existente do Delta Live Tables ou em um novo pipeline.
Veja a seguir um exemplo da sintaxe a ser usada no novo bloco de anotações SQL para adicionar uma chave primária a uma exibição materializada:
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 Unity Catalog
O controle de acesso para tabelas de recursos no Unity Catalog é gerenciado pelo Unity Catalog. Confira Privilégios do Unity Catalog.
Atualizar uma tabela de recursos do Unity Catalog
Você pode atualizar uma tabela de recursos no Unity Catalog adicionando novos recursos ou modificando linhas específicas com base na chave primária.
Os seguintes metadados de 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 treinar e fornecer modelos 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 destas duas maneiras:
- Atualize a função de computação de recurso existente e execute
write_tablecom o DataFrame retornado. Isso atualiza o esquema da tabela de recursos e mescla os novos valores de recursos com base na chave primária. - Crie uma 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ária e de partição das tabelas de recursos (se definidas). Execute
write_tablecom o DataFrame para gravar os novos recursos na tabela de recursos existente usando a mesma chave primária.
Atualizar somente linhas específicas em uma tabela de recursos
Use mode = "merge" em write_table. As linhas cuja chave 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'
)
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 notebook para atualizar a 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 necessário 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 passados 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 de recursos customer_features, você pode usar uma chave primária composta (date, customer_id) e a chave de partição date 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 um código para ler a 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 trabalho agendado regularmente para gravar recursos ou transmitir 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, transmita um DataFrame de streaming como argumento para write_table. Esse 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'
)
Ler de uma tabela de recursos no Unity Catalog
Use read_table para ler os valores de recursos.
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 Unity Catalog
Use a interface do usuário de Recursos para pesquisar ou procurar tabelas de recursos no Unity Catalog.
Clique em
Recursos na barra lateral para exibir a interface do usuário de Recursos.Selecione o catálogo com o seletor de catálogo para exibir 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. Insira também toda ou parte da chave ou do valor de uma marca. A pesquisa de texto não diferencia maiúsculas e 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 marcas com tabelas de recursos e recursos no Catálogo do Unity
Você pode usar marcas, que são pares simples de chave-valor, para categorizar e gerenciar seus recursos e tabelas de recursos.
Para tabelas de recursos, você pode criar, editar e excluir marcas usando o Gerenciador de Catálogos, instruções SQL em um notebook ou editor de consultas SQL ou a API Python de Engenharia de Recursos.
Para recursos, você pode criar, editar e excluir marcas usando instruções SQL ou Gerenciador de Catálogos em um notebook ou editor de consultas SQL.
Consulte Aplicar marcas a objetos protegíveis do Catálogo do Unity e API Python.
O exemplo a seguir mostra como usar a API Python de Engenharia de Recursos para criar, atualizar e excluir marcas de tabelas 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 do Unity excluindo diretamente a tabela Delta no Catálogo do Unity usando o Gerenciador de Catálogos ou usando a API Python de Engenharia de Recursos.
Observação
- A exclusão de uma tabela de recursos pode levar a falhas inesperadas em produtores de upstream e consumidores de downstream (modelos, pontos de extremidade e trabalhos agendados). Você deve excluir repositórios online publicados com seu provedor de nuvem.
- Ao excluir uma tabela de recursos no Unity Catalog, a tabela Delta subjacente também é removida.
- Não há suporte para
drop_tableno 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 Catálogo do 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'
)
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de