Item Segmentations

It is common to Segment the Items for example by:

• category or brand in the case of products
• genre in the case of movies
• artist in the case of songs
• belonging to particular homepage rows - see this section for other advanced use cases

Recommend Item Segments To User can be then used to recommend the top categories / top brands / top genres / top artists for a particular user.

It is also possible to get related Segments to a particular item (e.g. brands related to a product, artists related to a song), Segments related to another Item Segment (e.g. artists similar to a particular artist, brands related to a brand), or search within the Segments (search brands, artists, etc. with a search query).

A step-by-step video tutorial on Item Segmentations#

Creating an Item Segmentation#

There are multiple ways how a Segmentation can be defined.

The most frequently used and the easiest to set up is Property-based Segmentation.

See this section for info on more advanced options for creating the Segmentations.

Property-based Segmentation#

Property-based Segmentation groups the Items by the value of a particular property.

The property can be of string or set type.

NULL values are ignored.

Examples#

Consider the following data about the Items:

Example 1#

Segmentation based on the country property (of type string) will create the following three Segments:

For example, the value of the country property for the it_crowd is GB, and therefore the it_crowd belongs to the GB Segment.

Example 2#

Segmentation based on the genres property (of type set) will create the following three Segments:

Note that an Item can belong to multiple Segments: In that case, the_silence_of_the_lambs belongs to both Horror and Thriller Segments.

Creating in the Admin UI#

• Navigate to the Segmentations section
• Create a new Segmentation of the Property-based type and select by which Item property the Items shall be segmented.
• Check the preview of the resulting Segments and confirm the setup

Creating via the API#

• Call the Create Property Based Segmentation endpoint.

Recommending Segments#

Requesting recommendations#

The Segments can be recommended or searched using the following endpoints:

• Recommend Item Segments To User
• Recommend Item Segments To Item
• Recommend Item Segments To Item Segment
• Search Item Segments

Before you can use any of that endpoints, you need to create an Item Segmentation and then set up a Scenario in the Admin UI which will use that Segmentation.

The ID of that Scenario needs to be provided in the scenario parameter of the recommendation request:

client.send(
	new recombee.RecommendItemSegmentsToUser('2c169e575644d840838e', 5, {
		scenario: 'top_categories',
		cascadeCreate: true,
	}),
	(err, recommended) => {
		//...
	},
);

recommended = client.send(RecommendItemSegmentsToUser('2c169e575644d840838e', 5,
							scenario='top_categories',
							cascade_create=True))

recommended = client.send(RecommendItemSegmentsToUser.new('2c169e575644d840838e', 5,
{
	'scenario' => 'top_categories',
	'cascadeCreate' => true
})
)

RecommendationResponse recommended = client.send(new RecommendItemSegmentsToUser("2c169e575644d840838e", 5))
.setScenario("top_categories")
.setCascadeCreate(true);

<?php
$recommended = $client -> send(new Reqs\RecommendItemSegmentsToUser('2c169e575644d840838e', 5,
																	[
																		'scenario' => 'top_categories',
																		'cascadeCreate' => true
																	])
							);
?>

RecommendationResponse recommended = client.Send(new RecommendItemSegmentsToUser("2c169e575644d840838e", 5,
								scenario: "top_categories",
								cascadeCreate: true));

client.send(new rqs.RecommendItemSegmentsToUser('2c169e575644d840838e', 5,
	{
		'scenario': 'top_categories',
		'cascadeCreate': true
	}
	),
	(err, recommended) => {
	//...
	}
);

GET /myDb/recomms/users/2c169e575644d840838e/item-segments/?count=10&scenario=top_categories&cascadeCreate=true

These are some examples of how recommending Segments can be used on your website or in your app:

• Recommending the top categories for a user
• Recommending the top brands for a user
• Recommending the top genres for a user

Filtering and Boosting#

Recommended Segments can be filtered or boosted using ReQL. You can access the ID of a Segment in ReQL using 'segmentId'.

Examples of filters:

• Do not recommend the coupons category to the users

  ReQL

  'segmentId' != "coupons"
  

• Do not recommend horror movies to kids

  ReQL

  if context_user["is_child_profile"] then 'segmentId' != "Horror" else true
  

Example of a booster:

• Boosting the Editors Pick section

  ReQL

  if 'segmentId' == "Editors Pick" then 2 else 1
  

Advanced options for creating the Segmentations#

Manual ReQL Segmentation#

With Manual ReQL Segmentation, you specify individual Segments of the Segmentation.

Each Segment is defined by a ReQL filter: Items passing the filter belong to the Segment.

Example#

Consider the same data about the Items as in this section.

You can create an Item Segmentation where each Segment will represent one row on the homepage.

With defined Segments as follows:

Items get segmented in this way:

You will get the optimal order of these homepage rows for the particular user by calling the Recommend Item Segments To User endpoint.

Creating in the Admin UI#

• Navigate to the Segmentations section
• Give the Segmentation a title, which gets translated into the Segmentation ID, and optionally give also a description
• Create the first Segment by giving it a name (which gets again translated into the Segment's ID) and providing the ReQL filter
  • You can check which Items belong to the Segment by clicking on Preview items
• Click Add Segment to add another Segment
• When satisfied with the setup, click Create to confirm it

Creating via the API#

• First, create an empty Segmentation using Create Manual ReQL Segmentation
• Then add the individual Segments using Add Manual ReQL Segment

Auto ReQL Segmentation#

Auto ReQL Segmentation is specified by a ReQL expression that for each Item returns a set of Segments to which the Item belongs.

The individual Segments don't need to be predefined in any way.

Examples#

Example 1#

The following expression returns the set of genres:

'genres'

For example, for johnny_english it returns {"Comedy"} and for the_silence_of_the_lambs it returns {"Horror", "Thriller"}.

Therefore it behaves the same as the Property-based Segmentation using the genres property:

Example 2#

The following Segmentation put the Items into Segments according to their genres and also adds a Critically Acclaimed Segment for items with 'critically_acclaimed' == true.

'genres' + (if 'critically_acclaimed' then {"Critically Acclaimed"} else {})

For example, for johnny_english it returns {"Comedy"}, for friends it returns {"Comedy", "Critically Acclaimed"}, and for the_silence_of_the_lambs it returns {"Horror", "Thriller", "Critically Acclaimed"}.

Example 3#

The Segments of the following Segmentation are a combination of the Item's genres and country (British comedies, US thrillers, etc.).

map(lambda 'genre': 'genre' + "-" + 'country', 'genres')

For example, for johnny_english it returns {"Comedy-GB"}, for friends it returns {"Comedy-US"}, and for the_silence_of_the_lambs it returns {"Horror-US", "Thriller-US"}.

Creating in the Admin UI#

• Navigate to the Segmentations section
• Create a new Segmentation of the Auto ReQL type
• Give the Segmentation a title, which gets translated into the Segmentation ID, and optionally give also a description
• Provide the ReQL expression which returns a set of Segments to which an Item belongs
• Check the preview of the resulting Segments and confirm the setup

Creating via the API#

• Call the Create Auto ReQL Segmentation endpoint.