Pular para o conteúdo principal

Trabalhar com tabelas de recursos em Unity Catalog

Esta página descreve como criar e trabalhar com tabelas de recursos em Unity Catalog.

Esta página se aplica somente ao espaço de trabalho que está habilitado para Unity Catalog. Se o site workspace não estiver habilitado para Unity Catalog, consulte Trabalhar com tabelas de recurso no espaço de trabalho Recurso Store (legado).

Para obter detalhes sobre o comando e os parâmetros usados nos exemplos desta página, consulte a referência do recurso engenharia Python API.

Requisitos​

O recurso engenharia em Unity Catalog requer Databricks Runtime 13.2 ou superior.

Instalar recurso engenharia em Unity Catalog Python cliente​

recurso engenharia em Unity Catalog tem um cliente Python FeatureEngineeringClient. A classe está disponível em PyPI com o pacote databricks-feature-engineering e é pré-instalada em Databricks Runtime 13.3 LTS ML e acima. Se o senhor 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.

Python
%pip install databricks-feature-engineering

dbutils.library.restartPython()

Criar um catálogo e um esquema para tabelas de recurso em Unity Catalog​

O senhor deve criar um novo catálogo ou usar um catálogo existente para tabelas de recurso.

Para criar um novo catálogo, você deve ter o privilégio CREATE CATALOG na metastore.

SQL
CREATE CATALOG IF NOT EXISTS <catalog-name>

Para usar um catálogo existente, você deve ter o privilégio USE CATALOG no catálogo.

SQL
USE CATALOG <catalog-name>

As tabelas de recurso em Unity Catalog devem ser armazenadas em um esquema. Para criar um novo esquema no catálogo, você deve ter o privilégio CREATE SCHEMA no catálogo.

SQL
CREATE SCHEMA IF NOT EXISTS <schema-name>

Criar uma tabela de recursos em Unity Catalog​

nota

O senhor pode usar uma tabela Delta existente em Unity Catalog que inclua uma restrição primária key como uma tabela de recurso. Se a tabela não tiver um key primário definido, o senhor deverá atualizar a tabela usando ALTER TABLE instruções DDL para adicionar a restrição. Consulte Usar uma tabela Delta existente em Unity Catalog como uma tabela de recurso.

No entanto, adicionar um key primário a uma tabela de transmissão ou view materializado que foi publicado em Unity Catalog por um DLT pipeline exige a modificação do esquema da tabela de transmissão ou da definição do view materializado para incluir o key primário e, em seguida, atualizar a tabela de transmissão ou view materializado. Consulte Usar uma tabela de transmissão ou materializada view criada por um DLT pipeline como uma tabela de recurso.

As tabelas de recurso em Unity Catalog são tabelasDelta. As tabelas de recurso devem ter um primário key. As tabelas de recurso, como outros dados ativos em Unity Catalog, são acessadas usando um namespace de três níveis: <catalog-name>.<schema-name>.<table-name>.

O senhor pode usar Databricks SQL, o Python FeatureEngineeringClient ou um DLT pipeline para criar tabelas de recurso em Unity Catalog.

You can use any Delta table with a primary key constraint as a feature table. The following code shows how to create a table with a primary key:

SQL
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)
);

To create a time series feature table, add a time column as a primary key column and specify the TIMESERIES keyword. The TIMESERIES keyword requires Databricks Runtime 13.3 LTS or above.

SQL
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)
);

After the table is created, you can write data to it like other Delta tables, and it can be used as a feature table.

Criar uma tabela de recurso em Unity Catalog com DLT pipeline​

nota

O suporte DLT 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 visualização do DLT.

Qualquer tabela publicada a partir de um DLT pipeline que inclua uma restrição primária key pode ser usada como uma tabela de recurso. Para criar uma tabela em um DLT pipeline com um key primário, o senhor pode usar o Databricks SQL ou a interface de programação DLT Python.

Para criar uma tabela em um DLT pipeline com um key primário, use a seguinte sintaxe:

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

Para criar uma tabela de recurso de série temporal, adicione uma coluna de tempo como uma coluna primária key e especifique a palavra-chave TIMESERIES.

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

Depois que a tabela é criada, o senhor pode gravar dados nela como em qualquer outro conjunto de dados DLT, e ela pode ser usada como uma tabela de recurso.

Usar uma tabela Delta existente em Unity Catalog como uma tabela de recurso​

Qualquer tabela Delta em Unity Catalog com um key primário pode ser uma tabela de recurso em Unity Catalog, e o senhor pode usar o recurso UI e API com a tabela.

nota
  • Somente o proprietário da tabela pode declarar restrições primárias key. 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 é compatível com o recurso engenharia em Unity Catalog. Consulte Tipos de dados compatíveis.
  • A palavra-chave TIMESERIES requer o site Databricks Runtime 13.3 LTS ou acima.

