Feast Couchbase Columnar Offline Store 接入指南:在 Couchbase Capella Columnar 上构建点对点正确的历史特征检索
Feast Couchbase Columnar Offline Store 接入指南:在 Couchbase Capella Columnar 上构建点对点正确的历史特征检索
Couchbase Columnar offline store 是 Feast 官方以 contrib(社区贡献)形式提供的离线存储插件,让特征仓库可以直接把 Couchbase Capella Columnar 中的集合(collection)当作批量数据源,执行 get_historical_features 点对点正确连接、pull_latest_from_table_or_query 最新值拉取等操作。读完本文,你将掌握如何安装插件、初始化模板、配置 feature_store.yaml、定义 CouchbaseColumnarSource 数据源,并理解其底层 SQL++ 点对点连接与实体数据帧上传的实现原理。
概述:Couchbase Columnar 离线存储能做什么
CouchbaseColumnarOfflineStore 位于 sdk/python/feast/infra/offline_stores/contrib/couchbase_offline_store/couchbase.py,是一个通过 type: couchbase.offline 注册的 Feast 离线存储实现。它专用于读取 CouchbaseColumnarSource 定义的数据源,即 Couchbase Capella Columnar 上的集合。需要特别说明的是,Couchbase Columnar 是 Couchbase Capella(cloud.couchbase.com)提供的服务形态,本文的离线存储与之配套使用。
该离线存储在读取实体数据(entity dataframe)时支持两种形式:
- SQL++ 查询字符串:直接以一段查询作为实体集合,Feast 会在 Columnar 中基于该查询创建临时集合;
- Pandas DataFrame:实体数据帧会被上传到 Couchbase Capella Columnar 中,作为一个临时集合参与后续连接运算。
从源码看,这两种路径分别对应 _upload_entity_df 中的两个分支:DataFrame 走 df_to_columnar 逐行插入,查询字符串走 CREATE COLLECTION ... AS <query> 物化(见 couchbase.py)。
免责声明:当前为实验性功能
官方明确声明,Couchbase Columnar offline store 未达到完整测试覆盖率,请不要假定其完全稳定。同时,源码中的 pull_latest_from_table_or_query、get_historical_features、pull_all_from_table_or_query 三个方法都会在调用时抛出 RuntimeWarning:
This offline store is an experimental feature in alpha development. Some functionality may still be unstable so functionality can change in the future.
这意味着该模块处于 alpha 开发阶段,接口与行为在未来版本中可能发生变化,生产环境使用前应充分评估与自测。本文所有命令与配置均以当前仓库实际实现为准。
快速开始:安装与模板初始化
使用该离线存储前,需要安装带 Couchbase 依赖的 Feast 包:
pip install 'feast[couchbase]'
从仓库的 CI 依赖锁定文件看,该插件依赖 couchbase==4.3.2 与 couchbase-columnar==1.0.0(见 sdk/python/requirements/py3.12-ci-requirements.txt)。随后可以用 Feast 自带的 Couchbase 模板初始化一个功能仓库:
feast init -t couchbase
该模板由 sdk/python/feast/templates/couchbase/ 目录提供,初始化后即生成 feature_repo/feature_store.yaml 与 feature_repo/feature_definitions.py 等文件,其中 bootstrap.py 负责把模板变量渲染进配置。
在 Couchbase Capella 中准备环境
要连上 Couchbase Capella Columnar,需要依次完成以下前置步骤:
- 注册一个 Couchbase Capella 账号;
- 部署一个 Columnar 集群(Cluster);
- 创建访问控制(Access Control)账号——该账号需要具备读写权限;出于测试目的,官方建议直接赋予全部角色,避免不必要的权限问题;
- 配置允许的 IP 地址(Allowed IPs)——必须放行运行 Feast 的机器公网 IP。
配置文件详解:feature_store.yaml
初始化模板生成的离线存储配置(节选离线部分)如下,其中 offline_store 的 type 必须是 couchbase.offline:
project: my_project
registry: data/registry.db
provider: local
offline_store:
type: couchbase.offline
connection_string: COUCHBASE_COLUMNAR_CONNECTION_STRING # Copied from Settings > Connection String page in Capella Columnar console, starts with couchbases://
user: COUCHBASE_COLUMNAR_USER # Couchbase cluster access name from Settings > Access Control page in Capella Columnar console
password: COUCHBASE_COLUMNAR_PASSWORD # Couchbase password from Settings > Access Control page in Capella Columnar console
timeout: 120 # Timeout in seconds for Columnar operations, optional
online_store:
path: data/online_store.db
配置类 CouchbaseColumnarOfflineStoreConfig(定义于 couchbase.py)的字段语义如下:
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type |
Literal | "couchbase.offline" |
固定值,用于注册离线存储实现 |
connection_string |
str(可空) | None |
从 Capella Columnar 控制台 Settings > Connection String 页面复制,以 couchbases:// 开头 |
user |
str(可空) | None |
从 Settings > Access Control 页面获取的集群访问账号名 |
password |
str(可空) | None |
对应账号的密码 |
timeout |
float | 120 |
Columnar 操作的超时秒数,可选参数 |
其中 timeout 是可选参数,不配置时源码会使用默认值 120 秒。type: couchbase.offline 到实现类的映射关系定义在 sdk/python/feast/repo_config.py。
定义数据源:CouchbaseColumnarSource
CouchbaseColumnarSource(定义于 sdk/python/feast/infra/offline_stores/contrib/couchbase_offline_store/couchbase_source.py)用于描述一个 Columnar 集合作为特征数据来源,官方示例:
from feast.infra.offline_stores.contrib.couchbase_offline_store.couchbase_source import (
CouchbaseColumnarSource,
)
driver_stats_source = CouchbaseColumnarSource(
name="driver_hourly_stats_source",
query="SELECT * FROM Default.Default.`feast_driver_hourly_stats`",
database="Default",
scope="Default",
collection="feast_driver_hourly_stats",
timestamp_field="event_timestamp",
created_timestamp_column="created",
)
各参数语义(对应源码构造函数注释):
| 参数 | 说明 |
|---|---|
name |
数据源名称,项目内唯一;未指定时默认取 collection 值;两者都为空会抛出 DataSourceNoNameException |
query |
用于取数的 SQL++ 查询,与 database/scope/collection 二选一使用 |
database |
Columnar 数据库名,默认 "Default" |
scope |
Columnar scope 名,默认 "Default" |
collection |
Columnar 集合名 |
timestamp_field |
事件时间戳字段,用于点对点连接(point-in-time join) |
created_timestamp_column |
行创建时间戳列,用于行去重 |
field_mapping |
字段名到特征名的映射字典,仅作用于特征字段,不作用于实体或时间戳字段 |
description / tags / owner |
描述、任意元数据键值对、维护者信息 |
从 get_table_query_string 的实现(couchbase_source.py)可以看到:当 database、scope、collection 三者齐全时,表名被渲染为 `database`.`scope`.`collection`(反引号包裹防止保留字冲突);否则退化为使用 (query) 子查询。
模板 sdk/python/feast/templates/couchbase/feature_repo/feature_definitions.py 中给出了完整用法:定义 driver 实体、以 CouchbaseColumnarSource 为 source 的 FeatureView、RequestSource、on-demand 特征视图以及 FeatureService,并可通过 PushSource 包装该数据源获得在线推送能力。
支持的数据类型
Couchbase Capella Columnar 数据源支持 BOOLEAN、STRING、BIGINT、DOUBLE 四种 Feast 基础类型。类型映射由 cb_columnar_type_to_feast_value_type 提供(见 couchbase_source.py)。此外,_infer_composite_type 方法允许数组(array)类型的存在,但会拒绝嵌套集合与复杂对象:数组必须是同质基本类型且只能嵌套一层,object、multiset 类型会直接抛出 ValueError,原因是 Feast 类型系统无法表达这类复杂嵌套结构。
功能矩阵:该离线存储支持什么
下表列出 CouchbaseColumnarOfflineStore 对离线存储标准接口的支持情况(详见 overview.md 的功能矩阵说明):
| 能力 | Couchbase Columnar |
|---|---|
get_historical_features(点对点正确连接) |
yes |
pull_latest_from_table_or_query(取最新特征值) |
yes |
pull_all_from_table_or_query(读取已保存数据集) |
yes |
offline_write_batch(将数据帧持久化到离线存储) |
no |
write_logged_features(将记录的特征持久化到离线存储) |
no |
CouchbaseColumnarRetrievalJob 的检索结果能力矩阵如下:
| 能力 | Couchbase Columnar |
|---|---|
| 导出为 dataframe | yes |
| 导出为 arrow table | yes |
| 导出为 arrow batches | no |
| 导出为 SQL | yes |
| 导出到数据湖(S3、GCS 等) | yes |
| 导出到数据仓库 | yes |
| 导出为 Spark dataframe | no |
| Python 版 on-demand 变换的本地执行 | yes |
| Python 版 on-demand 变换的远程执行 | no |
| 在离线存储中持久化结果 | yes |
| 执行前预览查询计划 | yes |
| 读取分区数据 | yes |
底层实现:三大核心方法与点对点正确连接
pull_latest_from_table_or_query:按 join key 取最新行
该方法为每个 join key 拉取最新一行。其生成的 SQL++ 查询利用窗口函数:
SELECT ... FROM (
SELECT <字段列表>,
ROW_NUMBER() OVER(PARTITION BY <join keys> ORDER BY <timestamp_field> DESC, <created_timestamp_column> DESC) AS _feast_row
FROM <表或查询> a
WHERE a.<timestamp_field> BETWEEN '<start>' AND '<end>'
) b
WHERE _feast_row = 1
当不指定 join key 时,Feast 会注入虚拟实体(DUMMY_ENTITY_ID / DUMMY_ENTITY_VAL),保证无实体特征视图也能正确取数。时间范围会先经过 normalize_timestamp 归一化处理(sdk/python/feast/infra/utils/couchbase/couchbase_utils.py)。
get_historical_features:点对点正确连接
这是离线存储最核心的能力。其流程为:
- 校验离线存储配置与所有特征视图的
batch_source均为 Couchbase 类型; - 推断实体数据帧的事件时间戳列,并计算事件时间范围(DataFrame 取 min/max,SQL 查询则执行
MIN()/MAX()聚合,见_get_entity_df_event_timestamp_range); - 将实体数据上传为 Columnar 临时集合(
_upload_entity_df); - 用
build_point_in_time_query基于 Jinja2 模板MULTIPLE_FEATURE_VIEW_POINT_IN_TIME_JOIN渲染多特征视图连接查询; - 执行完毕后在
finally中执行DROP COLLECTION <临时表> IF EXISTS清理临时集合。
点对点正确连接的 SQL++ 模板(couchbase.py)采用典型的分步 CTE 结构:
entity_dataframe:为实体表附加实体时间戳与各特征视图的entity_row_unique_id;*__entity_dataframe:按实体键 + 时间戳去重实体行;*__subquery:通过LET max_ts/LET min_ts计算时间窗口,先按timestamp_field <= max_ts过滤,再依据 FeatureView 的 TTL 用date_diff_str(..., "second")做时间差裁剪;*__base:与实体表做 INNER JOIN,限定event_timestamp <= entity_timestamp、TTL 窗口,若启用了created_timestamp_column还附加created_timestamp <= entity_timestamp条件;*__dedup:存在创建时间戳列时,按entity_row_unique_id + event_timestamp取MAX(created_timestamp)去重;*__latest:用ROW_NUMBER() OVER(PARTITION BY ... ORDER BY event_timestamp DESC, created_timestamp DESC)取每个实体行最新的特征行;*__cleaned:把最新行连接回 base 数据;- 最终
SELECT DISTINCT:以实体表为主表,逐个 LEFT JOIN 各特征视图结果,并用IFMISSINGORNULL处理缺失值、用TOSTRING/CONCAT拼接复合唯一 ID。
这套模板与 Feast 在其他离线存储(如 BigQuery、Redshift)上的点对点连接语义保持一致,只是将语法适配为 Couchbase 的 SQL++,并利用 IFMISSINGORNULL 等 N1QL 函数处理半结构化数据中的缺失值。
pull_all_from_table_or_query:读取已保存数据集
该方法按时间范围读取表或查询的全部行,生成简单的 SELECT <字段> FROM <表> WHERE <时间戳过滤> 查询。时间过滤条件由 get_timestamp_filter_sql 生成,时间戳值使用反引号包裹(cast_style="raw"),以适配 SQL++ 的时序常量语法。
检索结果处理与持久化
CouchbaseColumnarRetrievalJob 负责执行查询并转换结果:
to_df()/to_arrow():内部执行查询后,_to_arrow_internal将时间戳字段通过pd.to_datetime(value, utc=True)解析为带时区的 datetime,其余字段的空值替换为np.nan,最终用pa.Table.from_pylist构建 PyArrow 表(couchbase.py);to_sql():直接返回生成的 SQL++ 查询字符串,便于执行前预览查询计划(功能矩阵中的 "preview the query plan");persist():将结果写回 Columnar 临时集合,配合SavedDatasetCouchbaseColumnarStorage完成 "持久化结果" 能力。写入过程先CREATE COLLECTION ... PRIMARY KEY(pk: UUID) AUTOGENERATED再INSERT INTO ...,时间戳列会规范化为%Y-%m-%dT%H:%M:%S.%f+00:00格式(df_to_columnar,couchbase.py)。
连接集群使用 Credential.from_username_and_password 构造认证信息,并通过 ClusterOptions(timeout_options=...) 与每次查询的 QueryOptions(timeout=timedelta(seconds=config.timeout)) 控制超时(见 _get_columnar_cluster 与 _execute_query)。另外,CouchbaseColumnarLoggingDestination(couchbase_source.py)实现了日志目的地接口,可把线上推理日志写入 Columnar 集合用于离线分析,不过这属于 feature logging 能力,与功能矩阵中 write_logged_features 为 "no" 并不冲突——前者是写入目标(destination)定义,后者是离线存储自身是否直接接收写入请求。
测试与集成现状
仓库中该功能的测试基建包括:
- sdk/python/feast/infra/offline_stores/contrib/couchbase_columnar_repo_configuration.py:集成测试配置,
FULL_REPO_CONFIGS使用 AWS provider +CouchbaseColumnarDataSourceCreator,在线存储配 Redis; - sdk/python/feast/infra/offline_stores/contrib/couchbase_offline_store/tests/data_source.py:数据源测试创建器,内嵌
type: couchbase.offline的仓库配置; - 单元测试中
test_filter_by_created_timestamp.py、test_eq_cross_type.py等对 Couchbase 数据源类型转换与相等性做了覆盖。
集成测试以 AWS provider + Redis 在线存储组合运行,说明该离线存储通常与 Redis 在线存储搭配使用(模板 feature_store.yaml 中同时配置了 couchbase.online 与 couchbase.offline,二者独立配置连接信息)。
使用建议与限制
- 云上环境要求:必须先完成 Capella 账号注册、Columnar 集群部署、读写账号创建与 IP 白名单配置,否则连接会失败;
- 临时集合的创建与销毁:
get_historical_features会在 Columnar 中创建实体临时集合并在结束阶段删除,因此账号必须具备建集/删集权限,这也解释了官方"建议赋予全部角色"的测试建议; - 类型限制:仅支持
BOOLEAN、STRING、BIGINT、DOUBLE及一层同质数组,复杂嵌套对象会报错; - 在线写入能力缺失:
offline_write_batch与write_logged_features均不支持,需要写入离线数据时只能通过其他通道准备 Columnar 集合; - 稳定性提示:作为 contrib 模块且处于 alpha 阶段,接口可能在后续版本调整,升级 Feast 时需关注 CHANGELOG 与该模块变更。
如需横向对比其他离线存储(BigQuery、Snowflake、Spark 等)的功能矩阵,可参考 offline-stores 功能矩阵;Couchbase 在线存储的使用方式则参见 Couchbase online store。