具体化特征视图

重要

此功能目前以公共预览版提供。工作区管理员可以从预览页控制对此功能的访问。请参阅 Manage Azure Databricks 预览版。

创建存储在 Unity 目录中的功能视图定义后，可以使用功能定义从源表生成特征数据。此过程称为特征具体化。 Azure Databricks创建和管理 Lakeflow 管道，以填充 Unity 目录中的表，以便进行模型训练和批量评分或联机服务。

有关提供功能视图的信息，请参阅服务功能视图。

要求

必须将功能创建为功能视图，并存储在 Unity 目录中。
有关版本要求，请参阅要求。
ColumnSelection 特征可以具体化到联机存储中。请参阅 ColumnSelection 具体化。
RequestSource 特征无法具体化，因为它们表示推理时提供的数据。

权限

物质化需要对该功能以及源资源和目的资源拥有权限。有关完整的 Unity 目录权限描述，请参见 Unity 目录权限参考。

实现某项功能需要 MANAGE。 调用 materialize_features 或 delete_materialized_feature 创建和管理支持 Lakeflow 管道和 Unity 目录表，因此它是一项管理操作。你必须在特征上拥有 MANAGE 权限，以及读取被具体化的特征定义的 READ FEATURE 权限。
读取源数据需要 SELECT。 对于使用Delta表源的功能，你必须在源表上设置 SELECT 。对于使用 Stream 源的功能，你必须对 Stream 的引入表具有 SELECT。

关于流认证配置所需的其他权限，请参见 Kafka 认证。
创建目标表需要 CREATE TABLE。 你必须在由 OnlineStoreConfig 或 CREATE TABLE 指定的每个架构上都拥有 OfflineStoreConfig。离线和在线目的地可能存在不同的模式或目录，实现需要对每个目的地拥有权限。
具体化到在线存储需要 CAN USE。 你必须在在线商店使用的Lakebase实例或项目中拥有 CAN USE 。有关Lakebase权限的信息，请参见 “项目授权”。
读取物化数据需要 READ FEATURE。 对特征的 READ FEATURE 权限将授予对支撑该特征的脱机表和联机表的访问权限，这样你便可以使用具体化数据进行模型训练和服务。 list_materialized_features 还需要 READ FEATURE。

对于参与实体化的每个 Unity Catalog 资源，你还需要在其父 Catalog 上具有 USE CATALOG 权限，并在其父架构上具有 USE SCHEMA 权限。此要求适用于该功能、每个源或 Stream 引入表以及每个已配置的目标。在架构或目录上授予的 READ FEATURE 和 MANAGE 适用于其当前和未来包含的所有对象。

API 数据结构

`OfflineStoreConfig`

脱机存储的配置，具体化后的特征将被写入到脱机存储中。当调用 materialize_features 时，特征存储后端使用此前缀创建表。每次管道运行时，都将根据具体化计划将最新特征值具体化到表中。

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`

联机存储的配置，联机存储用于存储模型服务使用的特征。具体化将使用 catalog.schema.table_name_prefix 创建 Delta 表，并将这些表流式传输到具有相同名称的联机特征存储中。

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`

表示已具体化的特征视图，即在 Unity Catalog 中具有可用的预计算表示形式。离线表和在线表分别有独立的物化特征。通常，用户不会直接实例化 MaterializedFeature 。

API 函数调用

`materialize_features()`

将特征视图列表具体化到脱机 Delta 表中，或具体化到联机特征存储中。在调用此函数之前，必须在 Unity 目录中注册功能（例如，使用 create_feature 或 register_feature）。未注册的本地构造功能将不起作用。

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]:

该方法返回具体化特征的列表，其中包含有关何时更新特征值的元数据，以及具体化功能的 Unity 目录表。

如果同时提供一个 OnlineStoreConfig 和一个 OfflineStoreConfig，则为每个提供的特征返回两个具体化特征，每个类型的存储对应一个特征。

参数 trigger 控制材质化管道的运行时间：

