FeatureStore Java SDK-Platform For AI(PAI)-阿里云帮助中心

Use the FeatureStore Java SDK to read online feature data from your PAI FeatureStore project at inference time. The SDK supports three feature types:

Feature type	Retrieval method	Typical use
Offline feature	Feature view (`FeatureView`)	Batch-synchronized user or item attributes
Real-time feature	Feature view (`FeatureView`)	Live-updated signals written directly to the online store
Sequence feature	Sequence feature view (`SequenceFeatureView`)	Ordered event history (clicks, plays, purchases)

To retrieve features grouped by model, use Model.getOnlineFeatures() or Model.getOnlineFeaturesWithEntity() instead of querying each feature view individually.

Prerequisites

Before you begin, make sure you have:

A FeatureStore project with at least one feature entity, feature view, and model feature configured and synchronized. See Configure a FeatureStore project.
An AccessKey ID and AccessKey secret for your Alibaba Cloud account. See Create an AccessKey.
The AccessKey ID and AccessKey secret stored as local environment variables. See Configure environment variables.

Note

The SDK connects directly to the online store. The client must run inside a Virtual Private Cloud (VPC). For example, a Hologres-backed online store is only reachable from within the VPC associated with that Hologres instance.

Step 1: Install the SDK

Download and install the FeatureStore Java SDK.

Step 2: Initialize the client

Create a Configuration object with your credentials and project name, then pass it to FeatureStoreClient. All subsequent feature retrieval calls go through this client.

API

Configuration configuration = new Configuration(regionId, accessKeyId, accessKeySecret, projectName);

Parameters

Parameter	Example	Description
`regionId`	`cn-hangzhou`	The region where your FeatureStore project is deployed
`accessKeyId`	`System.getenv("ACCESS_KEY_ID")`	AccessKey ID read from an environment variable
`accessKeySecret`	`System.getenv("ACCESS_KEY_SECRET")`	AccessKey secret read from an environment variable
`projectName`	`holo_pro`	The name of your FeatureStore project

Example

public class Constants {
    public static String accessId = "";
    public static String accessKey = "";
    public static String host = "paifeaturestore.cn-hangzhou.aliyuncs.com";

    static {
        // Read credentials from environment variables — never hardcode them.
        accessId = System.getenv("ACCESS_KEY_ID");
        accessKey = System.getenv("ACCESS_KEY_SECRET");
    }
}

// Initialize the configuration.
Configuration configuration = new Configuration("cn-hangzhou", Constants.accessId,
                                                Constants.accessKey, "dec8");
configuration.setDomain(Constants.host);

// Build the API client and the FeatureStore client.
ApiClient apiClient = new ApiClient(configuration);
FeatureStoreClient fsclient = new FeatureStoreClient(apiClient);

Step 3: Retrieve feature data from a feature view

Use FeatureView.getOnlineFeatures() to query features stored in a specific feature view. Both overloads return a FeatureResult containing one record per join ID.

API

// Retrieve all fields. No alias mapping.
public FeatureResult getOnlineFeatures(String[] joinIds);

// Retrieve selected fields, with optional field aliasing.
public FeatureResult getOnlineFeatures(String[] joinIds, String[] features, Map<String, String> aliasFields);

Parameters

Parameter	Example	Description
`joinIds`	`{"100001167","100001168"}`	Primary key values to look up. Returns one record per key.
`features`	`{"user_id","city"}`	Fields to include in the response. Pass `new String[]{"*"}` to return all fields.
`aliasFields`	`{"user_id":"uId"}`	Renames fields in the response. The key is the original field name; the value is the alias.

Example 1: Offline feature view

Retrieve feature data synchronized from an offline table.

// Get the offline feature view named "mo1".
FeatureView mo1 = project.getFeatureViewMap().get("mo1");
if (mo1 == null) {
    throw new RuntimeException("This featureView does not exist");
}

HashMap<String, String> ss = new HashMap<>();
FeatureResult features = mo1.getOnlineFeatures(
    new String[]{"100001167", "100004088", "100006646"},
    new String[]{"*"},
    ss
);

Sample response:

