Materializar view de recurso

info

Visualização

Esse recurso está em Prévia Pública. Os administradores do espaço de trabalho podem controlar o acesso a esse recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

Depois de criar suas definições de View de Recursos, que são armazenadas no Unity Catalog, você pode produzir dados de recursos de sua tabela de origem usando as definições de recursos. Este processo é chamado de materialização dos seus recursos. Databricks cria e gerencia Pipelines Declarativos Lakeflow Spark para preencher tabelas no Unity Catalog para treinamento de modelos e pontuação em lotes ou veiculação online.

Para obter informação sobre como disponibilizar Recurso Views, consulte Disponibilizar Recurso Views.

Requisitos

• Os recursos devem ser criados como Views de recursos e armazenados no Unity Catalog.
• Para requisitos de versão, consulte Requisitos.
• ColumnSelection O recurso pode ser materializado em lojas online. Veja a materialização de ColumnSelection.
• RequestSource O recurso não pode ser materializado porque representa dados fornecidos no momento da inferência.

Permissões

A materialização interage com os privilégios MANAGE e READ FEATURE do Unity Catalog no recurso. Para descrições completas de privilégios, consulte READ RECURSO.

• A materialização de um recurso requer MANAGE. A chamada de materialize_features ou delete_materialized_feature cria e gerencia os pipelines declarativos do LakeFlow Spark e as tabelas do Unity Catalog, tornando-a uma operação de gerenciamento. É preciso ter MANAGE no recurso, juntamente com READ FEATURE para ler a definição do recurso que está sendo materializada.
• A leitura de dados materializados exige READ FEATURE. READ FEATURE no recurso concede acesso às tabelas offline e online que o apoiam, para que você possa consumir os dados materializados para treinamento e disponibilização de modelos. list_materialized_features também exige READ FEATURE.

Assim como em qualquer objeto Unity Catalog, também é necessário USE CATALOG no catálogo pai e USE SCHEMA no esquema pai. READ FEATURE e MANAGE concedidos em um esquema ou catálogo aplicam-se a todos os recursos atuais e futuros que ele contém.

Estruturas de dados da API

OfflineStoreConfig

Configuração para o armazenamento offline onde o recurso materializado será gravado. Quando materialize_features é chamado, o backend do repositório de recursos cria tabelas usando esse prefixo. Cada execução pipeline materializa os valores mais recentes dos recursos na tabela, de acordo com a materialização programada.

Python

OfflineStoreConfig(
    catalog_name: str,        # Catalog name for the offline table where materialized features will be stored
    schema_name: str,         # Schema name for the offline table
    table_name_prefix: str    # Table name prefix for the offline table. The pipeline may create multiple tables with this prefix, each updated at different cadences
)

Python

from databricks.feature_engineering.entities import OfflineStoreConfig

offline_store = OfflineStoreConfig(
    catalog_name="main",
    schema_name="feature_store",
    table_name_prefix="customer_features"
)

OnlineStoreConfig

Configuração do armazenamento online, que armazena recurso utilizado pelo modelo de operação. A materialização cria tabelas Delta com o catalog.schema.table_name_prefix e transmite as tabelas para o Feature Store Online com o mesmo nome.

Python

from databricks.feature_engineering.entities import OnlineStoreConfig

online_store = OnlineStoreConfig(
    catalog_name="main",
    schema_name="feature_store",
    table_name_prefix="customer_features_serving",
    online_store_name="customer_features_store"
)

MaterializedFeature

Representa uma Visualização de Recursos que foi materializada, ou seja, que possui uma representação pré-computada disponível no Unity Catalog. Existem recursos materializados separados para a tabela offline e a tabela online. Tipicamente, os usuários não instanciarão um MaterializedFeature diretamente.

chamadas de funções da API

materialize_features()

Materializa uma lista de Views de Recursos em uma tabela Delta offline ou em uma Feature Store Online. Recursos devem ser registrados no Unity Catalog antes de chamar esta função (por exemplo, usando create_feature ou register_feature). Recursos construídos localmente que não foram registrados não funcionarão.

Python

FeatureEngineeringClient.materialize_features(
    features: List[Feature],                                               # List of Feature Views to materialize
    offline_config: Optional[OfflineStoreConfig] = None,                   # Offline store config (aggregation features only)
    online_config: Optional[OnlineStoreConfig] = None,                     # Online store config
    trigger: Union[CronSchedule, TableTrigger, StreamingMode],              # Materialization trigger
) -> List[MaterializedFeature]:

