Partilhar via


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 FeatureEngineeringClientPython . 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 FeatureEngineeringClientou 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.

  1. 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.
  2. Crie uma tabela de recursos instanciando a FeatureEngineeringClient e usando create_tableo .
  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 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:

  1. 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 _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 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_featuresde 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.

  1. Clique em Ícone da loja de recursosRecursos na barra lateral para exibir a interface do usuário Recursos.

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

    Exemplo de pesquisa de recursos

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.