Interactions data entities
This article provides guidance on how to configure your interactions data entities in the Intelligent Recommendations data contract.
Data entities review
A data entity is a set of one or more data text files, each having a list of columns (also called attributes) and rows containing the actual data values.
Intelligent Recommendations defines logical groups of data entities, each with its own purpose.
Data entities are optional, unless explicitly stated otherwise, which means that their data can be empty or missing.
Go to the full list of data entities
Introduction to interactions data entities
Interactions represent the set of all ways that a user interacts with the catalog items. Some common user actions include transactional interactions (purchases), views (click-through), ratings, or any other action that occurs between a user and an item or item variant.
The following data entities are part of the interactions data entities:
Data entity name: Reco_Interactions.
Description: All user interactions with items and item variants.
|Name||Data type||Mandatory||Default value||Invalid value behavior||Comments|
|InteractionGroupingId||String(256)||Yes||Drop entry||A grouping ID for several interactions. Length limited to 256 characters.|
|ItemId||String(16)||Yes||Drop entry||See Required data entities per recommendations scenario for item ID.|
|ItemVariantId||String(16)||No||Drop entry||See Required data entities per recommendations scenario for item variant ID.|
|UserId||String(256)||No||Drop entry||An empty value represents an anonymous interaction. Length limited to 256 characters.|
|InteractionType||String||No||Transaction||Drop entry||Transaction is the only valid value for this attribute and doesn't affect the recommendation results.|
|TimeStamp||DateTime||No||1970-01-01T00:00:00.000Z||Drop entry||See Required data entities per recommendations scenario for DateTime values.|
|String Attribute||String(64)||No||Drop entry||Length is limited to 64 characters. A string attribute that can be used according to the business' needs and doesn't effect the modeling proccess.|
|Double Attribute||Double||No||Drop entry||A double attribute that can be used according to the business' needs and doesn't effect the modeling proccess.|
|Channel||String(64)||No||0||Trim value||Length limited to 64 characters.|
|Catalog||String(64)||No||0||Trim value||Length limited to 64 characters.|
|Strength||Double||No||1.0||Drop entry||Represents how significant the interactions are (compared to other interactions). This can help improve transaction processes and performance, but transparency and ethical use of data are important considerations. Supported in Next Best Action, User Picks and Similar (AlgoType=MF).|
|IsPositive||Bool||No||True||See Required data entities per recommendations scenario for Boolean values.|
InteractionGroupingId is the main collaborative indicator grouping items together in a single multi-item interaction. It can be anything that, in the scope of your business, creates relationships between items. For example, items purchased in the same interactions (basket) might be connected/related, so basket/transaction ID could be a good fit for this field. If a collaborative factor is the user (person) interacting with items, you might want to copy UserId to this field and have it in the UserId field as well.
Make sure that Interactions data entity contains interactions of the same type (type can be - likes, transactions, views, etc.). In order to get recommendations for various interaction types, it is recommended that a modeling component will read interactions of the same type. Consolidating different types of transactions into the same model will return mixed recommendations with different and not necessarily desired meaning than working with separated models/IR accounts.
Unsupported interaction types will be ignored.
All data rows that represent the same operation (for example, a transaction of several items) should have the same unique grouping ID.
Negative interactions (such as item returns or dislikes) are represented by IsPositive=False.
Double Attribute, String Attribute and Interaction Type columns listed can be left empty for now.
Using "0" as the value for either the "Channel" or "Catalog" attributes will result in a processing error.
On Next Best Action scenario, Strength attribute is capped at 10. values above 10 will be replaced by 10.
Examples of when to use strength include:
- Prioritize products with a higher likelihood of being interacted with (i.e. viewed, watched, etc.). If you prefer to have higher prioritization on recent purchases, consider trying the Picks API using the RecentPurchases Algo-type, which already prioritizes the most recent interactions of a user.
- Rating scores to products in scale of 1-5 can be reflected by setting the strength of the relevant transaction as the rating score that the user gave to the item.
- Prioritizing the duration of watching a video by giving longer views a higher strength than those of shorter views.
Headers appear for convenience only and shouldn't be part of the actual data.
|InteractionGroupingId||ItemId||ItemVariantId||UserId||InteractionType||Timestamp||String Attribute||Double Attribute||Channel||Catalog||Strength||IsPositive|
Go to the full list of data entities
Data contract overview Data entities mapping table Catalog data entities Reco configuration data entities External lists data entities Opted-out users data entities Recommendations enrichment data entities Image to item mapping data entities Intelligent Recommendations API Quick start guide: Set up and run Intelligent Recommendations with sample data