Materializar exibições de recursos

Depois de criar suas definições da Feature View, que ficam armazenadas no Unity Catalog, você pode gerar dados de atributos a partir da tabela de origem usando essas definições. Esse processo é chamado de materialização de seus recursos. O Azure Databricks cria e gerencia pipelines do Lakeflow para alimentar tabelas no Unity Catalog para treinamento de modelos e scoring em lote ou serving online.

Para informações sobre como disponibilizar Feature Views, consulte Disponibilizar Feature Views.

Requirements

• Os recursos devem ser criados como Exibições de Recursos e armazenados no Catálogo do Unity.
• Para obter requisitos de versão, consulte Requisitos.
• Recursos do ColumnSelection podem ser materializadas para armazenamentos virtuais. Consulte Materialização ColumnSelection.
• RequestSource as características não podem ser materializadas porque representam 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 obter descrições completas de privilégios, consulte READ FEATURE.

• A materialização de um recurso requer MANAGE. Chamar materialize_features ou delete_materialized_feature cria e gerencia os pipelines subjacentes do Lakeflow e as tabelas do Unity Catalog, portanto, é uma operação de gerenciamento. Você deve ter MANAGE na funcionalidade, juntamente com READ FEATURE para ler a definição da funcionalidade que está sendo materializada.
• A leitura de dados materializados requer READ FEATURE. READ FEATURE no recurso concede acesso às tabelas offline e online que o dão suporte, para que você possa consumir os dados materializados para treinamento e serviço de modelo. list_materialized_features também requer READ FEATURE.

Como ocorre com qualquer objeto do Unity Catalog, você também precisa de USE CATALOG no catálogo pai e de USE SCHEMA no esquema pai. READ FEATURE e MANAGE concedidos em um esquema ou catálogo se aplicam a todos os recursos atuais e futuros que ele contém.

Estruturas de dados de API

OfflineStoreConfig

Configuração para o armazenamento offline em que os recursos materializados serão gravados. Quando materialize_features é chamado, o back-end do repositório de recursos cria tabelas usando esse prefixo. Cada execução de pipeline materializa os valores de recurso mais recentes para a tabela de acordo com o agendamento de materialização.

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
)

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 para o armazenamento online, que armazena recursos usados pelo Serviço de Modelo. A materialização cria tabelas Delta com o catalog.schema.table_name_prefixe transmite as tabelas para o Armazenamento de Recursos Online com o mesmo nome.

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 recurso que foi materializada, ou seja, que tem uma representação pré-computada disponível no Unity Catalog. Há recursos materializados separados para a tabela offline e a tabela online. Normalmente, os usuários não instanciarão diretamente um MaterializedFeature.

Chamadas de função de API

materialize_features()

Materializa uma lista de Exibições de Recursos em uma tabela Delta offline ou em um Repositório de Recursos Online. Os recursos devem ser registrados no Catálogo do Unity antes de chamar essa função (por exemplo, usando create_feature ou register_feature). Recursos construídos localmente que não foram registrados não funcionarão.

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 de recurso são atualizados e as tabelas do Catálogo do Unity em que os recursos são materializados.

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

O parâmetro trigger define quando o pipeline de materialização será executado.

• CronSchedule: é executado em um agendamento fixo. Necessário para recursos de agregação em lote (AggregationFunction de DeltaTableSource).
• TableTrigger: é executado quando a tabela Delta upstream recebe uma confirmação. Necessário para funcionalidades ColumnSelection suportadas por DeltaTableSource.
• StreamingMode: é executado como um pipeline de streaming contínuo. Necessário para recursos apoiados por um StreamSource.

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

Materializar para o armazenamento offline

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 o armazenamento online

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 streaming

Os recursos de streaming só podem ser materializados para lojas online; não há suporte para o offline_config parâmetro. A materialização offline não é compatível porque as funcionalidades de streaming exigem um pipeline em tempo real para garantir atualização em menos de um segundo. Para treinamento ou avaliação offline, o cliente de engenharia de recursos recompilará os valores de recurso com base em cada ponto de dados avaliado.

Os recursos de streaming não podem ser misturados com recursos de lote na mesma materialize_features chamada.

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()

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

Por padrão, um máximo de 100 funcionalidades é retornado. Você pode alterar esse limite usando o max_results parâmetro.

Para filtrar os recursos materializados retornados por um nome de recurso, use o parâmetro opcional feature_name .

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 ao recurso.

Exclui uma funcionalidade materializada. O recurso que será passado depende do tipo de recurso:

• Recursos de agregação: transmitem o recurso materializado offline. Se houver um recurso materializado online para o mesmo recurso, ambos os recursos serão excluídos.
• Recursos ColumnSelection: transmitem o recurso materializado online. Os recursos ColumnSelection são materializados apenas para o armazenamento online (consulte a Materialização ColumnSelection), portanto, não há um recurso offline correspondente.

Como parte da materialização, as características são agrupadas pela fonte de dados e pela janela de agregação para maior eficiência. ColumnSelection os recursos não têm janela de agregação, portanto, são agrupados apenas pela 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 tenham sido excluídos. Quando o último recurso materializado em um grupo é excluído, o armazenamento de recursos programa a limpeza automática dos recursos associados por meio de um processo em segundo plano. Consulte a limpeza de recursos em segundo plano.