O método retorna uma lista de recursos materializados, que contém metadados sobre quando os valores dos recursos são atualizados e as tabelas Unity Catalog onde os recursos são materializados.

Se forem fornecidos um OnlineStoreConfig e um OfflineStoreConfig , serão retornados dois recursos materializados para cada recurso fornecido, um para cada tipo de armazenamento.

O parâmetro trigger controla quando a execução do pipeline de materialização:

• CronSchedule : Em execução em um programar fixo. Necessário para recursos de agregação em lotes (AggregationFunction de DeltaTableSource).
• TableTrigger : execução quando a tabela Delta upstream recebe um commit. Requerido para recurso ColumnSelection apoiado por um DeltaTableSource.
• StreamingMode : Em execução como um pipeline de transmissão contínua. Necessário para recursos suportados por um StreamSource.

Não é possível misturar recursos que exigem diferentes tipos de gatilho em uma única chamada materialize_features. Faça chamadas separadas em vez disso.

Materializar para armazenamento offline

Python

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    CronSchedule, OfflineStoreConfig,
)

fe = FeatureEngineeringClient()

materialized = fe.materialize_features(
    features=features,
    offline_config=OfflineStoreConfig(
        catalog_name="main",
        schema_name="feature_store",
        table_name_prefix="customer_features"
    ),
    trigger=CronSchedule(
        quartz_cron_expression="0 0 * * * ?",  # Hourly
        timezone_id="UTC",
    ),
)

Materializar para armazenamento online

nota

Para materializar um recurso de agregação em um armazenamento online, você também deve materializá-lo em um armazenamento offline. Tanto offline_config quanto online_config são obrigatórios. O online_store_name deve fazer referência a um Feature Store Online existente. Para obter instruções sobre como criar um, consulte repositório de recursosDatabricks Online.

ColumnSelection recurso não requer um OfflineStoreConfig. Veja a materialização de ColumnSelection.

Python

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    CronSchedule, OfflineStoreConfig, OnlineStoreConfig,
)

fe = FeatureEngineeringClient()

materialized = fe.materialize_features(
    features=features,
    offline_config=OfflineStoreConfig(
        catalog_name="main",
        schema_name="feature_store",
        table_name_prefix="customer_features"
    ),
    online_config=OnlineStoreConfig(
        catalog_name="main",
        schema_name="feature_store",
        table_name_prefix="customer_features_serving",
        online_store_name="customer_features_store"
    ),
    trigger=CronSchedule(
        quartz_cron_expression="0 0 * * * ?",  # Hourly
        timezone_id="UTC",
    ),
)

Materializar recursos de transmissão

Recursos de transmissão só podem ser materializados em armazenamentos online; o parâmetro offline_config não é suportado. A materialização offline não é suportada porque recursos de transmissão exigem um pipeline em tempo real para garantir a atualização em microssegundos. Para treinamento ou avaliação offline, o cliente de engenharia de recursos recalculará os valores dos recursos com base em cada pontos de dados avaliado.

Recursos de transmissão não podem ser misturados com recursos de lotes na mesma chamada materialize_features.

Python

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    OnlineStoreConfig, StreamingMode,
)

fe = FeatureEngineeringClient()

materialized = fe.materialize_features(
    features=[streaming_feature],
    online_config=OnlineStoreConfig(
        catalog_name="my_catalog",
        schema_name="my_schema",
        table_name_prefix="streaming_features_serving",
        online_store_name="feature_store_online"
    ),
    trigger=StreamingMode(),
)

list_materialized_features()

Retorna uma lista de todos os recursos materializados no metastore Unity Catalog do usuário.

Por default, são retornados no máximo 100 recursos. Você pode alterar esse limite usando o parâmetro max_results .

Para filtrar o recurso materializado retornado por um nome de recurso, use o parâmetro opcional feature_name .

Python

FeatureEngineeringClient.list_materialized_features(
    feature_name: Optional[str] = None,     # Optional feature name to filter by
    max_results: int = 100,                 # Maximum number of features to be returned
) -> List[MaterializedFeature]:

delete_materialized_feature()

Antes de excluir um recurso materializado, remova ou atualize quaisquer modelos ou especificações de recursos que façam referência a ele.

Exclui um recurso materializado. O recurso a ser passado depende do tipo de recurso:

