Feature configuration - - Alibaba Cloud Documentation Center

FeatureConfs controls which user and item features the fine-ranking stage loads, and how those features are transformed before scoring. It maps scenario names to feature loading configurations, so different scenarios can use different feature sets.

{
  "FeatureConfs": {
    "<scene_name>": { ... }
  }
}

Key concepts

Term	Description
`FeatureConfs`	Top-level map. The key is the scenario name; the value is a feature loading configuration object.
`FeatureLoadConfs`	A list of feature loading jobs within a scenario. Each job pulls features from one data source.
`FeatureDaoConf`	Data access configuration for a single loading job — specifies the data source type, connection, and field selection.
`FeatureKey`	The lookup key. Format: `<side>:<field>`. For example, `user:uid` looks up the `uid` field on the user side; `item:id` looks up the `id` field on the item side.
`FeatureStore`	Where to store the retrieved features. Valid values: `user` or `item`.
`AsynLoadFeature`	When `true`, all jobs in `FeatureLoadConfs` run concurrently, reducing total loading time.

Choose a data source

Features can be loaded from Hologres, PAI-FeatureStore, Tablestore (OTS), and Redis. The table below summarizes the key differences.

Capability	Hologres	PAI-FeatureStore	Tablestore (OTS)	Redis
`AdapterType` value	`hologres`	`featurestore`	`tablestore`	`redis`
Field selection (`UserSelectFields` / `ItemSelectFields`)	Yes	Yes (with feature view)	Yes	Yes (HASH format only)
Local cache (`CacheSize` / `CacheTime`)	Yes	Yes	Yes	Yes
Feature view selection	No	Yes	No	No
Data format options	—	—	—	`string` (CSV / JSON) or `hash`

Hologres

Each entry in FeatureLoadConfs loads from one Hologres table. Configure separate entries for user and item features.

{
  "FeatureConfs": {
    "scene_name": {
      "AsynLoadFeature": true,
      "FeatureLoadConfs": [
        {
          "FeatureDaoConf": {
            "AdapterType": "hologres",
            "HologresName": "holo-pai",
            "FeatureKey": "user:uid",
            "UserFeatureKeyName": "user_id",
            "HologresTableName": "recom_user_features_processed_holo_online",
            "UserSelectFields": "rids_count,sex,alladdfriendnum,allpayrosenum",
            "FeatureStore": "user"
          },
          "Features": []
        },
        {
          "FeatureDaoConf": {
            "AdapterType": "hologres",
            "HologresName": "holo-pai",
            "ItemFeatureKeyName": "item_id",
            "FeatureKey": "item:id",
            "HologresTableName": "recom_user_features_processed_holo_online",
            "ItemSelectFields": "rids_count as rids2_count,sex as guestsex,alladdfriendnum as alladdfriendnum2",
            "FeatureStore": "item"
          },
          "Features": []
        }
      ]
    }
  }
}

`FeatureLoadConfs/FeatureDaoConf` parameters

Parameter	Type	Required	Description
`AdapterType`	string	Yes	Set to `hologres`.
`HologresName`	string	Yes	The name of the Hologres instance as defined in `HologresConfs`. For example, `holo_info`.
`FeatureKey`	string	Yes	The lookup key. For example, `user:uid` looks up the `uid` field on the user side; `item:id` looks up the `id` field on the item side.
`UserFeatureKeyName`	string	Yes	The primary key field of the user feature table.
`ItemFeatureKeyName`	string	Yes	The primary key field of the item feature table.
`HologresTableName`	string	Yes	The name of the feature table in Hologres.
`UserSelectFields`	string	No	User features to retrieve. Use `*` for all, or a comma-separated list such as `feature1,feature2`.
`ItemSelectFields`	string	No	Item features to retrieve. Use `*` for all, or a comma-separated list such as `feature1,feature2`.
`FeatureStore`	string	Yes	Where to store the retrieved features. Valid values: `user` or `item`.
`CacheSize`	integer	No	Number of feature entries to cache locally. Default: `0` (no caching).
`CacheTime`	integer	No	Expiration time for cached entries, in seconds. Takes effect only when `CacheSize` is greater than `0`. Default: `3600`.