Para limpar características materializadas, consulte a tabela associada a uma característica materializada. Cada recurso na tabela (um por coluna) deve ser excluído antes que a computação e os recursos da tabela Delta sejam limpos.

Use list_materialized_features() para obter o materialized_feature argumento.

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

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 ColumnSelection

Os recursos ColumnSelection selecionam o valor mais recente de uma única coluna para cada chave de entidade sem realizar agregação. Eles só podem ser implementados em armazenamentos online. Para casos de uso offline (treinamento e inferência em lote), ColumnSelection os recursos são buscados 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 de cada chave de entidade na tabela online, sem janela de agregação.
• A materialização online preenche a tabela online com o valor mais recente por chave de entidade.

Exemplo

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(),
)

Os recursos ColumnSelection usam TableTrigger, que executa o pipeline sempre que a tabela Delta de origem recebe uma nova confirmação. Nenhum offline_config é necessário porque as ColumnSelection características são lidas diretamente da fonte para usos offline (treinamento e inferência em lote).

Limpeza de recursos em segundo plano

Quando você exclui um recurso materializado, o Databricks remove os metadados do recurso imediatamente. A infraestrutura associada (tabelas, pipelines e tarefas) é removida de forma assíncrona por um processo em segundo plano.

Como vários recursos materializados podem compartilhar as mesmas tabelas e pipelines, esses recursos compartilhados não são removidos até que todos os recursos materializados que fazem referência a eles sejam excluídos. 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 offline do Delta que contêm os dados de atributos materializados
• As tabelas online, se os recursos foram materializados para um armazenamento online
• O pipeline de materialização
• O trabalho de orquestração

Esse processo em segundo plano usa uma entidade de serviço do sistema gerenciada pelo Databricks para realizar essas ações de limpeza em seu nome, incluindo a exclusão de tabelas, pipelines e trabalhos em seu espaço de trabalho. Você não precisa fazer nada. A limpeza é totalmente gerenciada pelo armazenamento de recursos.

Limitações

Funcionalidades de processamento em lote

• Os pipelines de materialização em lote são executados como pipelines sem servidor do Lakeflow.
• Os recursos da janela sem interrupção em lote não podem ser materializadas. Devido à alta fidelidade temporal, os recursos de janela sem interrupção para treinamento offline ou inferência em lote são gerados dinamicamente para cada ponto de dados.
• ColumnSelection as funcionalidades apenas podem ser implementadas em lojas virtuais.
• Os recursos RequestSource não podem ser implementados.
• Os recursos materializados só podem ser excluídos no workspace no qual foram criados.
• Para recursos de agregação materializados, o recurso materializado online não pode ser excluído diretamente. Exclua o recurso materializado offline emparelhado e 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 recurso até que todos os recursos materializados no pipeline sejam excluídos, iniciando a limpeza de recursos. Para criar um pipeline atualizado que dê suporte à exclusão por recurso, exclua e materialize novamente 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 sejam excluídos, o que dispara a limpeza de recursos.

Recursos de streaming

• Os recursos de streaming só podem ser materializados para lojas online. A materialização offline não é necessária porque os atributos em streaming durante o treinamento são projetados para ser recomputados com base em eventos históricos para cada ponto de dados, a fim de fornecer precisão na escala de milissegundos.
• Os recursos de streaming não podem ser misturados com recursos de lote em uma única materialize_features chamada.
• compute_features não dá suporte a recursos de streaming.
• O workspace deve estar em uma região que dê suporte a instâncias do Lakebase.
• Há suporte apenas para mensagens Kafka serializadas por JSON. Os esquemas de mensagem devem ser fornecidos diretamente no formato de esquema JSON. Os registros de esquema (Confluent, Glue) não têm suporte formal durante a versão prévia, mas se você fornecer o esquema diretamente, os pipelines poderão ler a partir de tópicos regidos por um registro de esquema.
• Há suporte apenas RollingWindow para recursos de agregação de streaming. TumblingWindow e SlidingWindow devem ser usados com funcionalidades de processamento em lote.
• Somente as funções de agregação Count, Avg, Sum, StddevPop, Max, Min e Last têm suporte para funcionalidades de streaming.
• As funcionalidades de seleção de colunas em fontes de streaming não oferecem suporte a mensagens fora de ordem. O evento mais recente no fluxo Kafka é exibido, mesmo que o valor da coluna de série temporal seja anterior ao de um evento recebido anteriormente.
• Os pipelines de streaming são reiniciados duas vezes por semana. Cada reinicialização pode causar atrasos de processamento e tempos de inicialização de até 1 minuto. Excluindo reinicializações, a atualização p99 é de 200ms.
• Não há suporte para backfill de atributos na materialização. Quando uma funcionalidade é materializada, os cálculos são feitos a partir desse ponto em diante. As agregações recém-criadas na loja online são imprecisas até que a respectiva janela de tempo se encerre.
• Há suporte apenas para o Repositório de Recursos do Databricks Online .
• Há suporte apenas para catálogos padrão no Catálogo do Unity criados em seu próprio armazenamento de objetos de nuvem. Catálogos criados no armazenamento padrão não podem ser usados.
• Os pipelines de materialização de streaming são executados como pipelines lakeflow sem servidor.
• Somente para espaços de trabalho do nível Enterprise.