Feast 原生 Apache Iceberg 支持:通过 PyIceberg 直连任意 Iceberg Catalog 构建特征管道

原创2026-09-17 17:55:121,433 阅读
文章标签:MLOps后端数据工程

Feast 原生 Apache Iceberg 支持:通过 PyIceberg 直连任意 Iceberg Catalog 构建特征管道

本篇文章聚焦 Feast 官方博客《Feast Gets Native Apache Iceberg Support》所介绍的 IcebergSource 与 UnityCatalogSource 两大原生数据源,结合仓库源码(iceberg_source.py、unity_catalog_source.py、uc_provider.py)与离线存储实现,完整讲解"如何让特征表直接落在 Iceberg Catalog 中、由 Feast 直接读取"的架构与实战方案。读完本文,你将掌握 IcebergSource 的全部配置参数、五种 Catalog 后端的接入方法、DuckDB/Spark 两种离线存储的使用差异,以及 Unity Catalog 治理元数据同步的启用方式,可直接在你的特征仓库中落地。

为什么需要原生 Iceberg 支持

Apache Iceberg 已成为开放表格式的事实标准,你的数据湖很可能已经构建在 Iceberg 之上——无论是 Databricks、Snowflake、AWS,还是自建基础设施。但在此之前,把 Iceberg 表接入 Feast 只有两条路:

  1. 走 Spark 中转(重量级、启动慢);
  2. 把数据复制成 Feast 托管的 Parquet 文件(带来数据重复与治理断档)。

这两条路的代价都是"两份数据、两套元数据系统、彼此毫无关联"。

现在,Feast 原生提供了 IcebergSource,可以直接从任意 Iceberg Catalog 读取数据:

  1. 数据工程师在 Catalog(Unity Catalog、Glue、Hive 等)中构建 Iceberg 表;
  2. ML 工程师用 IcebergSource 指向这张表;
  3. 完成。Feast 通过 PyIceberg 直接从 Catalog 读取——只有一份数据、一个数据源真相(source of truth)。本地轻量读取选 DuckDB,需要分布式计算时选 Spark,而数据源定义在两种离线存储下完全一致。

这一能力的版本前提:原生 Iceberg 支持自 Feast 0.64+ 提供,安装方式为 pip install "feast[iceberg]"。

核心能力一览

任意 Iceberg Catalog

IcebergSource 支持 PyIceberg 所支持的全部 Catalog 后端:

catalog_type 后端 典型使用场景
"rest" Iceberg REST Catalog Databricks Unity Catalog、Apache Polaris、Project Nessie、Snowflake Open Catalog
"sql" SQL 后端 Catalog 本地开发(SQLite)、CI/CD、PostgreSQL 支撑的 Catalog
"hive" Hive Metastore 自建 Hadoop、EMR
"glue" AWS Glue Data Catalog AWS 原生湖仓
"dynamodb" DynamoDB Catalog 无服务器 AWS

两种离线存储均可用

操作 DuckDB Spark
feast apply 支持 支持
get_historical_features 支持 支持
materialize / materialize-incremental 支持 支持
get_online_features 支持 支持

两种离线存储都通过 PyIceberg 完成真正的 Iceberg 表扫描,区别只在于扫描之后的处理环节:DuckDB 在进程内处理 Arrow 表(无需 JVM、无需集群),非常适合本地开发和中等规模负载;Spark 则用于需要对大数据集做分布式计算的场景。同一个 IcebergSource 定义在两种离线存储下均可使用——只需修改 YAML 中的 offline_store.type。

完整的 Iceberg 语义

每次读取都走 PyIceberg 的 table.scan().to_arrow(),因此你获得的是完整的 Iceberg 语义:模式演进(schema evolution)、分区裁剪(partition pruning)、快照隔离(snapshot isolation),而不仅仅是原始 Parquet 文件读取。

快速开始

安装

pip install "feast[iceberg]"

定义数据源

from feast.infra.data_sources.contrib.iceberg_catalog import IcebergSource

driver_stats = IcebergSource(
    warehouse="my_catalog",
    namespace="ml_features",
    table="driver_hourly_stats",
    catalog_type="rest",
    endpoint="https://my-iceberg-catalog.example.com",
    token_env_var="CATALOG_TOKEN",
    timestamp_field="event_timestamp",
)