[
  {
    "user_id": 100001167,
    "gender": "male",
    "age": 28,
    "city": "Shenyang",
    "item_cnt": 0,
    "follow_cnt": 0,
    "follower_cnt": 0,
    "register_time": 1696658585,
    "tags": "2"
  },
  {
    "user_id": 100004088,
    "gender": "female",
    "age": 28,
    "city": "Changchun",
    "item_cnt": 0,
    "follow_cnt": 8,
    "follower_cnt": 0,
    "register_time": 1695618449,
    "tags": "1"
  },
  {
    "user_id": 100006646,
    "gender": "male",
    "age": 28,
    "city": "Changchun",
    "item_cnt": 0,
    "follow_cnt": 1,
    "follower_cnt": 1,
    "register_time": 1698213339,
    "tags": "1"
  }
]

Example 2: Real-time feature view

Retrieve feature data written directly to an online table.

// Get the real-time feature view named "tfv1".
FeatureView tfv1 = project.getFeatureViewMap().get("tfv1");
if (tfv1 == null) {
    throw new RuntimeException("This featureView does not exist");
}

FeatureResult rf = tfv1.getOnlineFeatures(
    new String[]{"35d3d5a52a7515c2ca6bb4d8e965149b",
                 "0ab7e3efacd56983f16503572d2b9915",
                 "84dfd3f91dd85ea105bc74a4f0d7a067"},
    new String[]{"*"},
    ss
);

Sample response:

[
  {"USER_MD5": "35d3d5a52a7515c2ca6bb4d8e965149b", "USER_NICKNAME": "Miss Sini"},
  {"USER_MD5": "0ab7e3efacd56983f16503572d2b9915", "USER_NICKNAME": "Love You"},
  {"USER_MD5": "84dfd3f91dd85ea105bc74a4f0d7a067", "USER_NICKNAME": "Elementary Student's Dad"}
]

Example 3: Sequence feature view

Retrieve ordered event sequences using SequenceFeatureView. Call project.getSeqFeatureView() instead of getFeatureViewMap().

// Get the sequence feature view named "ots_seq2".
SequenceFeatureView ots_seq2 = project.getSeqFeatureView("ots_seq2");
if (ots_seq2 == null) {
    throw new RuntimeException("This featureView does not exist");
}

// Retrieve all sequence fields. No feature or alias selection needed.
FeatureResult features2 = ots_seq2.getOnlineFeatures(new String[]{"157843277", "157843278"});

Sample response:

[
  {
    "user_id": "157843277",
    "click_50_seq": "null;200167895",
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;200167895",
    "click_50_seq_playtime": "null;15.0",
    "click_50_seq_event_time": "null;1704684504747",
    "click_50_seq_ts": "625662604;625662604"
  },
  {
    "user_id": "157843278",
    "click_50_seq": "null;200167895",
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;200167895",
    "click_50_seq_playtime": "null;15.0",
    "click_50_seq_event_time": "null;1704684504747",
    "click_50_seq_ts": "625662604;625662604"
  }
]

Step 4: Retrieve feature data from a model feature

A model feature groups the feature views and feature entities a model needs at serving time, so you can fetch all of them with a single call instead of querying each feature view individually. Use Model.getOnlineFeatures() to retrieve features from all associated feature entities, or Model.getOnlineFeaturesWithEntity() to scope the response to a specific feature entity.

API

// Retrieve features from all feature entities in the model feature.
public FeatureResult getOnlineFeatures(Map<String, List<String>> joinIds);

// Retrieve features from a specific feature entity in the model feature.
public FeatureResult getOnlineFeaturesWithEntity(Map<String, List<String>> joinIds, String featureEntityName);

Parameters

Parameter	Example	Description
`joinIds`	`{"user_id": ["101598051", "101598471"]}`	A map of join ID names to lists of primary key values. Each key corresponds to a feature entity.
`featureEntityName`	`"user"`	The name of the feature entity to scope the query to. Used only with `getOnlineFeaturesWithEntity()`.

A model feature can be associated with multiple feature entities. Provide the same number of IDs for each join ID type. The SDK pairs IDs by position across all lists.

Example 1: Model feature without sequence features

This example retrieves features for user_id and item_id from the model feature model_ots1, which joins a user feature entity and an item feature entity.

Model mf1 = project.getModelFeature("model_ots1");