PAI-FeatureStore

For setup instructions, see FeatureStore overview.

Load all features from an entity

The following configuration retrieves all features of the user entity from the rank_v1 model:

{
  "FeatureConfs": {
    "scene_name": {
      "AsynLoadFeature": true,
      "FeatureLoadConfs": [
        {
          "FeatureDaoConf": {
            "AdapterType": "featurestore",
            "FeatureStoreName": "pairec-fs",
            "FeatureKey": "user:uid",
            "FeatureStoreModelName": "rank_v1",
            "FeatureStoreEntityName": "user",
            "FeatureStore": "user"
          }
        }
      ]
    }
  }
}

To load item features instead, set FeatureKey to item:id, FeatureStoreEntityName to item, and FeatureStore to item.

`FeatureLoadConfs/FeatureDaoConf` parameters

Parameter	Type	Required	Description
`AdapterType`	string	Yes	Set to `featurestore`.
`FeatureStoreName`	string	Yes	The name of the FeatureStore instance as defined in `FeatureStoreConfs`. For example, `pairec-fs`.
`FeatureKey`	string	Yes	The lookup key. For example, `user:uid` or `item:id`.
`FeatureStoreModelName`	string	Yes	The model feature name in PAI-FeatureStore.
`FeatureStoreEntityName`	string	Yes	The entity name in PAI-FeatureStore.
`FeatureStore`	string	Yes	Where to store the retrieved features. Valid values: `user` or `item`.
`CacheSize`	integer	No	Number of feature entries to cache locally. Default: `0` (no caching).
`CacheTime`	integer	No	Expiration time for cached entries, in seconds. Takes effect only when `CacheSize` is greater than `0`. Default: `3600`.

Load features from a specific feature view

To retrieve features from a named feature view rather than an entire entity, use FeatureStoreViewName. The following example retrieves all user features from the user_table_preprocess_all_feature_v1 view and a subset of item features from the item_table_preprocess_all_feature_v1 view:

{
  "FeatureConfs": {
    "scene_name": {
      "AsynLoadFeature": true,
      "FeatureLoadConfs": [
        {
          "FeatureDaoConf": {
            "AdapterType": "featurestore",
            "FeatureStoreName": "pairec-fs",
            "FeatureKey": "user:uid",
            "FeatureStoreViewName": "user_table_preprocess_all_feature_v1",
            "UserSelectFields": "*",
            "FeatureStore": "user"
          }
        },
        {
          "FeatureDaoConf": {
            "AdapterType": "featurestore",
            "FeatureStoreName": "pairec-fs",
            "FeatureKey": "item:id",
            "FeatureStoreViewName": "item_table_preprocess_all_feature_v1",
            "ItemSelectFields": "author,duration,category",
            "FeatureStore": "item"
          }
        }
      ]
    }
  }
}

Parameter	Type	Required	Description
`FeatureStoreViewName`	string	Yes	The name of the feature view.
`UserSelectFields`	string	No	User features to retrieve. Use `*` for all, or a comma-separated list such as `feature1,feature2`.
`ItemSelectFields`	string	No	Item features to retrieve. Use `*` for all, or a comma-separated list such as `feature1,feature2`.

Tablestore (OTS)

