Pular para o conteúdo principal
Última atualização em

Materializar recurso declarativo

info

Beta

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

Depois de criar suas definições de recursos declarativas, que são armazenadas no Unity Catalog, você pode gerar dados de recursos a partir da sua tabela de origem usando essas definições. Esse processo é chamado de materialização do seu recurso. Databricks cria e gerencia um pipeline declarativo LakeFlow Spark para popular tabelas no Unity Catalog para treinamento de modelos e pontuação de lotes ou disponibilização online.

Para informações sobre servir recurso declarativo, veja Servir recurso declarativo.

Requisitos​

  • O recurso deve ser criado com a API declarativa de recursos e armazenado 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.

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

chamadas de funções da API​

materialize_features()​

Materializa uma lista de recursos declarativos em uma tabela Delta offline ou em um Feature Store Online. recurso deve ser registrado 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 declarative features 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],                            # 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 : execução em um programar fixo. Requerido para recurso de agregação (AggregationFunction).
  • TableTrigger : execução quando a tabela Delta upstream recebe um commit. Requerido para recurso ColumnSelection apoiado por um DeltaTableSource.

Não é possível misturar ColumnSelection e recurso de agregação em uma única chamada materialize_features porque eles exigem tipos de gatilho diferentes. Em vez disso, faça chamadas separadas.

Materializar para armazenamento offline​

Python
from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    CronSchedule, MaterializedFeaturePipelineScheduleState, 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",
        pipeline_schedule_state=MaterializedFeaturePipelineScheduleState.ACTIVE,
    ),
)

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, MaterializedFeaturePipelineScheduleState,
    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",
        pipeline_schedule_state=MaterializedFeaturePipelineScheduleState.ACTIVE,
    ),
)

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 recurso não tem janela de agregação, então eles 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 tenham sido excluídos. Quando o último recurso materializado nesse grupo é excluído, todos os recursos associados são automaticamente excluídos pelo repositório de recursos.

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 recurso não pode ser materializado porque representa dados fornecidos pelo chamador no momento da inferência (ou extraídos do DataFrame rótulo no momento do treinamento). Não existe uma tabela de origem para leitura — os valores existem apenas no payload da requisição ou no DataFrame de treinamento.

Limitações​

  • 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.
Nesta página