HashMap<String, List<String>> mm = new HashMap<>();
mm.put("user_id", Arrays.asList("101598051", "101598471", "101601287"));
mm.put("item_id", Arrays.asList("200004157", "200006185", "200034730"));

Retrieve features from all feature entities:

FeatureResult fr1 = mf1.getOnlineFeatures(mm);

Sample response:

[
  {
    "user_id": 101598051, "gender": "male", "age": 28, "city": "Hangzhou",
    "item_cnt": 0, "follow_cnt": 0, "follower_cnt": 0,
    "register_time": 1695785665, "tags": "1",
    "item_id": 200004157, "author": 137649839, "category": 2,
    "click_count": 0, "duration": 18.0, "praise_count": 30,
    "pub_time": 1698208690, "title": "#Workout_Check-in"
  },
  {
    "user_id": 200004157, "gender": "female", "age": 31, "city": "Shenzhen",
    "item_cnt": 0, "follow_cnt": 1, "follower_cnt": 0,
    "register_time": 1695726582, "tags": "1",
    "item_id": 200006185, "author": 134195601, "category": 14,
    "click_count": 50, "duration": 55.0, "praise_count": 21,
    "pub_time": 1696700908, "title": "#Idiom_Story"
  },
  {
    "user_id": 101601287, "gender": "female", "age": 33, "city": "Shenzhen",
    "item_cnt": 0, "follow_cnt": 0, "follower_cnt": 55,
    "register_time": 1697519102, "tags": "0",
    "item_id": 200034730, "author": 112739045, "category": 6,
    "click_count": 2, "duration": 9.0, "praise_count": 0,
    "pub_time": 1696568654, "title": "#Workout_Check-in"
  }
]

Retrieve features from a specific feature entity only:

Pass the feature entity name ("server") to limit the response to fields from that entity.

FeatureResult fr2 = mf1.getOnlineFeaturesWithEntity(mm, "server");

Sample response:

[
  {"item_id": 200004157, "author": 137649839, "category": 2,
   "click_count": 0, "duration": 18.0, "praise_count": 30,
   "pub_time": 1698208690, "title": "#Workout_Check-in"},
  {"item_id": 200006185, "author": 134195601, "category": 14,
   "click_count": 50, "duration": 55.0, "praise_count": 21,
   "pub_time": 1696700908, "title": "#Idiom_Story"},
  {"item_id": 200034730, "author": 112739045, "category": 6,
   "click_count": 2, "duration": 9.0, "praise_count": 0,
   "pub_time": 1696568654, "title": "#Workout_Check-in"}
]

Example 2: Model feature with sequence features

When a model feature includes a sequence feature view, the response combines regular feature fields with sequence fields. This example uses mdt1, where join_id corresponds to user_id.

Model mdt1 = project.getModelFeature("mdt1");
if (mdt1 == null) {
    throw new RuntimeException("This modelFeature does not exist");
}

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

Retrieve features from all feature entities:

FeatureResult fr3 = mdt2.getOnlineFeatures(fsmap);

Sample response (sequence fields prefixed click_50_seq_ appear alongside regular attributes):

