Feast 原生 Apache Iceberg 支持:通过 PyIceberg 直连任意 Iceberg Catalog 构建特征管道
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 只有两条路:
- 走 Spark 中转(重量级、启动慢);
- 把数据复制成 Feast 托管的 Parquet 文件(带来数据重复与治理断档)。
这两条路的代价都是"两份数据、两套元数据系统、彼此毫无关联"。
现在,Feast 原生提供了 IcebergSource,可以直接从任意 Iceberg Catalog 读取数据:
- 数据工程师在 Catalog(Unity Catalog、Glue、Hive 等)中构建 Iceberg 表;
- ML 工程师用
IcebergSource指向这张表; - 完成。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_storeAPI 仅支持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+)。