# Item Segmentations

> Source: https://docs.recombee.com/segmentations

> For the complete documentation index, see [llms.txt](/llms.txt).

**Table of contents**

* [A Step-by-Step Video Tutorial on Item Segmentations](#a-step-by-step-video-tutorial-on-item-segmentations)
* [Creating an Item Segmentation](#creating-segmentation)  
   * [Property-Based Segmentation](#property-based-segmentation)  
         * [Examples](#property-based-examples)  
                  * [Example 1](#example-1)  
                  * [Example 2](#example-2)  
         * [Creating in the Admin UI](#creating-in-the-admin-ui)  
         * [Creating via the API](#creating-via-the-api)
* [Recommending Segments](#recommending-segments)  
   * [Requesting Recommendations](#requesting-recommendations)  
   * [Filtering and Boosting](#filtering-and-boosting)
* [Advanced Options for Creating the Segmentations](#advanced-creating-segmentations)  
   * [Manual ReQL Segmentation](#manual-reql-segmentation)  
         * [Example](#example)  
         * [Creating in the Admin UI](#id2)  
         * [Creating via the API](#id3)  
   * [Auto ReQL Segmentation](#auto-reql-segmentation)  
         * [Examples](#id4)  
                  * [Example 1](#id5)  
                  * [Example 2](#id6)  
                  * [Example 3](#example-3)  
         * [Creating in the Admin UI](#id7)  
         * [Creating via the API](#id8)

# 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.

![](/img/headings/segmentations.png) 

It is common to Segment the Items 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](#advanced-creating-segmentations) for other advanced use cases

[Recommend Item Segments To User](/api#request-recommend-item-segments-to-user)can be then used to recommend the[top brands](/recipes/e-commerce/fully-personalized-homepage/brands-for-you) /[top artists or actors](/recipes/video/fully-personalized-homepage/actors-for-you) /[top categories or genres](/recipes/video/fully-personalized-homepage/personalized-re-ordering-of-rows-advanced) for a particular user.

It is also possible to get[related Segments to a particular item](/api#request-recommend-item-segments-to-item) (e.g. brands related to a product, artists related to a song),[Segments related to another Item Segment](/api#request-recommend-item-segments-to-item-segment) (e.g. artists similar to a particular artist, brands related to a brand), or [search within the Segments](/api#request-search-item-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 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](/segmentations#advanced-creating-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:

![](/img/segmentations/segmentations_examples_items.png)

##### Example 1

Segmentation based on the _country_property (of type `string`) will create the following three Segments:

![](/img/segmentations/segmentations_examples_county_property.png)

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:

![](/img/segmentations/segmentations_examples_genres_property.png)

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](/img/segmentations/admin_ui_property_based.png)](/img/segmentations/admin_ui_property_based.png)

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](/api#request-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](/api#request-recommend-item-segments-to-user)
* [Recommend Item Segments To Item](/api#request-recommend-item-segments-to-item)
* [Recommend Item Segments To Item Segment](/api#request-recommend-item-segments-to-item-segment)
* [Search Item Segments](/api#request-search-item-segments%3E)

Before you can use any of that endpoints, you need to[create an Item Segmentation](segmentations#creating-segmentation) and then set up a[Scenario](/scenarios) in the Admin UI which will use that Segmentation.

[![Create a Scenario which returns Segments](/img/segmentations/admin_ui_scenario_type.png)](/img/segmentations/admin_ui_scenario_type.png)

Create a Scenario which returns Segments

[![Choose the Segmentation which shall be used in the Scenario](/img/segmentations/admin_ui_scenario_choose_segmentation.png)](/img/segmentations/admin_ui_scenario_choose_segmentation.png)

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:

```js
const recommended = await client.send(
  new recombee.RecommendItemSegmentsToUser('2c169e', 5, {
    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 genres/categories for a user, and re-ordering homepage rows accordingly](/recipes/video/fully-personalized-homepage/personalized-re-ordering-of-rows-advanced)
* [Recommending the top brands for a user](/recipes/e-commerce/fully-personalized-homepage/brands-for-you)
* [Recommending the top artists or actors for a user](/recipes/video/fully-personalized-homepage/actors-for-you)

### Filtering and Boosting

Recommended Segments can be [filtered or boosted using ReQL](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](/reql) filter: Items passing the filter belong to the Segment.

#### Example

Consider the same data about the Items as in [this section](/segmentations#property-based-examples).

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

With defined Segments as follows:

![](/img/segmentations/definition_manual_segmentation.png)

Items get segmented in this way:

![](/img/segmentations/segmentations_examples_manual_segmentation.png)

You will get the optimal order of these homepage rows for the particular user by calling the[Recommend Item Segments To User](/api#request-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](/img/segmentations/admin_ui_manual_reql.png)](/img/segmentations/admin_ui_manual_reql.png)

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 also give a description
* Create the first Segment by giving it a name (which gets again translated into the Segment's ID) and providing the [ReQL](/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](/api#request-create-manual-reql-segmentation)
* Then, add the individual Segments using[Add Manual ReQL Segment](/api#request-add-manual-reql-segment)

### Auto ReQL Segmentation

Auto ReQL Segmentation is specified by a [ReQL](/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_:

ReQL

```
'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](/segmentations#property-based-segmentation) using the _genres_ property:

![](/img/segmentations/segmentations_examples_auto_genres.png)

##### 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`.

ReQL

```
'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"}`.

![](/img/segmentations/segmentations_examples_auto_genres_acclaimed.png)

##### Example 3

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

ReQL

```
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"}`.

![](/img/segmentations/segmentations_examples_auto_genre_country.png)

#### Creating in the Admin UI

[![You can specify the ReQL expression for the Auto ReQL Segmentation in the Admin UI](/img/segmentations/admin_ui_auto_reql.png)](/img/segmentations/admin_ui_auto_reql.png)

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 also give a description
* Provide the [ReQL](/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](/api#request-create-auto-reql-segmentation)endpoint.