Interactions data entities

Article
06/09/2023

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.

Note

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:

Interactions

Interactions

Data entity name: Reco_Interactions.

Description: All user interactions with items and item variants.

Attributes:

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 affect the modeling process.
Double Attribute	Double	No		Drop entry	A double attribute that can be used according to the business' needs and doesn't affect the modeling process.
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 attribute 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.

Guidelines:

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's recommended that a modeling component reads interactions of the same type. Consolidating different types of transactions into the same model return mixed recommendations with different and not necessarily desired meaning than working with separated models/IR accounts.
Unsupported interaction types are 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 result in a processing error.
On Next Best Action scenario, Strength attribute is capped at 10. values above 10 are 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 the videos of shorter views.

Sample data:

Headers appear for convenience only and shouldn't be part of the actual data.

InteractionGroupingId	ItemId	ItemVariantId	UserId	InteractionType	Timestamp	String Attribute	Channel	Catalog	Strength	IsPositive
Interaction100	Item1	Item1Var1		Transaction	2020-04-01T10:00:00.000Z
Interaction100	Item2			Transaction	2020-04-01T10:00:00.000Z		2.0
Interaction101	Item2		User1	Like	2020-05-01T13:25:00.000Z	Interaction-101-RT				False
Interaction101	Item3		User2	Rating	2020-07-12T08:45:00.000Z		Europe	MySale	4.0	False