Vistas de Funcionalidade do Materialize

Depois de criar as suas definições da Feature View, que são armazenadas no Unity Catalog, pode produzir dados de características a partir da sua tabela de origem usando as definições de características. Este processo chama-se materializar as suas características. O Azure Databricks cria e gere pipelines Lakeflow para preencher tabelas no Unity Catalog para treino de modelos e pontuação em lote ou serviço online.

Para informações sobre como servir Visualizações de Funcionalidade, consulte Servir Visualizações de Funcionalidades.

Requerimentos

• As funcionalidades devem ser criadas como Vistas de Funcionalidades e armazenadas no Catálogo Unity.
• Para requisitos de versão, consulte Requisitos.
• ColumnSelection funcionalidades podem ser materializadas em lojas online. Consulte Materialização de Seleção de Coluna.
• RequestSource as características não podem ser materializadas porque representam dados fornecidos no momento da inferência.

Permissions

A materialização interage com os privilégios MANAGE e READ FEATURE do Unity Catalog da funcionalidade. Para descrições completas dos privilégios, consulte READ FEATURE.

• Materializar uma característica requer MANAGE. Chamar materialize_features ou delete_materialized_feature cria e gere os pipelines Lakeflow subjacentes e as tabelas do Unity Catalog, pelo que é uma operação de gestão. Tem de ter MANAGE na funcionalidade, bem como READ FEATURE para ler a definição da funcionalidade que está a ser materializada.
• A leitura de dados materializados requer READ FEATURE. READ FEATURE A funcionalidade concede acesso às tabelas offline e online que o suportam, para que possas consumir os dados materializados para treino e serviço de modelos. list_materialized_features também requer READ FEATURE.

Tal como acontece com qualquer objeto do Unity Catalog, também precisa de USE CATALOG no catálogo principal e de USE SCHEMA no esquema principal. READ FEATURE e MANAGE concedidos num esquema ou catálogo aplicam-se a todos os objetos atuais e futuros que este contém.

Estruturas de dados API

OfflineStoreConfig

Configuração para a loja offline onde as funcionalidades materializadas serão escritas. Quando materialize_features é chamado, o backend da feature store cria tabelas usando este prefixo. Cada execução de pipeline materializa os valores mais recentes das funcionalidades na tabela de acordo com o calendário 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 a loja online, que armazena as funcionalidades usadas pelo modelo que serve. A Materialization cria tabelas Delta com o catalog.schema.table_name_prefix, e transmite as tabelas para a Online Feature Store 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 Feature View que foi materializada, ou seja, que tem uma representação pré-computada disponível no Unity Catalog. Existem funcionalidades materializadas separadas para a mesa offline e a mesa online. Normalmente, os utilizadores não instanciam um MaterializedFeature direto.

Chamadas de função API

materialize_features()

Materializa uma lista de Feature Views numa tabela Delta offline ou numa Feature Store online. As funcionalidades devem ser registadas no Catálogo Unity antes de chamar esta função (por exemplo, usando create_feature ou register_feature). Características construídas localmente que não foram registadas não funcionam.

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 devolve uma lista de funcionalidades materializadas, que contêm metadados sobre quando os valores das funcionalidades são atualizados e as tabelas do Catálogo Unity onde as funcionalidades são materializadas.

Se forem fornecidas tanto uma OnlineStoreConfig como uma OfflineStoreConfig, então duas características materializadas são devolvidas por cada funcionalidade fornecida, uma para cada tipo de armazém.

O trigger parâmetro controla quando o pipeline de materialização é executado:

• CronSchedule: Decorre com um calendário fixo. Necessário para funcionalidades de agregação em lote (AggregationFunction de DeltaTableSource).
• TableTrigger: Executa-se quando a tabela Delta a montante recebe um commit. Obrigatório para ColumnSelection funcionalidades suportadas por um DeltaTableSource.
• StreamingMode: Funciona como uma canalização de fluxo contínuo. Obrigatório para funcionalidades suportadas por um StreamSource.

Não podes misturar funcionalidades que exigem diferentes tipos de gatilhos numa única materialize_features chamada. Em vez disso, emita chamadas separadas.