Se uma tabela Delta existente não tiver uma restrição key primária, o senhor poderá criar uma da seguinte forma:

  1. Definir as colunas primárias de key como NOT NULL. Para cada coluna primária key, execução:

    SQL
    ALTER TABLE <full_table_name> ALTER COLUMN <pk_col_name> SET NOT NULL

  2. Altere a tabela para adicionar a restrição primária key:

    SQL
    ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1, pk_col2, ...)

    pk_name é o nome da restrição key primária. Por convenção, você pode usar o nome da tabela (sem esquema e catálogo) com o 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 primária key.

    Para transformar a tabela em uma tabela de recurso de série temporal, especifique a palavra-chave TIMESERIES em uma das colunas primárias key, como segue:

    SQL
    ALTER TABLE <full_table_name> ADD CONSTRAINT <pk_name> PRIMARY KEY(pk_col1 TIMESERIES, pk_col2, ...)

    Depois de adicionar a restrição primária key à tabela, ela aparecerá na UI de recurso e o senhor poderá usá-la como uma tabela de recurso.

Usar uma tabela de transmissão ou materializada view criada por um DLT pipeline como uma tabela de recurso​

Qualquer tabela de transmissão ou materializada view em Unity Catalog com um key primário pode ser uma tabela de recurso em Unity Catalog, e o senhor pode usar a UI de recurso e API com a tabela.

nota
  • O suporte DLT 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 visualização do DLT.
  • Somente o proprietário da tabela pode declarar restrições primárias key. O nome do proprietário é exibido na página de detalhes da tabela do Catalog Explorer.
  • Verifique se o recurso engenharia em Unity Catalog suporta o tipo de dados na tabela Delta. Consulte Tipos de dados compatíveis.

Para definir a chave primária de uma tabela de transmissão existente ou materializada view, atualize o esquema da tabela de transmissão ou materializada view no Notebook que gerencia o objeto. Em seguida, refresh a tabela para atualizar o objeto Unity Catalog.

A seguir, a sintaxe para adicionar um key primário a um view materializado:

SQL
CREATE OR REFRESH MATERIALIZED VIEW existing_live_table(
  id int NOT NULL PRIMARY KEY,
  ...
) AS SELECT ...

Usar uma view existente em Unity Catalog como uma tabela de recurso​

Para usar o view como uma tabela de recurso, o senhor deve usar a versão 0.7.0 do databricks-feature-engineering ou o acima, que está integrado ao Databricks Runtime 16.0 ML.

Um simples SELECT view em Unity Catalog pode ser uma tabela de recurso em Unity Catalog, e o senhor pode usar o recurso API com a tabela.

nota
  • Um SELECT view simples é definido como um view criado a partir de uma única tabela Delta em Unity Catalog que pode ser usada como uma tabela de recurso e cuja chave primária é selecionada 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 compatíveis para ver os tipos de dados compatíveis.
  • As tabelas de recurso apoiadas pela visualização não aparecem na UI de recurso.
  • Se as colunas forem renomeadas na tabela Delta de origem, as colunas na instrução SELECT da definição view deverão ser renomeadas para corresponder.

Aqui está um exemplo de um SELECT view simples que pode ser usado como uma tabela de recurso:

SQL
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 recursos baseadas na visualização podem ser usadas para treinamento e avaliação de modelos off-line. Eles não podem ser publicados em lojas on-line. O senhor não pode usar os recursos dessas tabelas e modelos baseados nesses recursos.

Atualizar uma tabela de recursos em Unity Catalog​

O senhor pode atualizar uma tabela de recursos em Unity Catalog adicionando novos recursos ou modificando linhas específicas com base no primário key.

Os metadados da tabela de recursos a seguir não devem ser atualizados:

  • Primário key.
  • Partição key.
  • Nome ou tipo de dados de um recurso existente.

Alterá-los fará com que o pipeline downstream que usa recurso para treinamento e modelos de serviço seja interrompido.

Adicionar um novo recurso a uma tabela de recursos existente em Unity Catalog​

O senhor pode adicionar novos recursos a uma tabela de recursos existente de duas maneiras:

  • Atualize a função de computação de recurso existente e a execução write_table com o retorno DataFrame. Isso atualiza o esquema da tabela de recursos e mescla novos valores de recurso com base no primário key.
  • 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 a chave primária e de partição das tabelas de recurso (se definidas). execução write_table com o DataFrame para gravar o novo recurso na tabela de recursos existente usando o mesmo primário key.

Atualizar apenas linhas específicas em uma tabela de recurso​

Use mode = "merge" em write_table. As linhas cujo key primário não existe no DataFrame enviado na chamada write_table permanecem inalteradas.

Python
from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
fe.write_table(
  name='ml.recommender_system.customer_features',
  df = customer_features_df,
  mode = 'merge'
)

Programar um Job para atualizar uma tabela de recursos​

