Compartilhar via

Trabalhar com recursos no Repositório de Recursos do Workspace

  • Artigo

Observação

Esta documentação aborda o Repositório de Recursos do Workspace. O Databricks recomenda o uso da Engenharia de Recursos no Catálogo do Unity. O Repositório de Recursos do Workspace será preterido no futuro.

Esta página descreve como criar e trabalhar com tabelas de recursos no Repositório de Recursos do Workspace.

Observação

Se o workspace estiver habilitado para o Catálogo do Unity, qualquer tabela gerenciada pelo Catálogo do Unity que tenha uma chave primária será automaticamente uma tabela de recursos que você pode usar para treinamento e inferência de modelo. Todos os recursos do Catálogo do Unity, como segurança, linhagem, marcação e acesso entre workspaces, estão automaticamente disponíveis para a tabela de recursos. Para obter informações sobre como trabalhar com tabelas de recursos em um workspace habilitado para Catálogo do Unity, consulte Engenharia de Recursos no Catálogo do Unity.

Para saber como rastrear a linhagem e a atualização dos recursos, confira Descubra recursos e rastreie a linhagem deles.

Observação

Os nomes de tabela de banco de dados e de recursos podem conter apenas caracteres alfanuméricos e sublinhados (_).

Criar um banco de dados para tabelas de recursos

Antes de criar as tabelas de recursos, você precisa criar um banco de dados para armazená-las.

%sql CREATE DATABASE IF NOT EXISTS <database-name>

As tabelas de recursos são armazenadas como tabelas Delta. Ao criar uma tabela de recursos com create_table (cliente do Repositório de Recursos v0.3.6 e posterior) ou create_feature_table (v0.3.5 e anterior), o nome do banco de dados deve ser especificado. Por exemplo, esse argumento cria uma tabela Delta chamada customer_features no banco de dados recommender_system.

name='recommender_system.customer_features'

Quando você publica uma tabela de recursos em um repositório online, a tabela padrão e o nome do banco de dados são aqueles especificados quando você criou a tabela. Você pode especificar nomes diferentes usando o método publish_table.

A interface do usuário do Repositório de Recursos do Databricks mostra o nome da tabela e do banco de dados no repositório online, com outros metadados.

Criar uma tabela de recursos no Repositório de Recursos do Databricks

Observação

Você também pode registrar uma tabela Delta existente como uma tabela de recursos. Confira Registrar uma tabela Delta existente como uma tabela de recursos.

As etapas básicas para criar uma tabela de recursos são:

  1. 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.
  2. Crie uma tabela de recursos instanciando FeatureStoreClient e usando create_table (v0.3.6 e posterior) ou create_feature_table (v0.3.5 e anterior).
  3. Preencha a tabela de recursos usando write_table.

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

V0.3.6 e posterior

from databricks.feature_store import feature_table

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

# create feature table keyed by customer_id
# take schema from DataFrame output by compute_customer_features
from databricks.feature_store import FeatureStoreClient

customer_features_df = compute_customer_features(df)

fs = FeatureStoreClient()