Materializar para a loja 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",
    ),
)

Materialize na loja 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",
    ),
)

Funcionalidades de streaming do Materialize

As funcionalidades de streaming só podem ser materializadas para lojas online; O offline_config parâmetro não é suportado. A materialização em modo offline não é suportada porque as funcionalidades de streaming requerem um pipeline em tempo real para garantir uma atualização inferior a um segundo. Para treino ou avaliação offline, o cliente de engenharia de funcionalidades irá recalcular os valores das funcionalidades com base em cada ponto de dados avaliado.

Funcionalidades de streaming não podem ser misturadas com funcionalidades em 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()

Devolve uma lista de todas as funcionalidades materializadas na metastore do Catálogo Unity do utilizador.

Por defeito, um máximo de 100 caraterísticas são retornadas. Pode alterar este limite usando o max_results parâmetro.

Para filtrar as características materializadas devolvidas por um nome de funcionalidade, 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 eliminar uma funcionalidade materializada, remova ou atualize quaisquer modelos ou especificações de funcionalidades que façam referência a essa funcionalidade.

Apaga uma funcionalidade materializada. A funcionalidade a passar depende do tipo de característica:

• Funcionalidades de agregação: Passe a funcionalidade materializada offline. Se existir uma funcionalidade online materializada para a mesma funcionalidade, ambas são eliminadas.
• ColumnSelection funcionalidades: Forneça a funcionalidade materializada online. ColumnSelection as funcionalidades são materializadas apenas na loja online (ver materialização de ColumnSelection), portanto, não existe uma funcionalidade correspondente offline.

Como parte da materialização, as funcionalidades são agrupadas por fonte de dados e janela de agregação para maior eficiência. ColumnSelection As funcionalidades não têm janela de agregação, pelo que são agrupadas apenas por fonte de dados. O pipeline de materialização, a tabela offline e a tabela online não são eliminados até que todas as funcionalidades agrupadas tenham sido eliminadas. Quando a última funcionalidade materializada num grupo é eliminada, o armazenamento de funcionalidades agenda os recursos associados para limpeza automática por um processo em segundo plano. Ver Limpeza de recursos de antecedentes.

Para limpar as características materializadas, veja a tabela associada a uma característica materializada. Cada característica da tabela (uma por coluna) deve ser eliminada antes de os recursos de computação e tabela Delta serem limpos.

Usa list_materialized_features() para perceber 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 da Seleção da Coluna

ColumnSelection As funcionalidades selecionam o valor mais recente de uma única coluna por chave de entidade sem agregação. Só podem ser materializadas em lojas online. Para casos de uso offline (treino e inferência em lote), ColumnSelection as funcionalidades são obtidas diretamente dos dados de origem no momento da consulta, pelo que a materialização offline não é necessária.

Comportamento de materialização

• O pipeline escreve, por chave de entidade, a linha mais recente na tabela online, sem janela de agregação.
• A materialização online preenche a tabela online com o valor mais recente e atual 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(),
)

ColumnSelection as funcionalidades usam TableTrigger, que executa o pipeline sempre que a tabela Delta de origem recebe um novo commit. offline_config não é necessário porque as características ColumnSelection são lidas diretamente da fonte para casos de uso offline (treino e inferência em lote).

Limpeza de recursos em segundo plano

Quando elimina uma funcionalidade materializada, o Databricks remove imediatamente os metadados da funcionalidade. A infraestrutura associada (tabelas, pipelines e tarefas) é limpa de forma assíncrona por um processo em segundo plano.

Como múltiplas funcionalidades materializadas podem partilhar as mesmas tabelas e pipelines, estes recursos partilhados não são removidos até que todas as funcionalidades materializadas que as referenciam tenham sido eliminadas. Quando a última funcionalidade materializada que partilha um conjunto de tabelas é eliminada, o processo em segundo plano elimina automaticamente os seguintes recursos:

• As tabelas Delta offline que contêm os dados de funcionalidades materializadas
• As tabelas online, se as funcionalidades fossem materializadas numa loja online
• A canalização de materialização
• O trabalho de orquestração