Para garantir que as tabelas de recursos tenham sempre os valores mais recentes, o site Databricks recomenda que o senhor crie um trabalho que execute um Notebook para atualizar a tabela de recursos regularmente, por exemplo, todos os dias. Se o senhor já tiver criado um trabalho não programado, poderá convertê-lo em um trabalho programado para garantir que os valores de recurso estejam sempre atualizados. Consulte Visão geral da orquestração no Databricks.

O código para atualizar uma tabela de recurso usa mode='merge', conforme mostrado no exemplo a seguir.

Python
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 anteriores do recurso diário​

Definir uma tabela de recurso com um primário composto key. Inclua a data no site key. Por exemplo, para uma tabela de recurso customer_features, o senhor pode usar um primário composto key (date, customer_id) e uma partição key date para leituras eficientes.

A Databricks recomenda que o senhor ative o clustering líquido na tabela para obter leituras eficientes. Se o senhor não usar o clustering líquido, defina a coluna de data como uma partição key para obter um melhor desempenho de leitura.

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";

Em seguida, o senhor pode criar um código para ler a tabela de recursos filtrando date para o período de tempo de interesse.

O senhor também pode criar uma tabela de recurso de série temporal que permita pesquisas pontuais quando usar create_training_set ou score_batch. Consulte Criar uma tabela de recurso em Unity Catalog.

Para manter a tabela de recursos atualizada, configure um Job programado regularmente para gravar recursos ou transmitir novos valores de recursos para a tabela de recursos.

Criar uma computação de transmissão de recurso pipeline para atualizar o recurso​

Para criar uma computação de recurso de transmissão pipeline, passe uma transmissão DataFrame como argumento para write_table. Esse método retorna um objeto StreamingQuery.

Python
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 em Unity Catalog​

Use o site read_table para ler os valores do recurso.

Python
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 em Unity Catalog​

Use a UI de recurso para pesquisar ou procurar tabelas de recurso em Unity Catalog.

  1. Clique em ícone da loja de recursos recurso na barra lateral para exibir a UI do recurso.

  2. Selecione o catálogo com o seletor de catálogo para acessar view todas as tabelas de recurso disponíveis nesse catálogo. Na caixa de pesquisa, digite todo ou parte do nome de uma tabela de recurso, um recurso ou um comentário. O senhor também pode inserir todo ou parte do key ou o valor de uma tag. O texto de pesquisa não diferencia maiúsculas de minúsculas.

    exemplo de pesquisa de recurso

Obter metadados de tabelas de recurso em Unity Catalog​

Use get_table para obter metadados da tabela de recursos.

Python
from databricks.feature_engineering import FeatureEngineeringClient
fe = FeatureEngineeringClient()
ft = fe.get_table(name="ml.recommender_system.user_feature_table")
print(ft.features)

Use tags com recurso tables e recurso in Unity Catalog​

O senhor pode usar tags, que são simples par key-value, para categorizar e gerenciar suas tabelas de recursos e recursos.

Para tabelas de recurso, o senhor pode criar, editar e excluir tags usando o Catalog Explorer, as instruções SQL em um Notebook ou editor de consultas SQL ou o recurso engenharia Python API.

Para o recurso, o senhor pode criar, editar e excluir tags usando o Catalog Explorer ou as declarações do SQL em um editor de consultas do Notebook ou do SQL.

Consulte Aplicar tags a Unity Catalog objetos protegidos e recurso engenharia e espaço de trabalho recurso Store Python API .

O exemplo a seguir mostra como usar o recurso engenharia Python API para criar, atualizar e excluir tags de tabela de recurso.

Python
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 recurso em Unity Catalog​

O senhor pode excluir uma tabela de recurso em Unity Catalog excluindo diretamente a tabela Delta em Unity Catalog usando o Catalog Explorer ou usando o recurso engenharia Python API .

nota
  • A exclusão de uma tabela de recursos pode levar a falhas inesperadas em produtores upstream e consumidores downstream (modelos, endpoint e trabalho agendado).
  • Quando o senhor exclui uma tabela de recurso em Unity Catalog, a tabela subjacente Delta também é excluída.
  • drop_table não é compatível com Databricks Runtime 13.1 ML ou abaixo. Use o comando SQL para excluir a tabela.

O senhor pode usar Databricks SQL ou FeatureEngineeringClient.drop_table para excluir uma tabela de recurso em Unity Catalog:

SQL
DROP TABLE ml.recommender_system.customer_features;

Compartilhar uma tabela de recurso em Unity Catalog em um espaço de trabalho ou conta​

Uma tabela de recurso em Unity Catalog é acessível a todos os espaços de trabalho atribuídos ao metastore Unity Catalog da tabela.

Para compartilhar uma tabela de recurso com um espaço de trabalho que não esteja atribuído ao mesmo metastore Unity Catalog, use Delta Sharing.

Última atualização em