CronSchedule：按源自该功能计时设置的计划运行，或者按调用方提供的 Quartz cron 计划运行。支持批处理聚合功能（AggregationFunction 来自 DeltaTableSource）。
TableTrigger：当上游 Delta 表收到提交时运行。支持 ColumnSelection 特征和聚合特征（AggregationFunction），由 DeltaTableSource. 对于聚合特征，管道会被限流为每隔该特征窗口长度的一半时间最多运行一次。例如，在1小时内最多每30分钟一次，但从不超过每5分钟一次。
StreamingMode：作为连续流式处理管道运行。 StreamSource 支撑的特征所必需的。

不能在单个 materialize_features 调用中混合需要不同触发器类型的功能。请改为单独调用。

具体化到脱机存储

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

具体化到联机存储

Note

若要将聚合特征应用于联机存储，还必须具体化到脱机存储。 offline_config 和 online_config 均为必需。 online_store_name必须引用现有的在线特征库。有关创建一个的说明，请参阅 Databricks Online 特征库。

ColumnSelection 功能不需要 OfflineStoreConfig. 请参阅 ColumnSelection 具体化。

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

将流式特性实体化

流式处理特征只能具体化到联机存储；不支持 offline_config 参数。不支持脱机具体化，因为流式处理特征需要实时管道来确保亚秒级新鲜度。对于脱机训练或评估，特征工程客户端将根据评估的每个数据点重新计算特征值。

流式特性不能在同一次 materialize_features 调用中与批处理特性混用。

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

返回由全名标识的单个特征的具体化结果。 feature_name 是必需参数，且仅限关键字指定。若要查看多个特征的实体化，请先列出某个目录或架构中的特征，然后对返回的每个特征调用 list_materialized_features。

默认情况下，最多返回 100 个物化结果。可以使用参数更改此限制 max_results 。

FeatureEngineeringClient.list_materialized_features(
    *,                                      # Arguments are keyword-only
    feature_name: str,                      # Required: full name of the feature whose materializations to list
    max_results: int = 100,                 # Maximum number of materializations to return
) -> List[MaterializedFeature]:

`delete_materialized_feature()`

在删除具体化功能之前，请删除或更新引用该功能的任何模型或功能规格。

删除已具体化的特性。要传递的功能取决于功能类型：

聚合特征：传递脱机具体化特征。如果同一功能存在联机具体化功能，则会删除两者。
ColumnSelection 特征：传递联机具体化特征。 ColumnSelection 特征仅具体化到联机存储（请参阅 ColumnSelection 具体化），因此没有配对的脱机特征。

具体化过程中，功能按数据源和汇总时段进行组合，以提高效率。 ColumnSelection 功能没有聚合窗口，因此它们仅按数据源分组。在删除所有分组特征之前，实体化管道、离线表和在线表都不会被删除。若删除了某个组中的最后一个具体化特征，特征存储会将相关资源安排为由后台进程自动清理。请参阅后台资源清理。

要清理具体化特征，请查看与具体化特征关联的表。在清理计算和 Delta 表资源之前，必须删除表中的每个功能（每列一个）。

使用 list_materialized_features() 获取 materialized_feature 参数。

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

from databricks.feature_engineering import FeatureEngineeringClient

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:
    mfs = fe.list_materialized_features(feature_name=name)   # required, keyword-only
    offline = [mf for mf in mfs if not mf.is_online]
    for mf in (offline or mfs):
        fe.delete_materialized_feature(materialized_feature=mf)
    fe.delete_feature(full_name=name)

ColumnSelection 具体化

ColumnSelection 功能为每个实体键选择单个列的最新值，而无需聚合。它们只能具体化到联机存储。对于脱机用例（训练和批处理推理）， ColumnSelection 功能在查询时直接从源数据中提取，因此不需要脱机具体化。

具体化行为

管道将每个实体键值的最新行写入联机表，没有聚合窗口。
在线具体化将每个实体键的当前最新值填充到联机表中。

示例

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