接入特征视图并执行

from datetime import timedelta
from feast import Entity, FeatureView, Field
from feast.types import Float64, Int64

driver = Entity(name="driver", join_keys=["driver_id"])

driver_stats_fv = FeatureView(
    name="driver_hourly_stats",
    entities=[driver],
    ttl=timedelta(days=365),
    schema=[
        Field(name="driver_id", dtype=Int64),
        Field(name="conv_rate", dtype=Float64),
        Field(name="acc_rate", dtype=Float64),
        Field(name="avg_daily_trips", dtype=Int64),
    ],
    source=driver_stats,
    online=True,
)
# feature_store.yaml
project: my_project
registry: data/registry.db
provider: local
online_store:
  type: sqlite
  path: data/online_store.db
offline_store:
  type: duckdb
feast apply

然后像使用其他 Feast 数据源一样使用它:

from feast import FeatureStore
import pandas as pd
from datetime import datetime, timezone

store = FeatureStore(repo_path=".")

# 训练数据
training_df = store.get_historical_features(
    entity_df=pd.DataFrame({
        "driver_id": [1001, 1002, 1003],
        "event_timestamp": [datetime(2026, 7, 1, tzinfo=timezone.utc)] * 3,
    }),
    features=["driver_hourly_stats:conv_rate", "driver_hourly_stats:acc_rate"],
).to_df()

# 物化到在线存储
store.materialize_incremental(end_date=datetime.now(tz=timezone.utc))

# 在线服务
online = store.get_online_features(
    features=["driver_hourly_stats:conv_rate", "driver_hourly_stats:acc_rate"],
    entity_rows=[{"driver_id": 1001}],
).to_dict()

各 Catalog 后端接入示例

AWS Glue

glue_source = IcebergSource(
    warehouse="my_glue_database",
    namespace="ml_features",
    table="driver_stats",
    catalog_type="glue",
    catalog_properties={"region_name": "us-east-1"},
    timestamp_field="event_timestamp",
)

Hive Metastore

hive_source = IcebergSource(
    endpoint="thrift://hive-metastore:9083",
    warehouse="warehouse",
    namespace="features",
    table="driver_stats",
    catalog_type="hive",
    timestamp_field="event_timestamp",
)

Apache Polaris / Nessie

polaris_source = IcebergSource(
    endpoint="https://polaris.example.com",
    warehouse="my_catalog",
    namespace="ml",
    table="features",
    catalog_type="rest",
    token_env_var="POLARIS_TOKEN",
    timestamp_field="event_timestamp",
)

本地开发(SQLite 后端)

开发与 CI/CD 场景下,可以用本地的 PyIceberg SQL Catalog,无需任何外部服务:

local_source = IcebergSource(
    warehouse="dev_warehouse",
    namespace="default",
    table="driver_stats",
    catalog_type="sql",
    catalog_name="dev_catalog",
    catalog_properties={
        "uri": "sqlite:////tmp/iceberg_catalog.db",
        "warehouse": "file:///tmp/iceberg_warehouse",
    },
    timestamp_field="event_timestamp",
)

实战:Unity Catalog 集成

Unity Catalog 用户在前述能力之上还能获得更简化的配置。UnityCatalogSource 继承自 IcebergSource,并叠加 UC 专属默认值:

  • 默认通过 DATABRICKS_HOST 与 DATABRICKS_TOKEN 环境变量建立连接——无需手动配置 endpoint 和 token;
  • 三级命名(warehouse.namespace.table)直接映射到 UC 的 catalog/schema/table 层级。

从源码看,这一默认逻辑在 unity_catalog_source.py 的构造函数中实现:当 endpoint 未指定时,自动拼接为 {DATABRICKS_HOST}/api/2.1/unity-catalog/iceberg;当 token_env_var 未指定时,默认取 DATABRICKS_TOKEN。仓库中的单元测试 test_iceberg_source.py(TestUnityCatalogSource.test_default_endpoint)也验证了该默认拼接行为。

Databricks 环境配置

export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN="dapi_your_token_here"
from feast.infra.data_sources.contrib.iceberg_catalog import UnityCatalogSource

