Data access
1. Scene ID usage and purpose
Example: An item table contains item A withitem_id=1and a scene ID field value of1001,1002. The behavior table has two records for this item: one withitem_id=1,scene_id=1001,bhv_type=clickand another withitem_id=1,scene_id=1002,bhv_type=expose.
A scene represents a specific context or placement for an item, acting as a form of categorization. If you do not have multiple scenes, you can leave the scene_id field empty. For more information about how to implement event tracking for a scene id, see the relevant section in Event Tracking.
An item can be displayed in multiple scenes. To specify this, list the scene ids in the scene_id field, separated by commas.
If you are querying for recommendations in a specific context, include the relevant ID in the scene_id parameter. If you do not use multiple scenes, you do not need to populate this parameter. For details, see Obtain Recommendation Results.
If a query includes1001, the corresponding item might be recalled (whether the item is recommended depends on the algorithm model). However, if the query includes1003, this item will never be recalled.
2. Confirming data upload
A return value of true from the SDK indicates that the message was sent successfully. To confirm that the data was processed correctly, use features such as update record queries and data table queries. For more information, see Basic Settings - Data Source - Data and Record Query.
3. Category field usage
Reporting categories accurately improves recommendation performance and enables features like discretization.
A category is a multi-level classification for items. In AIRec, categories are primarily used for discretization but are also considered as features during model ranking, which helps improve algorithm performance.
The use of categories depends on your business logic. If you do not require discretization, you can leave this field empty. For information on how to use categories, see the category-related field descriptions in Data Specifications. For implementation details, see Event Tracking Guide. For more on the discretization feature, see Improve Recommendation Diversity with Instance Operation Strategies.
4. Testing the SDK with sample data
AIRec provides sample full data that you can use for testing. You can download this data to start your instance and quickly test SDK functionalities like data push and queries. After testing, you can replace the sample data by creating a new data version of your full data, or by pushing incremental data to overwrite the test records.
5. Configuring the tag field
For example, an e-commerce app maintains a tag pool with terms like "red", "yellow", "black", "casual", and "formal" to define product attributes and user preferences.
The tag fields in the user and item tables are directly related.
All tags for users and items must come from a single tag pool. The total number of unique tags in this pool should not exceed 50,000.
The tag field defines a profile for a user or an item. These tags can be added manually by your algorithm or operations teams, or they can be selected by users during registration. The AIRec algorithm uses tags as an input for model training. Well-structured tags improve algorithm performance.
If a user's tags are "black" and "formal", AIRec is more likely to recommend items with these same tags to that user. This creates a positive feedback loop.
6. The add and update operations
The add operation creates a new data record, while the update operation modifies an existing one.
Use the add operation to insert a new data record. If a record with the same primary key (item_id and item_type) already exists, it will be replaced. When adding a record, you must provide the primary key and all other fields.
Use the update operation to modify an existing data record. You only need to provide the primary key (item_id and item_type) and the fields you wish to change; other fields can be omitted. Using update on a non-existent record can lead to data loss and unexpected issues, so do not use update as a substitute for add.
7. Tag data format
Separate multiple tags with a comma. A single item can have a maximum of 100 tags. We recommend keeping the total number of unique tags in your tag pool under 50,000.
8. The feature and feature_num fields
feature: A string-type field for descriptive item characteristics.
feature_num: A numeric-type field for item characteristics. You can pass custom features into these two fields.
9. Handling unavailable item_type values
The currently supported types are: image, article, video, shortvideo, item, recipe, and audio.
If your desired type, such as "collection", is not on the list, you can map it to an existing type that you are not using. For example, if you do not use the audio type, you can use audio to represent "collection".
10. The traceInfo parameter
① What is traceInfo? It is tracing information for the recommendation pipeline.
② Where do I get it? You receive it in the recommendation results when you call AIRec through the server-side SDK.
③ How do I use it? When a user interacts with a recommended item, you must include the original traceInfo string from the recommendation response when you report that user's behavior to the behavior table.
The traceInfo is mainly used by AIRec algorithm engineers for model tuning and troubleshooting. For example, a recommendation result record contains the following fields: traceId (e.g., Alibaba), itemId (e.g., 34), itemType (e.g., image), traceInfo (the complete tracing information string, including recall strategies, trigger information, and other context), matchInfo (e.g., hot_common), weight (e.g., 1), and position (e.g., 0). The value of the traceInfo field is what you must pass back as the traceInfo value when you report behavioral data.
11. Positive and negative behavioral data
Positive behavioral data refers to user actions that indicate interest, such as clicks, likes, and purchases. Click data is mandatory for initialization.
Negative behavioral data primarily refers to an exposure. If a user is shown content (an exposure) but does not click, like, or otherwise interact with it, this is considered negative feedback. Both exposure and click behavior data are required.
12. Real-time data reporting
Yes, both full and incremental data for users, items, and behaviors should be reported in real time.
Failure to report data in real time has the following consequences: For behavior data, the real-time feedback loop is broken, preventing the model from learning from the latest interactions. For user data, if a new user is not reported promptly, recommendations for that user will be less accurate. For item data, we recommend real-time updates to ensure any changes to item information are reflected immediately.
13. Data migration during edition upgrade
No. You can test with the Junior Edition and then upgrade your configuration to migrate to a production environment. The upgrade is seamless.
14. Common server-side SDK data push errors
①ClientException: DocumentError.MissingField : Missing fields, field names: item_id. Reason: A required field, such as item_id, was not submitted, or its value was an empty string.
ClientException: BadFormat : null. Reason: Check if the submitted JSON string is malformed, which can cause a parsing failure.
③ClientException: InstanceNotExist : The specified instance does not exist. Reason: This can happen for two reasons: 1. The instance is still starting. 2. The region in your data push code is incorrect. It must match the region of your purchased instance.
④ServerException: FetchDocumentBackendError: Internal server error. Reason: Check for spelling mistakes in fixed strings within your JSON data, for example, writing "filed" instead of "field".
15. Missing exposure or traceInfo data
If your application's event tracking logic cannot yet provide exposure data or pass back traceInfo data, AIRec can automatically handle this for you. You can configure these settings separately for exposure data and traceInfo data.
-
Special handling for exposure data:
Exposure data is generated when a recommended item appears in a user's feed for a sufficient time to be seen. This data is a prerequisite for all subsequent user behaviors and is essential for the AIRec algorithm. If you cannot provide this data, AIRec can automatically supplement it to help you start your instance quickly. To enable this feature:
Procedure:
In the AIRec console, click Data Source.
You can find Data Source in the Basic Settings section of the left-side navigation pane on the instance details page.
Click to expand the Real-time Data Source section to find the feature toggle.
The feature toggle includes two configuration items: Does the behavior data contain accurate exposure data (with options "Yes, can be used for model training" and "No, special processing is required") and Does the behavior data contain accurate traceInfo (with options "Yes, can be used for attribution" and "No, special processing is required").
Select "No, special processing is required".
-
Special handling for traceInfo data:
The
traceInfodata is used during model computation to determine if a user's action, such as a click, occurred as a result of an AIRec recommendation. This information is then used to iterate and improve the recommendation algorithm. If you cannot provide accuratetraceInfodata, you can enable a feature that allows AIRec to automatically supplement it, which helps you get started.(For a detailed explanation of
traceInfodata, see question 10 above).Procedure:
In the AIRec console, click Data Source.
Click to expand the Real-time Data Source section to find the feature toggle: Does the behavior data contain accurate traceInfo (with options "Yes, can be used for attribution" and "No, special processing is required").
Select "No, special processing is required" to enable the feature. AIRec will then handle the related data automatically.