E-commerce industry

Updated at:
Copy as MD

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:

TablePurpose
Item tableAll items eligible for recommendation in the current scene
User tableAll users who have recently registered on the system
Behavior tableRecent 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.

Important

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.

FieldData typeRequiredDescriptionValid valuesNotesExample
item_idstringRequiredUnique item IDCustom (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_typestringRequiredItem typeimage, article, video, shortvideo, item, recipe, audioUploaded 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
statusstringRequiredWhether the item can be recommended0, 11: can be recommended. 0: cannot be recommended. Status changes take effect immediately.1
scene_idstringRequiredScene IDCustomUse 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_timestringRequiredItem release time (UNIX timestamp, accurate to the second)CustomUsed to determine whether the item is the latest. Required if you have high timeliness requirements.1520327038
expire_timestringOptionalItem expiration time (UNIX timestamp, accurate to the second)CustomIf 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_timestringOptionalTime the item information was last modified (UNIX timestamp, accurate to the second)CustomSet 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
titlestringRecommendedItem titleCustomUsed for in-depth semantic analysis. Missing values reduce algorithm accuracy.CHANEL-Style Lady Dress
weightstringRecommendedItem weight100, 1100: 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_levelstringRecommendedCategory level (e.g., level 3)CustomMust match the depth of category_path. A mismatch affects discretization.3
category_pathstringRecommendedCategory path, with levels separated by underscores (_)CustomA path can contain multiple levels. Do not use commas (,) or colons (:). Used in discretization policies.12_1024_56
tagsstringRecommendedItem tags, separated by commas (,)CustomDescribe 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_idstringRecommendedBrand IDCustomNon-real-time data is acceptable.—
shop_idstringRecommendedStore IDCustomNon-real-time data is acceptable.—
share_cntstringOptionalNumber of shares in the past monthCustomIf 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_cntstringOptionalNumber of favorites in the past monthCustomNon-real-time data is acceptable.566
pv_cntstringOptionalNumber of exposures in the past monthCustomNon-real-time data is acceptable.10292
origin_pricestringOptionalOriginal price in USD. Convert to USD if using another currency.CustomNon-real-time data is acceptable.1000 (USD 1,000)
cur_pricestringOptionalDiscounted price in USD. Convert to USD if using another currency.CustomNon-real-time data is acceptable.900 (USD 900)
buy_cntstringOptionalMonthly sales volume on the platformCustomIf 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_cntstringOptionalMonthly sales volume on TaobaoCustomNon-real-time data is acceptable.10000
comment_cntstringOptionalNumber of reviewsCustomNon-real-time data is acceptable.1000
source_idstringOptionalPlatform used to launch the item to the sceneCustomFor example: 1 = Taobao, 2 = Tmall.1
add_feestringOptionalAdditional fees for the itemCustom0 = free shipping. 1 = chargeable shipping. Or specify the exact amount in cents.0
featuresstringOptionalItem characteristics (string values)CustomSeparate with commas (,). Values must be descriptive.—
num_featuresstringOptionalItem characteristics (numerical values)CustomSeparate 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.

FieldData typeRequiredDescriptionValid valuesNotesExample
user_idstringRequired for logged-in usersUnique user IDCustomRequired for registered users. Uniquely identifies a user.1234567
imeistringRequired for users who have not logged inDevice ID. For Android: MD5 hash of IMEI (International Mobile Equipment Identity). For iOS: MD5 hash of IDFA (Identifier for Advertisers).CustomRequired 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_typestringOptionalUser registration type1, 2, 3, 41: app account. 2: mobile phone number. 3: WeChat account. 4: other.2
third_user_namestringOptionalThird-party usernameCustom—jack
third_user_typestringOptionalThird-party platform nameCustom—wechat
phone_md5stringOptionalMD5 hash of the user's mobile numberCustom—d41d8cd98f00b204e9800998ecf8****
genderstringOptionalGendermale, female, unknown—male
agestringOptionalAgeCustom—22
age_groupstringOptionalAge groupCustom—20-25
countrystringOptionalCountry codeCustomUse an ISO 3166-1 alpha-3 code.CHN
citystringOptionalCity nameCustom—Hangzhou
ipstringOptionalLast login IP addressCustom—202.113.XX.XX
device_modelstringOptionalDevice modelCustom—iphoneX
tagsstringOptionalUser tags, separated by commas (,)CustomUse tags to describe the user.football,fitness,outdoor
sourcestringOptionalUser acquisition sourceCustom—Toutiao
contentstringOptionalUser descriptionCustom——
featuresstringOptionalUser characteristics (string values), such as customer portrait dataCustomSeparate with commas (,).—
num_featuresstringOptionalUser characteristics (numerical values)CustomSeparate with commas (,). The number of commas must be the same across all users.—
register_timestringOptionalRegistration time (UNIX timestamp, accurate to the second)Custom—1520007038
last_login_timestringOptionalLast login time (UNIX timestamp, accurate to the second)Custom—1520017038
last_modify_timestringOptionalTime 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.

Important

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.

FieldData typeRequiredDescriptionValid valuesNotesExample
item_idstringRequiredItem IDCustomMust match the item_id in the item table.34513
item_typestringRequiredItem typeimage, article, video, shortvideo, item, recipe, audioMust match the item_type in the item table.article
bhv_typestringRequiredBehavior typeexpose, click, buy, cart, evaluate (and others: like, unlike, comment, collect, stay, dislike)See the Behavior types table below.expose
trace_idstringRequiredRequest tracking IDAlibaba, selfholdAlibaba: 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_infostringRequiredRequest tracking informationReturned from the Recommend API responseIf 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_idstringRequiredScene IDCustomThe 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_valuestringRequiredBehavior detailsCustomclick: 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_idstringRequired for logged-in usersUser IDCustomMust match the value in the user table. Leave blank for users who have not logged in.1234567
imeistringRequired for users who have not logged inDevice ID. For Android: MD5 hash of IMEI. For iOS: MD5 hash of IDFA.CustomRequired for users who have not registered. Must be a 32-character MD5 hash. If invalid, only the exposure blocking feature is retained.e2fcdb0f4dce45e35fe2823d7973****
bhv_timestringOptionalTime the behavior occurred (UNIX timestamp, accurate to the second)CustomSet to the time the user performed the action.1520327038
platformstringOptionalClient platformCustomiOS, Android, or H5.iOS
app_versionstringOptionalApp version numberCustom—4.1.10
net_typestringOptionalNetwork typeCustom2G, 3G, 4G, or WIFI.4G
ipstringOptionalClient IP addressCustom—234.45.XX.XX
loginstringOptionalWhether the user has logged in0, 10: not logged in. 1: logged in.1
report_srcstringOptionalReport source1, 21: server. 2: client.2
device_modelstringOptionalDevice modelCustom—iphoneX
longitudestringOptionalLongitudeCustom—128.4
latitudestringOptionalLatitudeCustom—78.1
module_idstringOptionalModule IDCustom—114
page_idstringOptionalPage IDCustom—4
positionstringOptionalItem positionCustom—5
message_idstringOptionalUnique identifier for the behavior entryCustomIf 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.Behaviorbhv_typebhv_valueNotes
1ExposeexposeLeave blankRequired. The behavior table must include expose entries. The number of expose entries must exceed the number of click entries.
2Clickclick1Required. The behavior table must include click entries.
3LikelikeLeave blank—
4DislikeunlikeLeave blank—
5ReviewcommentLeave blank—
6FavoritecollectLeave blank—
7StaystayDurationUnits are flexible, but must be consistent across all entries.
8Add to cartcartnumber,unit_priceUnit price in USD, accurate to the cent. Example: 1,10000.
9Purchasebuynumber,unit_priceUnit 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.
10EvaluateevaluateDiscrete integers in ascending or descending orderFor star ratings (1–5), use ascending order where 5 represents the most positive review. Ascending order must be positively correlated with positive feedback.
11Negative feedbackdislike—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
;