[
  {
    "click_50_seq_event_time": "null;1698170945",
    "gender": "male",
    "click_50_seq_ts": "1704292557212;1704292557212",
    "city": "Shenyang",
    "item_id": "200138790",
    "click_50_seq": "null;204153583",
    "author": 186784264,
    "pub_time": 1696574947,
    "follower_cnt": 0,
    "follow_cnt": 0,
    "item_cnt": 0,
    "click_count": 2,
    "title": "#Idiom_Story",
    "register_time": 1696658585,
    "tags": 2,
    "duration": 13.0,
    "click_50_seq_playtime": "null;98.93932923011255",
    "user_id": "100001167",
    "praise_count": 3,
    "click_50_seq_event": "null;click",
    "category": 20,
    "click_50_seq_item_id": "null;204153583",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698180365",
    "gender": "male",
    "click_50_seq_ts": "1704292547792;1704292547792;1704292547792",
    "city": "Ningbo",
    "item_id": 200385417,
    "click_50_seq": "null;299049390",
    "author": 189247964,
    "pub_time": 1696432224,
    "follower_cnt": 47,
    "follow_cnt": 0,
    "item_cnt": 0,
    "click_count": 4,
    "title": "#Idiom_Story",
    "register_time": 1697253820,
    "tags": 1,
    "duration": "9.0",
    "click_50_seq_playtime": "null;32.15018252408633",
    "user_id": 100024146,
    "praise_count": 0,
    "click_50_seq_event": "null;click",
    "category": 0,
    "click_50_seq_item_id": "null;299049390",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698170945",
    "gender": "male",
    "click_50_seq_ts": "1704292557212;1704292557212",
    "city": "Shenyang",
    "item_id": 200138790,
    "click_50_seq": "null;204153583",
    "author": 186784264,
    "pub_time": 1696574947,
    "follower_cnt": 0,
    "follow_cnt": 0,
    "item_cnt": 0,
    "click_count": 2,
    "title": "#Idiom_Story",
    "register_time": 1696658585,
    "tags": 2,
    "duration": 13.0,
    "click_50_seq_playtime": "null;98.93932923011255",
    "user_id": "100001167",
    "praise_count": 3,
    "click_50_seq_event": "null;click",
    "category": 20,
    "click_50_seq_item_id": "null;204153583",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698180365",
    "gender": "male",
    "click_50_seq_ts": "1704292547792;1704292547792",
    "city": "Ningbo",
    "item_id": 200385417,
    "click_50_seq": "null;299049390",
    "author": 189247964,
    "pub_time": 1696432224,
    "follower_cnt": 47,
    "follow_cnt": 0,
    "item_cnt": 0,
    "click_count": 4,
    "title": "#Idiom_Story",
    "register_time": 1697253820,
    "tags": 1,
    "duration": 9.0,
    "click_50_seq_playtime": "null;32.15018252408633",
    "user_id": "100024146",
    "praise_count": "0",
    "click_50_seq_event": "null;click",
    "category": 0,
    "click_50_seq_item_id": "null;299049390",
    "age": 28
  }
]

Retrieve features from a specific feature entity only:

FeatureResult fr4 = mdt1.getOnlineFeaturesWithEntity(fsmap, "client");

Sample response (user-side fields and sequence fields only, item fields excluded):

[
  {
    "click_50_seq_event_time": "null;1698170945",
    "gender": "male",
    "click_50_seq_ts": "1704292555552;1704292555552",
    "city": "Shenyang",
    "click_50_seq": "null;204153583",
    "follower_cnt": 0,
    "follow_cnt": 0,
    "item_cnt": 0,
    "register_time": 1696658585,
    "tags": 2,
    "click_50_seq_playtime": "null;98.93932923011255",
    "user_id": "100001167",
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;204153583",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698180365",
    "gender": "male",
    "click_50_seq_ts": "1704292546132;1704292546132;1704292546132",
    "city": "Ningbo",
    "click_50_seq": "null;299049390",
    "follower_cnt": 47,
    "follow_cnt": 0,
    "item_cnt": 0,
    "register_time": 1697253820,
    "tags": "1",
    "click_50_seq_playtime": "null;32.15018252408633",
    "user_id": 100024146,
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;299049390",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698170945",
    "gender": "male",
    "click_50_seq_ts": "1704292555552;1704292555552",
    "city": "Shenyang",
    "click_50_seq": "null;204153583",
    "follower_cnt": 0,
    "follow_cnt": 0,
    "item_cnt": 0,
    "register_time": 1696658585,
    "tags": 2,
    "click_50_seq_playtime": "null;98.93932923011255",
    "user_id": "100001167",
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;204153583",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698180365",
    "gender": "male",
    "click_50_seq_ts": "1704292546132;1704292546132;1704292546132",
    "city": "Ningbo",
    "click_50_seq": "null;299049390",
    "follower_cnt": 47,
    "follow_cnt": 0,
    "item_cnt": 0,
    "register_time": 1697253820,
    "tags": 1,
    "click_50_seq_playtime": "null;32.15018252408633",
    "user_id": "100024146",
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;299049390",
    "age": 28
  }
]

What's next

Configure a FeatureStore project — set up projects, feature entities, feature views, and model features
Create an AccessKey — get credentials for SDK authentication
FeatureStore Java SDK repository — full SDK source, release notes, and version history

上一篇: FeatureStore SDK reference 下一篇: FeatureStore SDK for Go