E-commerce industry
This topic describes the data specifications for the e-commerce industry. You must follow these specifications when uploading historical data and real-time data to AIRec (Artificial Intelligence Recommendation).
Data overview
To use AIRec for e-commerce recommendations, prepare three data tables:
| Table | Purpose |
|---|---|
| Item table | All items eligible for recommendation in the current scene |
| User table | All users who have recently registered on the system |
| Behavior table | Recent user behavior data in the current scene |
Behavior data: Provide behavior data from the last 1–2 weeks. If no historical data is available — for example, because the scene is new or behavior data cannot be exported — use the test data provided by AIRec. Expect recommendation quality to be limited for the first two weeks; accuracy improves as data accumulates.
Optional fields: Fill in as many optional fields as possible. More complete data produces better recommendations. If an optional field is left blank, the system uses its default value.
Fields marked as Required in the tables below must be specified. Fields marked as Required and Recommended have significant impacts on recommendation results. If you use a MaxCompute table to upload historical data, optional fields may be left blank, but the table must include all fields. For the CREATE TABLE statements, see CREATE TABLE statements.
Table schema
Item table
The item table contains all items that can be recommended in the current scene. Items are subject to a quota limit — deduplicate items before uploading. The item_id and item_type fields together uniquely identify an item.
| Field | Data type | Required | Description | Valid values | Notes | Example |
|---|---|---|---|---|---|---|
| item_id | string | Required | Unique item ID | Custom (letters and digits only) | Combined with item_type to uniquely identify an item. Maximum 50 characters. Record all reported item IDs for later use. | 34513 |
| item_type | string | Required | Item type | image, article, video, shortvideo, item, recipe, audio | Uploaded data must match the specified item type. To use a type not in this list, map it to one of these values. For multi-type arrangements, see Mixed sorting policies. Contact technical support for additional types. | article |
| status | string | Required | Whether the item can be recommended | 0, 1 | 1: can be recommended. 0: cannot be recommended. Status changes take effect immediately. | 1 |
| scene_id | string | Required | Scene ID | Custom | Use an acronym or alphanumeric combination. Do not use colons (:). Do not use -102 (reserved by the system). If only one scene exists, set to 1. Separate multiple scene IDs with commas (,). See Use scene IDs. | sy101,gwc102 (sy101 = homepage; gwc102 = shopping cart page) |
| pub_time | string | Required | Item release time (UNIX timestamp, accurate to the second) | Custom | Used to determine whether the item is the latest. Required if you have high timeliness requirements. | 1520327038 |
| expire_time | string | Optional | Item expiration time (UNIX timestamp, accurate to the second) | Custom | If the server time exceeds this value, the item is expired and not recommended. If all items expire, the service cannot start. Leave blank for no expiration. If started via data source import, this field cannot be blank — set it to a timestamp far in the future. | 1520327038 |
| last_modify_time | string | Optional | Time the item information was last modified (UNIX timestamp, accurate to the second) | Custom | Set this when making major updates to a released item with high timeliness requirements. Functions similarly to pub_time — both are used to identify new items. | 1520327038 |
| title | string | Recommended | Item title | Custom | Used for in-depth semantic analysis. Missing values reduce algorithm accuracy. | CHANEL-Style Lady Dress |
| weight | string | Recommended | Item weight | 100, 1 | 100: weighted (more likely to be recommended). 1: unweighted. Other values are invalid. Keep weighted items at or below 10% of the total item count. Weighting affects model training — set with care. | 1 |
| category_level | string | Recommended | Category level (e.g., level 3) | Custom | Must match the depth of category_path. A mismatch affects discretization. | 3 |
| category_path | string | Recommended | Category path, with levels separated by underscores (_) | Custom | A path can contain multiple levels. Do not use commas (,) or colons (:). Used in discretization policies. | 12_1024_56 |
| tags | string | Recommended | Item tags, separated by commas (,) | Custom | Describe item characteristics. The algorithm uses tags for feature analysis. Maximum 100 tags per item; no more than 50,000 tags per tag pool. If tags are confidential, convert them to digit-based codes before uploading. | famous actor,sports |
| brand_id | string | Recommended | Brand ID | Custom | Non-real-time data is acceptable. | — |
| shop_id | string | Recommended | Store ID | Custom | Non-real-time data is acceptable. | — |
| share_cnt | string | Optional | Number of shares in the past month | Custom | If behavior data is sparse at service start, supplement with data from other scenes. Non-real-time data is acceptable. If the maintenance cost of this field is high after the model becomes stable, you can process it at a low priority. | 156 |
| collect_cnt | string | Optional | Number of favorites in the past month | Custom | Non-real-time data is acceptable. | 566 |
| pv_cnt | string | Optional | Number of exposures in the past month | Custom | Non-real-time data is acceptable. | 10292 |
| origin_price | string | Optional | Original price in USD. Convert to USD if using another currency. | Custom | Non-real-time data is acceptable. | 1000 (USD 1,000) |
| cur_price | string | Optional | Discounted price in USD. Convert to USD if using another currency. | Custom | Non-real-time data is acceptable. | 900 (USD 900) |
| buy_cnt | string | Optional | Monthly sales volume on the platform | Custom | If behavior data is sparse at service start, supplement with data from other scenes. Non-real-time data is acceptable. If the maintenance cost of this field is high after the model becomes stable, you can process it at a low priority. | 10 |
| source_buy_cnt | string | Optional | Monthly sales volume on Taobao | Custom | Non-real-time data is acceptable. | 10000 |
| comment_cnt | string | Optional | Number of reviews | Custom | Non-real-time data is acceptable. | 1000 |
| source_id | string | Optional | Platform used to launch the item to the scene | Custom | For example: 1 = Taobao, 2 = Tmall. | 1 |
| add_fee | string | Optional | Additional fees for the item | Custom | 0 = free shipping. 1 = chargeable shipping. Or specify the exact amount in cents. | 0 |
| features | string | Optional | Item characteristics (string values) | Custom | Separate with commas (,). Values must be descriptive. | — |
| num_features | string | Optional | Item characteristics (numerical values) | Custom | Separate with commas (,). The number of commas must be the same across all items. | — |
User table
The user table contains all users who have recently registered on the system. Users are subject to a quota limit — deduplicate users before uploading.
Use user_id to identify logged-in users and imei to identify users who have not logged in. When requesting recommendation results, specify the user's unique identifier — otherwise, personalized recommendations cannot be generated.
| Field | Data type | Required | Description | Valid values | Notes | Example |
|---|---|---|---|---|---|---|
| user_id | string | Required for logged-in users | Unique user ID | Custom | Required for registered users. Uniquely identifies a user. | 1234567 |
| imei | string | Required for users who have not logged in | Device ID. For Android: MD5 hash of IMEI (International Mobile Equipment Identity). For iOS: MD5 hash of IDFA (Identifier for Advertisers). | Custom | Required for users who have not registered. Must be a 32-character MD5 hash. If the MAC address or device number is invalid, internal user portrait data cannot be used — only the exposure blocking feature is retained. | 74f25e604e1a9dde7471fe2e25ae54d0 |
| user_id_type | string | Optional | User registration type | 1, 2, 3, 4 | 1: app account. 2: mobile phone number. 3: WeChat account. 4: other. | 2 |
| third_user_name | string | Optional | Third-party username | Custom | — | jack |
| third_user_type | string | Optional | Third-party platform name | Custom | — | wechat |
| phone_md5 | string | Optional | MD5 hash of the user's mobile number | Custom | — | d41d8cd98f00b204e9800998ecf8**** |
| gender | string | Optional | Gender | male, female, unknown | — | male |
| age | string | Optional | Age | Custom | — | 22 |
| age_group | string | Optional | Age group | Custom | — | 20-25 |
| country | string | Optional | Country code | Custom | Use an ISO 3166-1 alpha-3 code. | CHN |
| city | string | Optional | City name | Custom | — | Hangzhou |
| ip | string | Optional | Last login IP address | Custom | — | 202.113.XX.XX |
| device_model | string | Optional | Device model | Custom | — | iphoneX |
| tags | string | Optional | User tags, separated by commas (,) | Custom | Use tags to describe the user. | football,fitness,outdoor |
| source | string | Optional | User acquisition source | Custom | — | Toutiao |
| content | string | Optional | User description | Custom | — | — |
| features | string | Optional | User characteristics (string values), such as customer portrait data | Custom | Separate with commas (,). | — |
| num_features | string | Optional | User characteristics (numerical values) | Custom | Separate with commas (,). The number of commas must be the same across all users. | — |
| register_time | string | Optional | Registration time (UNIX timestamp, accurate to the second) | Custom | — | 1520007038 |
| last_login_time | string | Optional | Last login time (UNIX timestamp, accurate to the second) | Custom | — | 1520017038 |
| last_modify_time | string | Optional | Time the user information was last modified (UNIX timestamp, accurate to the second) | Custom | — | 1520327038 |
Behavior table
The behavior table contains recent user behavior data in the current scene. Provide data from the last 1–2 weeks.
The behavior types you upload directly determine what the recommendation model optimizes for. Uploading only click data makes click-through rate (CTR) the primary optimization target. Uploading consumption data — such as add-to-cart and purchase events — also optimizes for those behaviors, with CTR remaining the main goal. If you cannot identify the scene where an add-to-cart or purchase behavior occurred, set scene_id to -102.
Expose and click requirements: The behavior table must include both expose and click entries. The number of click entries must be less than the number of expose entries. If click entries exceed expose entries, the system flags the data as abnormal and the service cannot start.
| Field | Data type | Required | Description | Valid values | Notes | Example |
|---|---|---|---|---|---|---|
| item_id | string | Required | Item ID | Custom | Must match the item_id in the item table. | 34513 |
| item_type | string | Required | Item type | image, article, video, shortvideo, item, recipe, audio | Must match the item_type in the item table. | article |
| bhv_type | string | Required | Behavior type | expose, click, buy, cart, evaluate (and others: like, unlike, comment, collect, stay, dislike) | See the Behavior types table below. | expose |
| trace_id | string | Required | Request tracking ID | Alibaba, selfhold | Alibaba: behavior generated by an AIRec recommendation. selfhold: behavior from a self-developed or self-operated recommendation system. Used to generate analytical reports and compare results in the console. | Alibaba |
| trace_info | string | Required | Request tracking information | Returned from the Recommend API response | If trace_id is selfhold, set to 1. If trace_id is Alibaba, use the value returned in the recommendation result. | 1007.5911.12351.1002000::::: |
| scene_id | string | Required | Scene ID | Custom | The scene where the behavior occurred. Only one scene ID per entry. The value must be one of the scene IDs in the item table. If the scene cannot be traced, set to -102. See Use scene IDs. | a1001 |
| bhv_value | string | Required | Behavior details | Custom | click: set to 1. expose: leave blank or set per your business requirements. cart/buy: format is number,unit_price (unit price in USD, accurate to the cent). evaluate: discrete integers in ascending or descending order. For other behaviors, contact technical support. | 1 |
| user_id | string | Required for logged-in users | User ID | Custom | Must match the value in the user table. Leave blank for users who have not logged in. | 1234567 |
| imei | string | Required for users who have not logged in | Device ID. For Android: MD5 hash of IMEI. For iOS: MD5 hash of IDFA. | Custom | Required for users who have not registered. Must be a 32-character MD5 hash. If invalid, only the exposure blocking feature is retained. | e2fcdb0f4dce45e35fe2823d7973**** |
| bhv_time | string | Optional | Time the behavior occurred (UNIX timestamp, accurate to the second) | Custom | Set to the time the user performed the action. | 1520327038 |
| platform | string | Optional | Client platform | Custom | iOS, Android, or H5. | iOS |
| app_version | string | Optional | App version number | Custom | — | 4.1.10 |
| net_type | string | Optional | Network type | Custom | 2G, 3G, 4G, or WIFI. | 4G |
| ip | string | Optional | Client IP address | Custom | — | 234.45.XX.XX |
| login | string | Optional | Whether the user has logged in | 0, 1 | 0: not logged in. 1: logged in. | 1 |
| report_src | string | Optional | Report source | 1, 2 | 1: server. 2: client. | 2 |
| device_model | string | Optional | Device model | Custom | — | iphoneX |
| longitude | string | Optional | Longitude | Custom | — | 128.4 |
| latitude | string | Optional | Latitude | Custom | — | 78.1 |
| module_id | string | Optional | Module ID | Custom | — | 114 |
| page_id | string | Optional | Page ID | Custom | — | 4 |
| position | string | Optional | Item position | Custom | — | 5 |
| message_id | string | Optional | Unique identifier for the behavior entry | Custom | If not set, the system deduplicates using the combination of item_id, item_type, user_id, imei, bhv_type, and bhv_time. | 5 |
Behavior types
The following behavior types are supported for the e-commerce industry. For additional behavior types, contact technical support.
| No. | Behavior | bhv_type | bhv_value | Notes |
|---|---|---|---|---|
| 1 | Expose | expose | Leave blank | Required. The behavior table must include expose entries. The number of expose entries must exceed the number of click entries. |
| 2 | Click | click | 1 | Required. The behavior table must include click entries. |
| 3 | Like | like | Leave blank | — |
| 4 | Dislike | unlike | Leave blank | — |
| 5 | Review | comment | Leave blank | — |
| 6 | Favorite | collect | Leave blank | — |
| 7 | Stay | stay | Duration | Units are flexible, but must be consistent across all entries. |
| 8 | Add to cart | cart | number,unit_price | Unit price in USD, accurate to the cent. Example: 1,10000. |
| 9 | Purchase | buy | number,unit_price | Unit price in USD, accurate to the cent. Example: 1,10000. One buy entry corresponds to one item_id. Split orders with multiple items into separate entries. |
| 10 | Evaluate | evaluate | Discrete integers in ascending or descending order | For star ratings (1–5), use ascending order where 5 represents the most positive review. Ascending order must be positively correlated with positive feedback. |
| 11 | Negative feedback | dislike | — | See Negative feedback. |
CREATE TABLE statements
If you use MaxCompute to upload data, use the following CREATE TABLE statements.
--- Create a behavior table for the e-commerce industry.
DROP TABLE IF EXISTS behavior_table;
CREATE TABLE IF NOT EXISTS `behavior_table`
(
trace_id STRING COMMENT "Request tracking ID"
,trace_info STRING COMMENT "Request tracking information"
,platform STRING COMMENT "Client platform"
,device_model STRING COMMENT "Device model"
,imei STRING COMMENT "Device ID"
,app_version STRING COMMENT "App version number"
,net_type STRING COMMENT "Network type"
,longitude STRING COMMENT "Longitude"
,latitude STRING COMMENT "Latitude"
,ip STRING COMMENT "Client IP address"
,login STRING COMMENT "Whether the user has logged on"
,report_src STRING COMMENT "Source of the report"
,scene_id STRING COMMENT "Scene ID"
,user_id STRING COMMENT "User ID"
,item_id STRING COMMENT "Item ID"
,item_type STRING COMMENT "Type of the item"
,module_id STRING COMMENT "Module ID"
,page_id STRING COMMENT "Page ID"
,position STRING COMMENT "Position of the item"
,bhv_type STRING COMMENT "Behavior type"
,bhv_value STRING COMMENT "Behavior details"
,bhv_time STRING COMMENT "Time at which the behavior occurs"
)
PARTITIONED BY
(
ds STRING
)
LIFECYCLE 30
;
--- Create a user table for the e-commerce industry.
DROP TABLE IF EXISTS user_table;
CREATE TABLE IF NOT EXISTS `user_table`
(
user_id STRING COMMENT "Unique ID of the user"
,user_id_type STRING COMMENT "Registration type of the user"
,third_user_name STRING COMMENT "Name of the third-party user"
,third_user_type STRING COMMENT "Name of the third-party platform"
,phone_md5 STRING COMMENT "MD5 hash value of the mobile phone number of the user"
,imei STRING COMMENT "Device ID of the user"
,content STRING COMMENT "User content"
,gender STRING COMMENT "Gender"
,age STRING COMMENT "Age"
,age_group STRING COMMENT "Age group"
,country STRING COMMENT "Country"
,city STRING COMMENT "City"
,ip STRING COMMENT "Last logon IP address"
,device_model STRING COMMENT "Device model"
,register_time STRING COMMENT "Registration time"
,last_login_time STRING COMMENT "Last logon time"
,last_modify_time STRING COMMENT "Time at which the user information was last modified"
,tags STRING COMMENT "User tags"
,source STRING COMMENT "Source of the user"
,features STRING COMMENT "Additional user characteristics, which are strings"
,num_features STRING COMMENT "Additional user characteristics, which are numerical values"
)
PARTITIONED BY
(
ds STRING
)
LIFECYCLE 30
;
--- Create an item table for the e-commerce industry.
DROP TABLE IF EXISTS item_table;
CREATE TABLE IF NOT EXISTS `item_table`
(
scene_id STRING COMMENT "Scene ID"
,item_id STRING COMMENT "Unique ID of the item"
,item_type STRING COMMENT "Type of the item"
,category_level STRING COMMENT "Category level"
,category_path STRING COMMENT "Category path"
,title STRING COMMENT "Item title"
,content STRING COMMENT "Body part of the item"
,pub_time STRING COMMENT "Release time"
,tags STRING COMMENT "Tags"
,share_cnt STRING COMMENT "Number of shares"
,collect_cnt STRING COMMENT "Number of favorites"
,pv_cnt STRING COMMENT "Number of exposures"
,status STRING COMMENT "Whether the item can be recommended"
,expire_time STRING COMMENT "Time at which the item expires"
,last_modify_time STRING COMMENT "Time at which the item information was last modified"
,origin_price STRING COMMENT "Original price"
,cur_price STRING COMMENT "Price after a discount"
,buy_cnt STRING COMMENT "Monthly sales volume on the platform"
,source_buy_cnt STRING COMMENT "Monthly sales volume on Taobao"
,comment_cnt STRING COMMENT "Number of reviews"
,brand_id STRING COMMENT "Brand ID"
,shop_id STRING COMMENT "Store ID"
,source_id STRING COMMENT "Source of the item"
,add_fee STRING COMMENT "Additional fees"
,features STRING COMMENT "Additional user characteristics, which are strings"
,num_features STRING COMMENT "Additional user characteristics, which are numerical values"
,weight STRING COMMENT "Weight of the item, default value: 1"
)
PARTITIONED BY
(
ds STRING
)
LIFECYCLE 30
;