• Recurso de agregação : Passe o recurso materializado offline. Se existir um recurso materializado online para o mesmo recurso, ambos serão excluídos.
• ColumnSelection recurso : Passe o recurso materializado online. ColumnSelection recurso são materializados apenas para o armazenamento online (veja Materialização de ColumnSelection), portanto não há recurso offline correspondente.

Como parte da materialização, os recursos são agrupados por fonte de dados e janela de agregação para maior eficiência. ColumnSelection recursos não têm janela de agregação, portanto, são agrupados apenas por fonte de dados. O pipeline de materialização, a tabela offline e a tabela online não são excluídos até que todos os recursos agrupados sejam excluídos. Quando o último recurso materializado em um grupo é excluído, o repositório de recursos programa os recursos associados para limpeza automática por um processo em segundo plano. Consulte limpeza de recurso em segundo plano.

Para limpar recursos materializados, consulte a tabela associada a eles. Cada recurso na tabela (um por coluna) deve ser excluído antes que os recursos das tabelas compute e Delta sejam limpos.

Use list_materialized_features() para obter o argumento materialized_feature .

Python

FeatureEngineeringClient.delete_materialized_feature(
    materialized_feature: MaterializedFeature,  # Required: The materialized feature to delete
) -> None

Python

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import ColumnSelection

fe = FeatureEngineeringClient()

feature_names = [
    "main.feature_store.amount_sum_sliding_7d_1d",
    "main.feature_store.amount_sum_sliding_30d_1d",
    "main.feature_store.transaction_count_sliding_7d_1d",
    "main.feature_store.latest_transaction_amount",
    "main.feature_store.latest_user_tier",
]

for name in feature_names:
    feature = fe.get_feature(full_name=name)
    for mf in fe.list_materialized_features(feature_name=name):
        if isinstance(feature.function, ColumnSelection):
            # ColumnSelection features only have online materializations. Delete the online materialized feature directly.
            fe.delete_materialized_feature(materialized_feature=mf)
        elif not mf.is_online:
            # Aggregation features have both offline and online materializations. Delete the offline materialized feature to delete both.
            fe.delete_materialized_feature(materialized_feature=mf)
        # Online materialized aggregation features cannot be deleted directly. They are deleted via their paired offline materialized features.

Materialização de seleção de coluna

ColumnSelection recurso seleciona o valor mais recente de uma única coluna por key de entidade sem agregação. Eles só podem ser materializados em lojas online. Para casos de uso offline (treinamento e inferência de lotes), os recursos ColumnSelection são obtidos diretamente dos dados de origem no momento da consulta, portanto, a materialização offline não é necessária.

Comportamento de materialização

• O pipeline grava a linha mais recente por key de entidade na tabela online, sem janela de agregação.
• A materialização online preenche a tabela online com o valor mais recente para cada key de entidade.

Exemplo

Python

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    DeltaTableSource, Feature, ColumnSelection, TableTrigger, OnlineStoreConfig,
)

fe = FeatureEngineeringClient()

delta_source = DeltaTableSource(
    catalog_name="catalog",
    schema_name="schema",
    table_name="transactions",
)

amount_feature = Feature(
    source=delta_source,
    function=ColumnSelection("amount"),
    entity=["user_id"],
    timeseries_column="transaction_time",
    name="latest_transaction_amount",
)

# Register before materializing
amount_feature = fe.register_feature(
    feature=amount_feature,
    catalog_name="catalog",
    schema_name="schema",
)

mfs = fe.materialize_features(
    features=[amount_feature],
    online_config=OnlineStoreConfig(
        catalog_name="catalog",
        schema_name="feats_online",
        table_name_prefix="txn_",
        online_store_name="lb_usw2"
    ),
    trigger=TableTrigger(),
)

ColumnSelection recurso use TableTrigger, que executa o pipeline sempre que a tabela Delta de origem recebe um novo commit. Não é necessário offline_config porque ColumnSelection recurso são lidos diretamente da fonte para casos de uso offline (treinamento e inferência de lotes).

nota

RequestSource Os recursos não podem ser materializados porque eles representam dados fornecidos pelo chamador no momento da inferência (ou extraídos do DataFrame rotulado no momento do treinamento). Não há tabela de origem para ler. Os valores existem apenas no payload da solicitação ou no DataFrame de treinamento.

Limpeza de recursos em segundo plano

Quando você exclui um recurso materializado, a Databricks remove os metadados do recurso imediatamente. A infraestrutura associada (tabelas, pipelines e jobs) é limpa assincronamente por um processo em segundo plano.

