Trabalhar com tabelas de recursos no Catálogo Unity
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 ativado para o Catálogo Unity, consulte Trabalhar com tabelas de funcionalidades no Armazém de Funcionalidades do Espaço de Trabalho (legado).
Para obter detalhes sobre os comandos e parâmetros usados nos exemplos desta página, consulte a referência da API Python de engenharia de recursos.
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 tem um cliente FeatureEngineeringClient
Python . A classe está disponível no PyPI com o databricks-feature-engineering
pacote e é 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 encontrar 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 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 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á atualizá-la usando ALTER TABLE
instruções DDL 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 Unity Catalog por um pipeline Delta Live Tables requer modificar o esquema da tabela de streaming ou a definição de exibição materializada para incluir a chave primária e, em seguida, 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 Delta Live Tables como uma tabela de recursos.
As tabelas de recursos no Catálogo Unity são tabelas Delta. As tabelas de recursos devem ter uma chave primária. As tabelas de recursos, como outros ativos de dados no Unity Catalog, são acessadas usando um namespace de três níveis: <catalog-name>.<schema-name>.<table-name>
.
Você pode usar o Databricks SQL, o Python FeatureEngineeringClient
ou um pipeline Delta Live Tables para criar tabelas de recursos 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 como outras tabelas Delta e 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 usandocreate_table
o . - 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',
# ...
# )
Criar uma tabela de recursos no Unity Catalog com o pipeline Delta Live Tables
Nota
O suporte do Delta Live Tables para restrições de tabela está em Visualização pública. Os exemplos de código a seguir devem ser executados usando o canal de visualização Delta Live Tables.
Qualquer tabela publicada a partir de um pipeline Delta Live Tables que inclua uma restrição de chave primária pode ser usada como uma tabela de recursos. Para criar uma tabela em um pipeline Delta Live Tables com uma chave primária, você pode usar o Databricks SQL ou a interface de programação Python Delta Live Tables.
Para criar uma tabela em um pipeline Delta Live Tables com uma chave primária, use a seguinte sintaxe:
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 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.
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 ...
Depois que a tabela é criada, você pode gravar dados nela como outros conjuntos de dados Delta Live Tables e pode ser usada 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
- 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 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"
teriacustomer_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 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
- O suporte do Delta Live Tables para restrições de tabela está em Visualização pública. 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 de chave primária. O nome do proprietário é exibido na página de detalhes da tabela do Catalog Explorer.
- Verifique se a Engenharia de Recursos no Unity Catalog suporta o tipo de dados na tabela Delta. Veja Tipos de dados suportados.
Para definir chaves primárias para uma tabela de streaming existente ou uma exibição materializada, atualize o esquema da tabela de streaming ou da exibição materializada no bloco de anotações que gerencia o objeto. Em seguida, atualize a tabela para atualizar o objeto Unity Catalog.
Segue-se a sintaxe para adicionar uma chave primária a uma 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 ...
Usar uma exibição existente no Unity Catalog como uma tabela de recursos
Para usar uma vista como uma tabela de características, deverá usar a versão databricks-feature-engineering
0.7.0 ou superior, que está incorporada no Databricks Runtime 16.0 ML.
Uma visualização SELECT simples no Unity Catalog pode ser uma tabela de recursos no Unity Catalog, e você pode usar a API de recursos com a tabela.
Nota
- Uma exibição SELECT simples é definida como uma exibição criada a partir de uma única tabela Delta no Unity Catalog que pode ser usada como uma tabela de recursos e cujas chaves primárias são selecionadas sem cláusulas JOIN, GROUP BY ou DISTINCT. As palavras-chave aceitáveis na instrução SQL são SELECT, FROM, WHERE, ORDER BY, LIMIT e OFFSET.
- Consulte Tipos de dados suportados para tipos de dados suportados.
- As tabelas de recursos apoiadas por modos de exibição não aparecem na interface do usuário de recursos.
- Se as colunas forem renomeadas na tabela Delta de origem, as colunas na instrução SELECT para a definição de exibição deverão ser renomeadas para corresponder.
Aqui está um exemplo de uma exibição SELECT simples que pode ser usada como uma tabela de recursos:
CREATE OR REPLACE VIEW ml.recommender_system.content_recommendation_subset AS
SELECT
user_id,
content_id,
user_age,
user_gender,
content_genre,
content_release_year,
user_content_watch_duration,
user_content_like_dislike_ratio
FROM
ml.recommender_system.content_recommendations_features
WHERE
user_age BETWEEN 18 AND 35
AND content_genre IN ('Drama', 'Comedy', 'Action')
AND content_release_year >= 2010
AND user_content_watch_duration > 60;
As tabelas de funcionalidades baseadas em visões podem ser usadas para treino e avaliação de modelos em modo offline. Não podem ser publicados em lojas online. Funcionalidades dessas tabelas e modelos baseados nessas funcionalidades não podem ser disponibilizados.
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ária e 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. Consulte Programar e orquestrar fluxos de trabalho.
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_features
de recursos, você pode usar uma chave primária composta (date
, customer_id
) e uma chave date
de partição para leituras eficientes.
O Databricks recomenda que você habilite o clustering líquido na tabela para leituras eficientes. Se você não usar clustering líquido, defina a coluna de data como uma chave de partição para um melhor desempenho de leitura.
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)
)
-- If you are not using liquid clustering, uncomment the following line.
-- 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'],
# If you are not using liquid clustering, uncomment the following line.
# 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 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, 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.table("prod.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 o Gerenciador de Catálogos, instruções SQL em um bloco de anotações ou editor de consultas SQL ou a API Python de Engenharia de Recursos.
Para recursos, você pode criar, editar e excluir tags usando o Gerenciador de Catálogos ou instruções SQL em um bloco de anotações ou editor de consultas SQL.
Consulte Aplicar tags a objetos protegíveis do Unity Catalog e API Python do Feature Engineering and Workspace Feature Store.
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'
)
Compartilhar uma tabela de recursos no Unity Catalog entre espaços de trabalho ou contas
Uma tabela de recursos no Unity Catalog é acessível a todos os espaços de trabalho atribuídos ao metastore do Unity Catalog da tabela.
Para compartilhar uma tabela de recursos com espaços de trabalho que não estão atribuídos ao mesmo metastore do Catálogo Unity, use o Compartilhamento Delta.