{
  "FeatureConfs": {
    "scene_name": {
      "AsynLoadFeature": true,
      "FeatureLoadConfs": [
        {
          "FeatureDaoConf": {
            "AdapterType": "tablestore",
            "TableStoreName": "tablestore_info",
            "FeatureKey": "user:uid",
            "UserFeatureKeyName": "uid",
            "TableStoreTableName": "",
            "UserSelectFields": "*",
            "FeatureStore": "user"
          },
          "Features": []
        },
        {
          "FeatureDaoConf": {
            "AdapterType": "tablestore",
            "TableStoreName": "tablestore_info",
            "FeatureKey": "item:id",
            "ItemFeatureKeyName": "item_id",
            "TableStoreTableName": "",
            "ItemSelectFields": "*",
            "FeatureStore": "item"
          },
          "Features": []
        }
      ]
    }
  }
}

`FeatureLoadConfs/FeatureDaoConf` parameters

Parameter	Type	Required	Description
`AdapterType`	string	Yes	Set to `tablestore`.
`TableStoreName`	string	Yes	The name of the Tablestore instance as defined in `TableStoreConfs`. For example, `tablestore_info`.
`FeatureKey`	string	Yes	The lookup key. For example, `user:uid` or `item:pair_id`.
`UserFeatureKeyName`	string	No	The primary key field of the user feature table.
`ItemFeatureKeyName`	string	No	The primary key field of the item feature table.
`TableStoreTableName`	string	Yes	The name of the feature table in Tablestore.
`UserSelectFields`	string	No	User features to retrieve. Use `*` for all, or a comma-separated list such as `feature1,feature2`.
`ItemSelectFields`	string	No	Item features to retrieve. Use `*` for all, or a comma-separated list such as `feature1,feature2`.
`FeatureStore`	string	Yes	Where to store the retrieved features. Valid values: `user` or `item`.
`CacheSize`	integer	No	Number of feature entries to cache locally. Default: `0` (no caching).
`CacheTime`	integer	No	Expiration time for cached entries, in seconds. Takes effect only when `CacheSize` is greater than `0`. Default: `3600`.

Redis

Redis supports two storage formats: key-value (KV) and HASH.

KV format: The value can be CSV (with a configurable delimiter) or JSON.
HASH format: Retrieves all or selected fields by name using UserSelectFields or ItemSelectFields.

KV format

In this example, user features are stored as CSV and item features as JSON. RedisValueDelimeter specifies the CSV separator.

{
  "FeatureConfs": {
    "scene_name": {
      "AsynLoadFeature": true,
      "FeatureLoadConfs": [
        {
          "FeatureDaoConf": {
            "AdapterType": "redis",
            "RedisName": "user_redis",
            "RedisPrefix": "UF_V2_",
            "FeatureKey": "user:uid",
            "FeatureStore": "user",
            "RedisDataType": "string",
            "RedisFieldType": "csv",
            "RedisValueDelimeter": ","
          },
          "Features": []
        },
        {
          "FeatureDaoConf": {
            "AdapterType": "redis",
            "RedisName": "item_redis",
            "RedisPrefix": "IF_V2_FM_",
            "FeatureKey": "item:id",
            "FeatureStore": "item",
            "RedisDataType": "string",
            "RedisFieldType": "json"
          },
          "Features": []
        }
      ]
    }
  }
}

HASH format

{
  "FeatureConfs": {
    "scene_name": {
      "AsynLoadFeature": true,
      "FeatureLoadConfs": [
        {
          "FeatureDaoConf": {
            "AdapterType": "redis",
            "RedisName": "user_redis",
            "RedisPrefix": "UF_V2_",
            "FeatureKey": "user:uid",
            "FeatureStore": "user",
            "RedisDataType": "hash",
            "UserSelectFields": "*"
          },
          "Features": []
        },
        {
          "FeatureDaoConf": {
            "AdapterType": "redis",
            "RedisName": "item_redis",
            "RedisPrefix": "IF_V2_FM_",
            "FeatureKey": "item:id",
            "FeatureStore": "item",
            "RedisDataType": "hash",
            "ItemSelectFields": "city,author,duration"
          },
          "Features": []
        }
      ]
    }
  }
}

`FeatureLoadConfs/FeatureDaoConf` parameters