customer_feature_table = fs.create_table(
  name='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 = fs.create_table(
#  ...
#  df=customer_features_df,
#  ...
# )

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

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

# Use write_table to write data to the feature table
# Overwrite mode does a full refresh of the feature table

fs.write_table(
  name='recommender_system.customer_features',
  df = customer_features_df,
  mode = 'overwrite'
)

V0.3.5 e inferior

from databricks.feature_store import feature_table

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

# create feature table keyed by customer_id
# take schema from DataFrame output by compute_customer_features
from databricks.feature_store import FeatureStoreClient

customer_features_df = compute_customer_features(df)

fs = FeatureStoreClient()

customer_feature_table = fs.create_feature_table(
  name='recommender_system.customer_features',
  keys='customer_id',
  schema=customer_features_df.schema,
  description='Customer features'
)

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

# customer_feature_table = fs.create_feature_table(
#  ...
#  features_df=customer_features_df,
#  ...
# )

# To use a composite key, pass all keys in the create_feature_table call

# customer_feature_table = fs.create_feature_table(
#   ...
#   keys=['customer_id', 'date'],
#   ...
# )

# Use write_table to write data to the feature table
# Overwrite mode does a full refresh of the feature table

fs.write_table(
  name='recommender_system.customer_features',
  df = customer_features_df,
  mode = 'overwrite'
)from databricks.feature_store import feature_table

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

# create feature table keyed by customer_id
# take schema from DataFrame output by compute_customer_features
from databricks.feature_store import FeatureStoreClient

customer_features_df = compute_customer_features(df)

fs = FeatureStoreClient()

customer_feature_table = fs.create_feature_table(
  name='recommender_system.customer_features',
  keys='customer_id',
  schema=customer_features_df.schema,
  description='Customer features'
)

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

# customer_feature_table = fs.create_feature_table(
#  ...
#  features_df=customer_features_df,
#  ...
# )

# To use a composite key, pass all keys in the create_feature_table call

# customer_feature_table = fs.create_feature_table(
#   ...
#   keys=['customer_id', 'date'],
#   ...
# )

# Use write_table to write data to the feature table
# Overwrite mode does a full refresh of the feature table

fs.write_table(
  name='recommender_system.customer_features',
  df = customer_features_df,
  mode = 'overwrite'
)

Registrar uma tabela Delta existente como uma tabela de recursos

Com a versão v0.3.8 e superior, você pode registrar uma tabela Delta existente como uma tabela de recursos. A tabela Delta precisa existir no metastore.

Observação

Para atualizar uma tabela de recursos registrada, use a API do Python para Repositório de Recursos.

fs.register_table(
  delta_table='recommender.customer_features',
  primary_keys='customer_id',
  description='Customer features'
)

Controlar o acesso às tabelas de recursos

Confira Controlar o acesso às tabelas de recursos.

Atualizar uma tabela de recursos

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

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

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

Adicionar novos recursos a uma tabela de recursos existente

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_table com 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 precisa conter as chaves primárias e as chaves de partição da tabela de recursos (se definido). Execute write_table com 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.

fs.write_table(
  name='recommender.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.

fs = FeatureStoreClient()

customer_features_df = compute_customer_features(data)

fs.write_table(
  df=customer_features_df,
  name='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 store_purchases, você pode usar uma chave primária composta (date, user_id) e a chave de partição date para leituras eficientes.

fs.create_table(
  name='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 especificando a coluna date como uma chave de carimbo de data/hora usando o argumento timestamp_keys.

fs.create_table(
  name='recommender_system.customer_features',
  primary_keys=['date', 'customer_id'],
  timestamp_keys=['date'],
  schema=customer_features_df.schema,
  description='Customer timeseries features'
)

Isso permite pesquisas pontuais ao usar create_training_set ou score_batch. O sistema executa uma união de carimbo de data/hora usando o timestamp_lookup_key especificado por você.

Para manter a tabela de recursos atualizada, configure um trabalho agendado regularmente para gravar 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, 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  # not shown

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

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

Ler de uma tabela de recursos

Use read_table para ler os valores de recursos.

fs = feature_store.FeatureStoreClient()
customer_features_df = fs.read_table(
  name='recommender.customer_features',
)

Pesquisar e procurar tabelas de recursos

Use a interface do usuário do Repositório de Recursos para pesquisar ou procurar tabelas de recursos.

  1. Na barra lateral, selecione Machine Learning > Repositório de Recursos para exibir a interface do usuário do Repositório de Recursos.

  2. Na caixa de pesquisa, insira todo ou parte do nome de uma tabela de recursos, um recurso ou uma fonte de dados usada para computação de recurso. 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.

    Feature search example

Obter metadados da tabela de recursos

A API usada para obter os metadados da tabela de recursos depende da versão do Databricks Runtime que está sendo usada. Com v0.3.6 e posterior, use get_table. Com v0.3.5 e inferior, use get_feature_table.

# this example works with v0.3.6 and above
# for v0.3.5, use `get_feature_table`
from databricks.feature_store import FeatureStoreClient
fs = FeatureStoreClient()
fs.get_table("feature_store_example.user_feature_table")

Trabalhar com marcas de tabelas de recursos

As marcas são pares chave-valor que você pode criar e usar para pesquisar tabelas de recursos. Você pode criar, editar e excluir marcas usando a interface do usuário do Repositório de Recursos ou a API Python do Repositório de Recursos.

Trabalhar com marcas de tabelas de recursos na interface do usuário

Use a interface do usuário do Repositório de Recursos para pesquisar ou procurar tabelas de recursos. Para acessar a interface do usuário, na barra lateral, selecione Machine Learning > Repositório de Recursos.

Adicionar uma marca usando a interface do usuário do Repositório de Recursos

  1. Clique no Tag icon se ela não estiver aberta ainda. A tabela de marcas será exibida.

    tag table

  2. Clique nos campos Nome e Valor e insira a chave e o valor da marca.

  3. Clique em Adicionar.

Editar ou excluir uma marca usando a interface do usuário do Repositório de Recursos

Para editar ou excluir uma marca existente, use os ícones da coluna Ações.

tag actions

Trabalhar com marcas de tabela de recursos usando a API Python do Repositório de Recursos

Em clusters que executam a versão v.04.1 e superiores, você pode criar, editar e excluir marcas usando a API Python do Repositório de Recursos.

Requisitos

Cliente do Repositório de recursos v0.4.1 e superior

Criar tabela de recursos com a marca usando a API Python do Repositório de Recursos

from databricks.feature_store import FeatureStoreClient
fs = FeatureStoreClient()

customer_feature_table = fs.create_table(
  ...
  tags={"tag_key_1": "tag_value_1", "tag_key_2": "tag_value_2", ...},
  ...
)

Adicionar, atualizar e excluir marcas usando a API Python do Repositório de Recursos

from databricks.feature_store import FeatureStoreClient
fs = FeatureStoreClient()

# Upsert a tag
fs.set_feature_table_tag(table_name="my_table", key="quality", value="gold")

# Delete a tag
fs.delete_feature_table_tag(table_name="my_table", key="quality")

Atualizar fontes de dados para uma tabela de recursos

O repositório de recursos controla automaticamente as fontes de dados usadas para calcular recursos. Você também pode atualizar manualmente as fontes de dados usando a API de Python do Repositório de Recursos.

Requisitos

Cliente do Repositório de recursos v0.5.0 e superior

Adicionar fontes de dados usando a API de Python do Repositório de Recursos

Veja a seguir alguns comandos de exemplo. Para conhecer detalhes, a documentação da API.

from databricks.feature_store import FeatureStoreClient
fs = FeatureStoreClient()

# Use `source_type="table"` to add a table in the metastore as data source.
fs.add_data_sources(feature_table_name="clicks", data_sources="user_info.clicks", source_type="table")

# Use `source_type="path"` to add a data source in path format.
fs.add_data_sources(feature_table_name="user_metrics", data_sources="dbfs:/FileStore/user_metrics.json", source_type="path")

# Use `source_type="custom"` if the source is not a table or a path.
fs.add_data_sources(feature_table_name="user_metrics", data_sources="user_metrics.txt", source_type="custom")

Excluir fontes de dados usando a API de Python do Repositório de Recursos

Para conhecer detalhes, a documentação da API.

Observação

O comando a seguir exclui fontes de dados de todos os tipos ("table", "path" e "custom") que correspondem aos nomes de origem.

from databricks.feature_store import FeatureStoreClient
fs = FeatureStoreClient()
fs.delete_data_sources(feature_table_name="clicks", sources_names="user_info.clicks")

Excluir uma tabela de recursos

É possível excluir uma tabela de recursos usando a IU da Feature Store ou a API do Python para a Feature Store.

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 usando a API, a tabela Delta subjacente também é removida. Ao excluir uma tabela de recursos da interface do usuário, você deve remover a tabela Delta subjacente separadamente.

Excluir uma tabela de recursos usando a IU

  1. Na página da tabela de recursos, clique no Button Down à direita do nome da tabela de recursos e selecione Excluir. Se não tiver a permissão PODE GERENCIAR na tabela de recursos, você não verá essa opção.

    Select delete from drop-down menu

  2. Na caixa de diálogo Excluir Tabela de Recursos, clique em Excluir para confirmar.

  3. Para também remover a tabela subjacente de Delta, execute o comando a seguir em um notebook.

    %sql DROP TABLE IF EXISTS <feature-table-name>;

Excluir uma tabela de recursos usando a API Python do Repositório de Recursos

Com o cliente da Feature Store v0.4.1 e mais recente, é possível usar drop_table para excluir uma tabela de recursos. Quando você exclui uma tabela com drop_table, a tabela Delta subjacente também é removida.

fs.drop_table(
  name='recommender_system.customer_features'
)