Ler em inglês

Compartilhar via

Trabalhar com tabelas de recursos no Catálogo do Unity

  • Artigo

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 seu workspace não estiver habilitado para o Catálogo do Unity, confira Trabalhar com tabelas de características no Workspace Feature Store (herdado).

Para obter detalhes sobre os comandos e parâmetros usados nos exemplos desta página, consulte a Referência da API Python da engenharia de recursos.

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.

  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 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',
#   ...
# )

Criar uma tabela de recursos no Catálogo do Unity com o pipeline do Delta Live Tables

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. Para criar uma tabela em um pipeline do Delta Live Tables com uma chave primária, você pode usar o SQL do Databricks ou a interface de programação Python do Delta Live Tables.

Para criar uma tabela em um pipeline do 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 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.

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:

  1. 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 NULL

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

Para definir chaves primárias para uma exibição materializada ou tabela de fluxo existentes, atualize o esquema da exibição materializada ou tabela de fluxo 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:

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 Catálogo do Unity como uma tabela de recursos

Para usar uma exibição como uma tabela de recursos, você deve usar databricks-feature-engineering versão 0.7.0 ou superior, que é integrado ao Databricks Runtime 16.0 ML.

Uma visualização simples SELECT no Unity Catalog pode ser uma tabela de recursos no Unity Catalog, e a API de Recursos pode ser usada com a tabela.

Observação

  • Uma exibição SELECT simples é definida como uma exibição criada com base em uma só tabela Delta no Catálogo do Unity 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 com suporte para mais informações sobre tipos de dados com suporte.
  • Tabelas de características baseadas em visualizações não aparecem na interface de funcionalidades.
  • Se as colunas forem renomeadas na tabela Delta de origem, as colunas na instrução SELECT para a definição de visualizaçã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;

Tabelas de características baseadas em exibições podem ser usadas para treinamento e avaliação offline de modelos. Eles não podem ser publicados em lojas online. Não podem ser atendidas as características dessas tabelas e dos modelos baseados nessas características.

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_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 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 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. Confira Visão geral da orquestração no Databricks.

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.

O Databricks recomenda que você habilite 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 melhorar o 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 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.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 de uma tabela de recursos no Catálogo do Unity

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.

  1. Clique em Ícone do Repositório de RecursosRecursos na barra lateral para exibir a interface do usuário dos Recursos.

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

    Exemplo de pesquisa de recurso

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 tags a objetos protegíveis do Catálogo do Unity e API Python da engenharia de recursos e espaço de trabalho no Feature Store..

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

Compartilhar uma tabela de recursos no Catálogo do Unity entre espaços de trabalho ou contas

Uma tabela de recursos no Catálogo do Unity pode ser acessada por todos os espaços de trabalho atribuídos ao metastore do Catálogo do Unity 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 do Unity, use Compartilhamento Delta.