每当源 Delta 表收到新提交时，ColumnSelection 功能使用 TableTrigger 来运行该管道。不需要 offline_config ，因为 ColumnSelection 功能直接从源读取脱机用例（训练和批处理推理）。

Note

RequestSource 特征无法具体化，因为它们表示调用方在推理时提供的数据（或在训练时从标记的数据帧中提取）。没有可读取的源表。这些值仅存在于请求有效负载或训练数据帧中。

后台资源清理

删除具体化功能时，Databricks 会立即删除功能元数据。关联的基础结构（表、管道和作业）由后台进程异步清理。

由于多个具体化特征可以共享相同的表和管道，因此，只有在引用这些资源的所有具体化特征都已被删除后，这些共享资源才会被删除。当共享一组表的最后一个物化特征被删除时，后台进程会自动删除以下资源：

包含物化特征数据的离线 Delta 表
联机表（如果特征已具体化到联机存储）
物化管道
编排作业

此后台进程使用由 Databricks 托管的系统服务主体，为你执行这些清理操作，包括删除工作区中的表、管道和作业。你无需执行任何操作。清理工作由特征存储全面管理。

Note

删除组中最后一个具体化特征与移除关联的表和其他资源，这两个操作之间可能存在短暂延迟。

查看具体化状态

要在 Databricks UI 中查看功能视图的实体化状态并调试实体化错误，请参见在 Unity Catalog 中浏览功能视图。

局限性

批处理功能

批量具体化管道以无服务器 Lakeflow 管道的形式运行。
批处理滚动窗口特性无法实现。由于其时间正确性的高保真度，会为每个数据点动态生成用于脱机训练或批量推理的滚动窗口特征。
ColumnSelection 特征只能具体化到联机存储中。
RequestSource 特征无法具体化。
只能在生成具体化特征的工作区中删除具体化特征。
对于具体化聚合特征，无法直接删除联机具体化特征。删除配对的脱机具体化特征，更改将同时传播到这两个配对特征。
对于在 2026 年 4 月 20 日之前创建的具体化聚合特征，具体化管道将继续生成新的特征值，直到删除管道中的所有具体化特征，这会触发资源清理。要创建支持按特征删除的更新管道，请删除特征，然后重新具体化特征。
对于具体化的 ColumnSelection 特征，具体化管道会继续生成新的特征值，直到管道中的所有具体化特征都被删除，从而触发资源清理。

流式功能

流式处理特征只能具体化到联机存储中。不需要进行离线实体化，因为训练阶段使用的流式特征被设计为可根据每个数据点对应的历史事件重新计算，从而实现毫秒级精度。
在单个 materialize_features 调用中，不能混合使用流式处理特性与批处理特性。
compute_features 不支持流式传输功能。
工作区必须位于支持 Lakebase 实例的区域。
仅支持 JSON 序列化的 Kafka 消息。必须直接以 JSON 架构格式提供消息架构。架构注册表（Confluent，Glue）在预览期间不受正式支持，但如果直接提供架构，管道可以从受架构注册表管理的主题中读取。
流式聚合功能仅支持 RollingWindow。 TumblingWindow 和 SlidingWindow 应与批处理功能一起使用。
对于流式特征，仅支持 Count、Avg、Min、StddevPop、FirstDistinct、Sum、First、LastDistinct、Max、Last、FirstN 和 LastN 聚合函数。
来自流式源的列选择功能无法处理乱序消息。显示 Kafka 流的最新事件，即使时间列值早于以前收到的事件也是如此。
流处理管道每周会重启两次。每次重启可能会导致处理延迟和启动时间长达 1 分钟。排除重启情况，p99 数据新鲜度为 200 毫秒。
不支持用于具体化的特征回填。当特征具体化时，它会从该点向前计算。在线商店中新创建的聚合结果在其时间窗口结束之前并不准确。
仅支持 Databricks 在线特征存储。
流式具体化管道以无服务器 Lakeflow 管道的形式运行。
仅限企业级工作区。

反馈

此页面是否有帮助？

Last updated on 2026-09-18