Recommendations enrichment data entities

Article
10/07/2024

This article provides guidance on how to configure recommendations enrichment 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

Intelligent Recommendations supports manual enrichment of generated recommendations, which allows you to manually add or remove specific items or item variants from any recommendations list.

The supported enrichment actions are:

Include: Adds the specified item or item variant at the top of the specified list. These manually added items are sorted by their Rank attribute.
Exclude: Removes the specified item or item variant from the specified list, whatever the rank of the item in said list.

Item availabilities are always respected. Any item not considered available at the moment when the recommendation API is called isn't returned as part of the response.

The following data entities are part of the recommendations enrichment data entities:

Go to the full list of data entities

Recommendations enrichment for a specific item

Data entity name: Reco_SeededRecommendationsEnrichment

Description: Enrichment of recommendation results for a specific Item using ItemId known as the SeedItemId. Only applies to lists such as "People also like", which are keyed off a specific item.

Attributes:

Name	Data type	Mandatory	Invalid value behavior	Comments
RecoListName	String	Yes	Trim value	Go to the ListNames Table for the supported list names.
AlgoType	String	No	Trim value	Not all list names require this value to be set. See the AlgoTypes Table for the supported algorithm types for each list name.
SeedItemId	String(16)	Yes	Drop entry	The ItemId the list is recommending for. See Required data entities per recommendations scenario for item ID.
SeedItemVariantId	String(16)	No	Drop entry	The ItemVariantId the list is recommending for. See Required data entities per recommendations scenario for item variant ID.
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.
EnrichmentAction	String	Yes	Drop entry	Supports only Include or Exclude for now.
Rank	Int	No	Drop entry	For the Exclude enrichment action, this value is ignored.

Guidelines:

Items marked include can be added only to the top of a generated recommendations list.
Excluding an item from a list that the item doesn’t appear in will do nothing.
Exclusion always wins. If you include and exclude the same item from the same list, it's excluded from the final API response.
The Rank attribute only specifies the order between the added items or item variants. In any case, they'll always be added to the top of the list. If there are duplicate rank values for multiple items, they're added in some random order between them.
Enrichments with an unsupported AlgoType value are ignored.

Sample data:

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

RecoListName	AlgoType	SeedItemId	SeedItemVariantId	ItemId	ItemVariantId	EnrichmentAction	Rank
Similar	MF	Item1		Item2		Include	1
Similar	MF	Item1		Item3	Item3Var1	Include	2
Similar	DAS	Item3	Item3Var1	Item1	Item1Var2	Exclude
Cart		Item3		Item1	Item1Var1	Include	1