Este processo em segundo plano utiliza um principal de serviço de sistema gerido pela Databricks para realizar estas ações de limpeza em seu nome, incluindo a eliminação de tabelas, pipelines e trabalhos no seu espaço de trabalho. Não é necessária qualquer ação da tua parte. A limpeza é totalmente gerida pela feature store.

Limitações

Funcionalidades em lote

• Os pipelines de materialização por lote são executados como pipelines Lakeflow sem servidor.
• As funcionalidades das janelas rolantes em lote não podem ser concretizadas. Devido à sua elevada fidelidade de correção temporal, funcionalidades de janelas rolantes para treino offline ou inferência em lote são geradas em tempo real para cada ponto de dados.
• ColumnSelection As funcionalidades só podem ser materializadas em lojas online.
• RequestSource funcionalidades não podem ser concretizadas.
• As funcionalidades materializadas só podem ser eliminadas no espaço de trabalho onde foram criadas.
• Para funcionalidades de agregação materializada, a funcionalidade materializada online não pode ser eliminada diretamente. Elimine a funcionalidade de materialização offline emparelhada e a alteração propaga-se para ambos.
• Para funcionalidades de agregação materializadas criadas antes de 20 de abril de 2026, o pipeline de materialização continua a produzir novos valores de funcionalidades até que todas as funcionalidades materializadas no pipeline sejam eliminadas, o que desencadeia a limpeza de recursos. Criar um pipeline atualizado que suporte a eliminação por característica, eliminação e reconstrução da funcionalidade.
• Para as características materializadas ColumnSelection, o pipeline de materialização continua a produzir novos valores de características até que todas as características materializadas no âmbito do pipeline sejam eliminadas, o que desencadeia a limpeza dos recursos.

Funcionalidades de streaming

• As funcionalidades de streaming só podem ser materializadas em lojas online. A materialização offline não é necessária porque as funcionalidades de streaming durante o treino são concebidas para serem recalculadas a partir de eventos históricos por ponto de dados, de modo a proporcionar precisão ao nível de milissegundos.
• Funcionalidades de streaming não podem ser misturadas com funcionalidades em lote numa única materialize_features chamada.
• compute_features não suporta funcionalidades de streaming.
• O espaço de trabalho deve estar numa região que suporte instâncias Lakebase.
• Apenas mensagens Kafka serializadas em JSON são suportadas. Os esquemas de mensagens devem ser fornecidos diretamente em formato de esquema JSON. Os registos de esquemas (Confluent, Glue) não são oficialmente suportados durante a versão preliminar, mas, se fornecer o esquema diretamente, os pipelines podem ler a partir de tópicos geridos por um registo de esquemas.
• Apenas RollingWindow é suportado para funcionalidades de agregação de streaming. TumblingWindow e SlidingWindow deve ser usado com funcionalidades em lote.
• Apenas as funções de agregação Count, Avg, Sum, StddevPop, Max, Min e Last são suportadas para funcionalidades de streaming.
• As funcionalidades de seleção de colunas provenientes de fontes de streaming não tratam mensagens fora de ordem. O evento mais recente no stream de Kafka é mostrado, mesmo que o valor da coluna da série temporal seja anterior ao de um evento previamente recebido.
• Os fluxos de processamento em streaming são reiniciados duas vezes por semana. Cada reinício pode causar atrasos no processamento e tempos de arranque de até 1 minuto. Excluindo os reinícios, a atualização no p99 é de 200 ms.
• O retropreenchimento da funcionalidade para a materialização não é suportado. Quando uma característica é materializada, calcula a partir desse ponto em diante. As agregações recém-criadas na loja online são imprecisas até que o seu período de tempo tenha passado.
• Apenas a Databricks Online Feature Store é suportada.
• Apenas são suportados catálogos padrão no Unity Catalog criados no seu próprio armazenamento de objetos na nuvem. Catálogos criados em armazenamento predefinido não podem ser utilizados.
• Os pipelines de materialização em streaming são executados como pipelines Lakeflow serverless.
• Apenas espaços de trabalho de nível empresarial.