driver_stats_source = UnityCatalogSource(
    warehouse="ml_catalog",
    namespace="driver_features",
    table="driver_hourly_stats",
    timestamp_field="event_timestamp",
    created_timestamp_column="created",
    description="Hourly aggregated driver statistics",
)

就这样,无需再传 endpoint 或 token 参数——它们来自环境变量。

可选:治理元数据同步

如果你希望 feast apply 用 feast.* 属性(项目名、特征视图、主键、负责人)标注 UC 表,可以启用 UnityCatalogProvider:

# feature_store.yaml
provider: unity_catalog

这一步是可选的。对大多数用户来说,provider: local 已足够;无论使用哪种 provider,读取、物化和在线服务的行为完全一致。

从源码看,UnityCatalogProvider 定义于 uc_provider.py,继承自 PassthroughProvider。它钩入 feast apply 生命周期,对每个 FeatureView 检查其 batch_source 是否为 UnityCatalogSource,若是且 register_as_feature_table=True,则:

  • 以 feast.project、feast.feature_view(以及可选的 feast.owner、feast.description、feast.tag.*)为属性,调用 UC API 注册特征表;
  • 若 sync_lineage=True,还会从流式源或上游特征视图收集血缘,写入 UC 的血缘图;
  • 删除特征视图时不会删除 UC 表,只更新属性 feast.is_feature_table=false 与 feast.deleted_at 时间戳。

OSS Unity Catalog

该集成同样适用于开源的 Unity Catalog,但存在一些差异:

能力 Databricks UC OSS UC
通过 Iceberg REST 读取 内置 需要 H2 库中的 uniform_iceberg_metadata_location
通过 SQL Catalog 读取 支持 支持
凭证下发(credential vending) 支持 不可用

针对 OSS UC,需要设置 credential_vending=False 和 token_env_var=None:

source = UnityCatalogSource(
    warehouse="unity",
    namespace="default",
    table="driver_hourly_stats",
    endpoint="http://localhost:8080/api/2.1/unity-catalog/iceberg",
    token_env_var=None,
    credential_vending=False,
    catalog_type="sql",    # OSS UC 推荐
    catalog_name="my_catalog",
    catalog_properties={
        "uri": "sqlite:////tmp/pyiceberg_catalog.db",
        "warehouse": "file:///tmp/warehouse",
    },
    timestamp_field="event_timestamp",
    register_as_feature_table=False,
)

工作原理

读取链路

无论哪种 Catalog 类型,所有数据读取都经过 PyIceberg:

IcebergSource.get_catalog_client()
    → PyIceberg catalog (REST / SQL / Hive / Glue / DynamoDB)
    → table.scan().to_arrow()
    → Arrow table
    → DuckDB ibis memtable 或 Spark DataFrame

如果 Catalog 配置错误,会得到明确的报错——这与 Feast 其他数据源的行为保持一致。

从源码层面印证:

  • DuckDB 路径:duckdb.py 中的 _read_iceberg_catalog_source() 通过 get_catalog_client() 加载表,最终执行 ibis.memtable(table.scan().to_arrow()),把 PyIceberg 扫描结果转成 ibis 内存表交给 DuckDB 处理。对应测试 test_iceberg_duckdb.py 验证了"PyIceberg scan → Arrow → ibis"的完整链路。
  • Spark 路径:spark.py 中通过 _register_iceberg_source_as_temp_view() 把 PyIceberg 扫描得到的 Arrow 表注册为 Spark 临时视图(视图名正是 iceberg_tmp_{table},与 get_table_query_string() 的返回值一致),再交给 SQL 查询使用。
  • REST 细节:对于 catalog_type="rest",iceberg_source.py 的 get_catalog_client() 使用的是仓库内置的轻量级 IcebergRestClient(见 iceberg_rest_client.py),其余类型则委托给 PyIceberg 的 load_catalog()。IcebergRestClient 会自动识别 endpoint 风格(Unity 风格的 .../api/2.1/unity-catalog/iceberg 与标准 REST 前缀风格),并把 404(表不存在)、401/403(认证失败)、500(服务端错误)分别映射为 TableNotFoundError、CatalogAuthError、IcebergCatalogError——这正是 validate() 能给出清晰错误信息的底层基础。
  • 类型映射:Iceberg 类型到 Feast 类型的映射由 _iceberg_type_to_feast_value_type() 完成(long→INT64、timestamp/timestamptz→INT64、decimal→DOUBLE、uuid→STRING 等),与 docs/reference/data-sources/iceberg.md 文档及测试 TestIcebergTypeMapping 保持一致。