Parameter	Type	Required	Description
`AdapterType`	string	Yes	Set to `redis`.
`RedisName`	string	Yes	The name of the Redis instance as defined in `RedisConfs`. For example, `redis_info`.
`RedisPrefix`	string	Yes	The key prefix.
`FeatureKey`	string	Yes	The lookup key. For example, `user:uid` or `item:pair_id`.
`FeatureStore`	string	Yes	Where to store the retrieved features. Valid values: `user` or `item`.
`RedisDataType`	string	Yes	The data storage format. Valid values: `string` or `hash`.
`RedisFieldType`	string	No	The field format when `RedisDataType` is `string`. Valid values: `csv` or `json`.
`RedisValueDelimeter`	string	No	The CSV separator. Takes effect only when `RedisFieldType` is `csv`.
`UserSelectFields`	string	No	User features to retrieve. Use `*` for all, or a comma-separated list such as `feature1,feature2`. Takes effect only when `RedisDataType` is `hash`.
`ItemSelectFields`	string	No	Item features to retrieve. Use `*` for all, or a comma-separated list such as `feature1,feature2`. Takes effect only when `RedisDataType` is `hash`.
`CacheSize`	integer	No	Number of feature entries to cache locally. Default: `0` (no caching).
`CacheTime`	integer	No	Expiration time for cached entries, in seconds. Takes effect only when `CacheSize` is greater than `0`. Default: `3600`.

Feature transformation

After features are loaded, you can derive new features or recombine existing ones using three transformation types:

`FeatureType`	Description
`new_feature`	Generates a new feature from scratch or from an expression.
`raw_feature`	Creates a renamed copy of an existing feature.
`compose_feature`	Combines multiple existing features into a single composite feature.

Feature transformation configurations are defined inline within each FeatureLoadConf entry, alongside FeatureDaoConf.

new_feature

Use new_feature to generate features that don't exist in the data source — time-based values, random numbers, constants, or expression results.

Time and random values

{ "FeatureType": "new_feature", "FeatureName": "day_h", "Normalizer": "hour_in_day", "FeatureStore": "user" }

{ "FeatureType": "new_feature", "FeatureName": "week_day", "Normalizer": "weekday", "FeatureStore": "user" }

{ "FeatureType": "new_feature", "FeatureName": "rand_int_v", "Normalizer": "random", "FeatureStore": "user" }

hour_in_day and weekday generate real-time values based on the current system time. random generates an integer in the range [0, 100).

Constant value

The following generates a feature named alg with the static value ALRC:

{
  "FeatureType": "new_feature",
  "FeatureStore": "user",
  "Normalizer": "const_value",
  "FeatureValue": "ALRC",
  "FeatureName": "alg"
}

Expression (recommended)

Use Normalizer: "expr" for expression-based features. This method uses the expr library and offers more flexible syntax and better performance than the older expression method.

Reference item-side features with the item. prefix and user-side features with the user. prefix. Use currentTime for the current Unix timestamp in seconds.

The following generates a Boolean feature is_retarget (represented as 1 or 0):

{
  "FeatureType": "new_feature",
  "FeatureStore": "item",
  "Normalizer": "expr",
  "Expression": "item.recall_name in ['retarget_u2i','realtime_retarget_click']",
  "FeatureName": "is_retarget"
}

To combine user-side and item-side features in the same expression:

{
  "FeatureType": "new_feature",
  "FeatureStore": "item",
  "Normalizer": "expr",
  "Expression": "user.user_index - item.index",
  "FeatureName": "index_delta"
}

For expression syntax, see the expr language definition.

Expression (legacy)

Normalizer: "expression" uses the govaluate library. Use FeatureSource to specify which feature value to pass to the expression. If the expression references multiple item properties, omit FeatureSource — all item properties are passed automatically.

{
  "FeatureType": "new_feature",
  "FeatureStore": "item",
  "FeatureSource": "item:recall_name",
  "Normalizer": "expression",
  "Expression": "recall_name in ('retarget_u2i','realtime_retarget_click')",
  "FeatureName": "is_retarget"
}