Como múltiplos recursos materializados podem compartilhar as mesmas tabelas e pipelines, esses recursos compartilhados não são removidos até que todo recurso materializado que os referencia tenha sido excluído. Quando o último recurso materializado que compartilha um conjunto de tabelas é excluído, o processo em segundo plano exclui automaticamente os seguintes recursos:

• As tabelas Delta offline que contêm os dados de recurso materializados
• As tabelas online, se os recursos foram materializados para um armazenamento online.
• O pipeline de materialização
• O Job de orquestração

Esse processo em segundo plano usa uma entidade de serviço de sistema gerenciada pelo Databricks para realizar essas ações de limpeza em seu nome, incluindo a exclusão de tabelas, pipelines e Jobs em seu workspace. Não é necessária nenhuma ação do(a) senhor(a). A limpeza é totalmente gerenciada pelo repositório de recursos.

nota

Pode haver um pequeno atraso entre a exclusão do último recurso materializado em um grupo e a remoção das tabelas associadas e outros recursos.

Limitações

Recursos de lotes

• Pipelines de materialização em lotes são executados como Lakeflow Spark Declarative Pipelines serverless.
• O recurso de janela rolante de lotes não pode ser materializado. Devido à sua alta fidelidade de correção temporal, os recursos de janela deslizante para treinamento offline ou inferência de lotes são gerados dinamicamente para cada ponto de dados.
• ColumnSelection O recurso só pode ser materializado em lojas online.
• RequestSource recurso não pode ser materializado.
• Recursos materializados só podem ser excluídos no workspace em que foram criados.
• Para recursos de agregação materializados, o recurso materializado online não pode ser excluído diretamente. Ao excluir o recurso materializado offline correspondente, a alteração se propaga para ambos.
• Para recursos de agregação materializados criados antes de 20 de abril de 2026, o pipeline de materialização continua produzindo novos valores de recursos até que todos os recursos materializados no pipeline sejam excluídos, o que aciona a limpeza de recursos. Para criar um pipeline atualizado que suporte a exclusão por recurso, exclua e rematerialize o recurso.
• Para recursos materializados ColumnSelection , o pipeline de materialização continua produzindo novos valores de recursos até que todos os recursos materializados no pipeline tenham sido excluídos, o que aciona a limpeza de recursos.

Recursos de transmissão

• Recursos de transmissão podem ser materializados apenas para repositórios online. A materialização offline não é necessária porque os recursos de transmissão no momento do treinamento são projetados para serem recalculados a partir de eventos históricos por pontos de dados para fornecer precisão em nível de milissegundos.
• Recursos de transmissão não podem ser misturados com recursos de lotes em uma única chamada materialize_features.
• compute_features não é compatível com recursos de transmissão.
• O workspace deve estar em uma região que suporte instâncias Lakebase.
• Somente mensagens Kafka serializadas em JSON são compatíveis. Esquemas de mensagens devem ser fornecidos diretamente no formato JSON Schema. Registros de esquema (Confluent, Glue) não são formalmente compatíveis durante a prévia, mas se o esquema for fornecido diretamente, os pipelines podem ler de tópicos governados por um registro de esquema.
• Apenas RollingWindow é compatível com recursos de agregação de transmissão. TumblingWindow e SlidingWindow devem ser usados com recursos de lotes.
• Apenas as funções de agregação Count, Avg, Sum, StddevPop, Max, Min e Last são suportadas para recursos de transmissão.
• Recursos de seleção de coluna de fontes de transmissão não lidam com mensagens fora de ordem. O evento mais recente na transmissão do Kafka é mostrado, mesmo que o valor da coluna de série temporal seja anterior a um evento recebido anteriormente.
• Os pipelines de transmissão são reiniciados duas vezes por semana. Cada reinício pode causar atrasos de processamento e tempos de startup de até 1 minuto. Excluindo reinícios, a atualização p99 é de 200ms.
• O preenchimento retroativo de recursos para materialização não é compatível. Quando um recurso é materializado, ele é calculado a partir daquele ponto em diante. As agregações recém-criadas no armazenamento online são imprecisas até que seu intervalo de tempo tenha passado.
• Somente a Feature Store Online da Databricks é compatível.
• Somente catálogos padrão no Unity Catalog criados em seu próprio armazenamento de objetos na cloud são compatíveis. Os catálogos criados em armazenamento default não podem ser usados.
• Pipelines de materialização de transmissão são executados como pipelines serverless do Lakeflow Spark Declarative Pipelines.
• Somente workspace de nível Enterprise.