Catalog 名称隔离

每个数据源都有一个 catalog_name 参数(默认 "feast_iceberg"),这是 PyIceberg 加载 Catalog 时使用的实例名。如果多个数据源指向不同 Catalog,请使用不同名称避免冲突:

production = IcebergSource(catalog_name="prod_catalog", ...)
staging = IcebergSource(catalog_name="staging_catalog", ...)

凭证下发(credential vending)

credential_vending 参数(默认 True)用于请求受限范围(scoped)的存储凭证。IcebergRestClient 通过 REST Catalog 的凭证下发接口换取临时凭证——从测试可见,支持 S3(s3.access-key-id / s3.secret-access-key / s3.session-token / s3.endpoint)与 GCS(gcs.oauth2.token)两种返回形式。当 credential_vending=False 时,请求头中不会携带 Authorization 与 X-Iceberg-Access-Delegation。OSS UC 不支持凭证下发,因此必须显式关闭。

暂不支持的能力

  • 回写 Iceberg/UC 表:Feast 只从已有表读取,不会把特征数据写回。write_to_offline_store API 仅支持 FileSource(DuckDB)与 SparkSource(Spark)。表的创建与数据写入由你的数据工程管道负责。
  • 建表:表必须已存在,Feast 才能读取。feast apply 注册的是 Feast 注册表中的特征视图,而不是 Catalog 中的表。

配置参考

IcebergSource

参数 默认值 说明
warehouse 必填 Catalog 或 warehouse 名称
namespace 必填 Schema 或命名空间
table 必填 表名
catalog_type "rest" 后端类型:"rest"、"sql"、"hive"、"glue"、"dynamodb"
catalog_name "feast_iceberg" PyIceberg 实例名(每个 Catalog 唯一,避免冲突)
endpoint None Catalog endpoint URL
catalog_properties {} 额外的 Catalog 配置(如 {"uri": "sqlite:///..."})
token_env_var None 存放认证 token 的环境变量名
credential_vending True 是否请求受限范围存储凭证
timestamp_field None 事件时间戳列
created_timestamp_column None 用于去重的创建时间戳列

其余继承自 Feast 通用 DataSource 的参数还包括 name(默认取 warehouse.namespace.table)、field_mapping(源列到特征名的映射)、description、tags、owner 等,均可在 iceberg_source.py 的构造函数签名中确认。该文件还提供了 fqn 属性(warehouse.namespace.table)、source_type()(返回 BATCH_ICEBERG)、get_table_column_names_and_types()(从 Catalog 拉取列名与类型)以及 validate()(连接校验,对 404/401/403/500 及网络错误给出可读的 ValueError)。

UnityCatalogSource(继承自 IcebergSource)

包含 IcebergSource 全部参数,并额外支持:

参数 默认值 说明
endpoint 取自 DATABRICKS_HOST 默认为 {DATABRICKS_HOST}/api/2.1/unity-catalog/iceberg
token_env_var "DATABRICKS_TOKEN" 默认使用 Databricks token 环境变量
register_as_feature_table True 是否在 feast apply 时向 UC 同步 feast.* 属性
sync_lineage True 是否在 UC 中记录血缘(仅 Databricks)

总结

IcebergSource 让 Feast 的离线存储直接对齐你现有的数据湖资产:无论是 Databricks Unity Catalog、Apache Polaris、Nessie、AWS Glue、Hive Metastore 还是本地 SQLite,特征表都留在原处,由 Feast 通过 PyIceberg 直接读取,并完整保留 Iceberg 的快照隔离、分区裁剪与模式演进语义。需要治理能力时,UnityCatalogSource + UnityCatalogProvider 还能在 feast apply 时自动把项目、特征视图、主键、负责人等元数据写回 UC。完整 API 参考见 Iceberg 数据源文档,安装时使用 pip install "feast[iceberg]"(Feast 0.64+)。

登录后查看全文
feast