FeatureStore Java SDK

获取 FeatureView 特征数据

通过 FeatureView 获取在线特征数据，支持离线特征、实时特征和序列特征的读取。

public FeatureResult getOnlineFeatures(String[] joinIds);
public FeatureResult getOnlineFeatures(String[] joinIds, String[] features, Map<String, String> aliasFields);

获取 ModelFeature 关联特征

通过 Model 获取关联的所有 FeatureEntity 特征数据，支持上级-下级 Entity 层级关系。

接口说明

// 获取所有根实体及其关联的下级实体特征
public FeatureResult getOnlineFeatures(Map<String, List<String>> joinIds);

// 获取指定 Entity 及其下级 Entity 特征
public FeatureResult getOnlineFeaturesWithEntity(Map<String, List<String>> joinIds, String featureEntityName);

参数说明

Model 可关联多个 FeatureEntity，存在上下级嵌套关系：

* 上级 Entity：包含主特征字段 + 关联下级 Entity 的字段

* 下级 Entity：被上级 Entity 引用，包含独立的特征字段

获取特征时，只需传入根实体的 join_id，SDK 会自动根据上级实体的特征值获取下级实体的特征。

不同场景示例

场景1：获取 Model 关联的全部特征

调用 getOnlineFeatures 传入所有根实体的 join_id，SDK 自动获取 Model 关联的全部特征（包括下级实体）。

Model model = project.getModelFeature("model_fv1");
if (null == model) {
    throw  new RuntimeException("model not found");
}

// 传入所有根实体的 join_id
Map<String, List<String>> joinIds = new HashMap<>();
joinIds.put("item_id", Arrays.asList("1001", "1002", "1003"));
joinIds.put("user_id", Arrays.asList("U001", "U002", "U003"));

// 会一并获取所有根实体及其关联下级实体的特征
FeatureResult result = model.getOnlineFeatures(joinIds);

返回示例：

{
  "item_id": "1001",
  "item_title": "智能手表",
  "item_price": 299.00,
  "author_id": "A001",
  "author_name": "张三",
  "author_fans_count": 10000,
  "category_id": "C001",
  "category_name": "电子产品",
  "category_level": 1,
  "user_id": "U001",
  "user_age": 28,
  "user_gender": "male"
}

场景2：获取指定 Entity 侧特征（含下级实体）

调用 getOnlineFeaturesWithEntity 指定 Entity 名称，获取该 Entity 及其下级实体特征。示例中 item Entity 关联 author、category 两个下级实体，返回 item 侧全部特征。

Map<String, List<String>> joinIds = new HashMap<>();
joinIds.put("item_id", Arrays.asList("1001", "1002", "1003"));

// 指定获取 item Entity 的特征
// item侧关联下级实体 author、category，一并返回
FeatureResult result = model.getOnlineFeaturesWithEntity(joinIds, "item");

返回示例：

{
  "item_id": "1001",
  "item_title": "智能手表",
  "item_price": 299.00,
  "author_id": "A001",
  "author_name": "张三",
  "author_fans_count": 10000,
  "category_id": "C001",
  "category_name": "电子产品",
  "category_level": 1
}

场景3：获取指定 Entity 侧特征（无下级实体）

调用 getOnlineFeaturesWithEntity 指定实体名称，获取该实体特征。示例中 author 实体无下级实体，只返回 author 本身的特征字段。

Map<String, List<String>> joinIds = new HashMap<>();
joinIds.put("author_id", Arrays.asList("A001", "A002", "A003"));

// 指定获取 author Entity 的特征
// author侧无下级实体，只返回 author侧特征
FeatureResult result = model.getOnlineFeaturesWithEntity(joinIds, "author");

返回示例：

{
  "author_id": "A001",
  "author_name": "张三",
  "author_fans_count": 10000
}

ModelFeature 包含序列特征示例

当 ModelFeature 关联序列特征 FeatureView 时，返回数据中会包含序列特征字段：

Model model = project.getModelFeature("model_with_seq");
if (null == model) {
    throw  new RuntimeException("model not found");
}

Map<String, List<String>> joinIds = new HashMap<>();
joinIds.put("user_id", Arrays.asList("100001167", "100024146"));
joinIds.put("item_id", Arrays.asList("200138790", "200385417"));

FeatureResult result = model.getOnlineFeatures(joinIds);

返回示例：

[
  {
    "user_id": "100001167",
    "gender": "male",
    "age": 28,
    "city": "沈阳市",
    "item_id": "200138790",
    "title": "#成语故事",
    "click_count": 2,
    "click_50_seq": "null;204153583",
    "click_50_seq_item_id": "null;204153583",
    "click_50_seq_event": "null;click",
    "click_50_seq_playtime": "null;98.94",
    "click_50_seq_ts": "1704292557212;1704292557212"
  },
  {
    "user_id": "100024146",
    "gender": "male",
    "age": 28,
    "city": "宁波市",
    "item_id": "200385417",
    "title": "#健身打卡",
    "click_count": 4,
    "click_50_seq": "null;299049390",
    "click_50_seq_item_id": "null;299049390",
    "click_50_seq_event": "null;click",
    "click_50_seq_playtime": "null;32.15",
    "click_50_seq_ts": "1704292547792;1704292547792"
  }
]

写入功能

将特征数据实时写入 FeatureDB 数据源，支持实时特征和行为序列特征的写入。

FeatureView featureView = project.getFeatureView("user_feature_view");
if (null == featureView) {
    throw  new RuntimeException("featureview not found");
}

// 构造写入数据
Map<String, Object> record = new HashMap<>();
record.put("user_id", "user_001");
record.put("name", "张三");
record.put("age", 28);
record.put("city", "北京");

featureView.writeFeatures(Arrays.asList(record));
featureView.writeFlush();

List<Map<String, Object>> writeData = new ArrayList<>();
Map<String, Object> record = new HashMap<>();
record.put("user_id", "user_001");
record.put("name", "李四");
writeData.add(record);
// 默认整行替换，部分字段更新需指定 InsertMode
featureView.writeFeatures(writeData, InsertMode.PartialFieldWrite);

SequenceFeatureView sequenceFeatureView = project.getSeqFeatureView("sequence");
if (null == seqFeatureView) {
    throw new RuntimeException("sequence feature view not found");
}

// 构造序列数据
List<Map<String, Object>> writeData = new ArrayList<>();
Map<String, Object> data = new HashMap<>();
data.put("request_id", 901850344);
data.put("user_id", "172040759");
data.put("page", "home");
data.put("net_type", "wifi");
data.put("day_h", 17);
data.put("week_day", 6);
data.put("event_unix_time", System.currentTimeMillis()/1000);
data.put("item_id", "223466789");
data.put("event","click");
data.put("playtime", 54.7296554003366);
writeData.add(data);
sequenceFeatureView.writeFeatures(writeData);
sequenceFeatureView.writeFlush();