Feast Couchbase Columnar Offline Store 接入指南:在 Couchbase Capella Columnar 上构建点对点正确的历史特征检索

原创2026-09-16 13:36:051,764 阅读
文章标签:MLOps后端数据工程

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,需要依次完成以下前置步骤:

  1. 注册一个 Couchbase Capella 账号;
  2. 部署一个 Columnar 集群(Cluster);
  3. 创建访问控制(Access Control)账号——该账号需要具备读写权限;出于测试目的,官方建议直接赋予全部角色,避免不必要的权限问题;
  4. 配置允许的 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:点对点正确连接

这是离线存储最核心的能力。其流程为:

  1. 校验离线存储配置与所有特征视图的 batch_source 均为 Couchbase 类型;
  2. 推断实体数据帧的事件时间戳列,并计算事件时间范围(DataFrame 取 min/max,SQL 查询则执行 MIN()/MAX() 聚合,见 _get_entity_df_event_timestamp_range);
  3. 将实体数据上传为 Columnar 临时集合(_upload_entity_df);
  4. 用 build_point_in_time_query 基于 Jinja2 模板 MULTIPLE_FEATURE_VIEW_POINT_IN_TIME_JOIN 渲染多特征视图连接查询;
  5. 执行完毕后在 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)定义,后者是离线存储自身是否直接接收写入请求。

测试与集成现状

仓库中该功能的测试基建包括:

集成测试以 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。

登录后查看全文
feast