Item Segmentations¶
Item Segmentation is an abstraction on top of the catalog of Items. It allows you to group the Items into Segments based on their properties. The Segments can be then recommended to your users.
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).
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¶
You can create the Property-based Segmentation in the Admin UI by picking the name of the property¶
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:
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.
Create a Scenario which returns Segments¶
Choose the Segmentation which shall be used in the Scenario¶
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:
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
'segmentId' != "coupons"
Do not recommend horror movies to kids
if context_user["is_child_profile"] then 'segmentId' != "Horror" else true
Example of a booster:
Boosting the Editors Pick section
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¶
You can create individual Segments of the Manual ReQL Segmentation 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¶
You can specify the ReQL expression for the Auto ReQL Segmentation 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.