For expression syntax, see the govaluate manual.

raw_feature

raw_feature copies an existing feature under a new name. Set RemoveFeatureSource to true to delete the original after copying.

The following renames the user's age feature to age_v2:

{
  "FeatureType": "raw_feature",
  "FeatureStore": "user",
  "FeatureSource": "user:age",
  "RemoveFeatureSource": true,
  "FeatureName": "age_v2"
}

Use the user: prefix for user-side features and the item: prefix for item-side features in FeatureSource.

compose_feature

compose_feature joins multiple feature values with an underscore (_) to create a composite feature.

The following creates item_author by joining user:category and item:author. If user:category is category1 and item:author is author1, the result is category1_author1:

{
  "FeatureType": "compose_feature",
  "FeatureStore": "item",
  "FeatureSource": "user:category,item:author",
  "FeatureName": "item_author"
}

The expr method for new_feature provides a more flexible alternative for building composite features.

Built-in expression functions

The following functions are available in both expression and expr expressions.

String functions

Function	Signature	Description	Example
`getString`	`getString(a, b)`	Returns `a` if non-empty; otherwise returns `b`.	`getString(user.city, "unknown")`
`trim`	`trim(str, cutset)`	Removes all leading and trailing characters in `cutset` from `str`.	`trim(" hello ", " ")` returns `"hello"`
`trimPrefix`	`trimPrefix(str, cutset)`	Removes leading characters in `cutset` from `str`.	`trimPrefix("UF_uid", "UF_")` returns `"uid"`
`replace`	`replace(str, old, new)`	Replaces all occurrences of `old` with `new` in `str`.	`replace("a-b-c", "-", "_")` returns `"a_b_c"`

Math functions

Function	Signature	Description	Example
`round`	`round(number)`	Rounds to the nearest integer.	`round(123.5)` returns `124.0`
`round`	`round(number, places)`	Truncates to the specified number of decimal places.	`round(123.456, 2)` returns `123.45`
`hash32`	`hash32(str)`	Computes a 32-bit hash using murmur3.Sum32.	`hash32(item.id)`
`log`	`log(number)`	Natural logarithm (base e).	`log(2.718)`
`log10`	`log10(number)`	Common logarithm (base 10).	`log10(100)` returns `2.0`
`log2`	`log2(number)`	Binary logarithm (base 2).	`log2(8)` returns `3.0`
`pow`	`pow(base, exponent)`	Raises `base` to the power of `exponent`.	`pow(2, 10)` returns `1024.0`

Geospatial functions

Function	Signature	Description
`s2CellID`	`s2CellID(lat, lng)` `s2CellID(lat, lng, level)`	Returns the S2 Cell ID (`int`) for the given coordinates. `level` controls precision (higher = smaller cell). Default level: `15`.
`s2CellNeighbors`	`s2CellNeighbors(lat, lng)` `s2CellNeighbors(lat, lng, level)`	Returns a list of S2 Cell IDs (`[]int`) for the given coordinates and all 8 adjacent cells — 9 IDs total.
`geoHash`	`geoHash(lat, lng)` `geoHash(lat, lng, precision)`	Encodes coordinates as a Geohash string. Default precision: `6`.
`geoHashWithNeighbors`	`geoHashWithNeighbors(lat, lng)` `geoHashWithNeighbors(lat, lng, precision)`	Returns Geohash strings for the given coordinates and all 8 adjacent areas — 9 strings total.
`haversine`	`haversine(lng1, lat1, lng2, lat2)`	Calculates the spherical distance between two points using the Haversine formula. Returns `float64` in kilometers.
`sphereDistance`	`sphereDistance(lng1, lat1, lng2, lat2)`	Calculates the spherical distance between two points using the spherical law of cosines. Returns `float64` in kilometers.