# Segmentations Definition > Source: https://docs.recombee.com/api/segmentations > For the complete documentation index, see [llms.txt](/llms.txt). # Segmentations Definition Segmentations allow you to group the Items into various segments: For example segment articles or products by categories, segment movies by genres, etc. The Segmentations can be used in recommendations (e.g. return the most relevant categories for a user). See [this section](https://docs.recombee.com/segmentations) for more info. ## Property Based Segmentation Property-based Segmentation groups the Items by the value of a particular property. See [this section](https://docs.recombee.com/segmentations/property-based-segmentations) for more info. put ### Create Property Based Segmentation Creates a Segmentation that splits the items into segments based on values of a particular item property. A segment is created for each unique value of the property. In case of `set` properties, a segment is created for each value in the set. Item belongs to all these segments. ```js client.send(new requests.CreatePropertyBasedSegmentation(segmentationId, sourceType, propertyName, { // optional parameters: title: 'Categories', // string description: 'Segmentation based on item categories.', // string })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the newly created Segmentation --- sourceType String Located in: **body** Required: **Yes** Since version: **4.1.0** What type of data should be segmented. Currently only `items` are supported. --- propertyName String Located in: **body** Required: **Yes** Since version: **4.1.0** Name of the property on which the Segmentation should be based --- title String Located in: **body** Required: **No** Since version: **4.1.0** Human-readable name that is shown in the Recombee Admin UI. --- description String Located in: **body** Required: **No** Since version: **4.1.0** Description that is shown in the Recombee Admin UI. --- #### Responses 201 successful operation --- 400 segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$, property is not of supported type (`string` or `set`). --- 404 Property does not exist. --- post ### Update Property Based Segmentation Updates a Property Based Segmentation ```js client.send(new requests.UpdatePropertyBasedSegmentation(segmentationId, { // optional parameters: propertyName: 'categories', // string title: 'Categories', // string description: 'Segmentation based on item categories.', // string })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the updated Segmentation --- propertyName String Located in: **body** Required: **No** Since version: **4.1.0** Name of the property on which the Segmentation should be based --- title String Located in: **body** Required: **No** Since version: **4.1.0** Human-readable name that is shown in the Recombee Admin UI. --- description String Located in: **body** Required: **No** Since version: **4.1.0** Description that is shown in the Recombee Admin UI. --- #### Responses 201 successful operation --- 400 segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$, property is not of supported type (`string` or `set`). --- 404 Property does not exist. Segmentation with given ID does not exist. --- ## Manual ReQL Segmentation Segmentation whose Segments are defined by ReQL filters. See [this section](https://docs.recombee.com/segmentations/reql-segmentations#manual-reql-segmentation) for more info. put ### Create Manual ReQL Segmentation Segment the items using multiple [ReQL](https://docs.recombee.com/reql) filters. Use the Add Manual ReQL Items Segment endpoint to create the individual segments. ```js client.send(new requests.CreateManualReqlSegmentation(segmentationId, sourceType, { // optional parameters: title: 'Homepage Rows', // string description: 'Segmentation grouping items into rows shown on the homepage.', // string })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the newly created Segmentation --- sourceType String Located in: **body** Required: **Yes** Since version: **4.1.0** What type of data should be segmented. Currently only `items` are supported. --- title String Located in: **body** Required: **No** Since version: **4.1.0** Human-readable name that is shown in the Recombee Admin UI. --- description String Located in: **body** Required: **No** Since version: **4.1.0** Description that is shown in the Recombee Admin UI. --- #### Responses 201 successful operation --- 400 segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- #### Examples ##### Example Create a Manual ReQL Segmentation and set up its Segments Each Segment is defined by a ReQL filter: Items passing the filter belong to the Segment. Here we create two Segments in the `homepage-rows` Segmentation: * `made-in-us` contains items that were created in the US * `short-laughs` contains comedies with runtime under 30 minutes See [this section](https://docs.recombee.com/segmentations/reql-segmentations#manual-reql-segmentation) for more info. ```python reqs = [ CreateManualReqlSegmentation("homepage-rows", "items"), AddManualReqlSegment("homepage-rows", "made-in-us", "'country' == \"US\" "), AddManualReqlSegment("homepage-rows", "short-laughs", "\"Comedy\" in 'genres' and 'runtime' < 30") ] responses = client.send(Batch(reqs)) ``` post ### Update Manual ReQL Segmentation Update an existing Segmentation. ```js client.send(new requests.UpdateManualReqlSegmentation(segmentationId, { // optional parameters: title: 'Homepage Rows', // string description: 'Segmentation grouping items into rows shown on the homepage.', // string })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the updated Segmentation --- title String Located in: **body** Required: **No** Since version: **4.1.0** Human-readable name that is shown in the Recombee Admin UI. --- description String Located in: **body** Required: **No** Since version: **4.1.0** Description that is shown in the Recombee Admin UI. --- #### Responses 201 successful operation --- 400 segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$. Given Segmentation is of different type. --- 404 Segmentation with given ID does not exist. --- put ### Add Manual ReQL Segment Adds a new Segment into a Manual ReQL Segmentation. The new Segment is defined by a [ReQL](https://docs.recombee.com/reql) filter that returns `true` for an item in case that this item belongs to the segment. ```js client.send(new requests.AddManualReqlSegment(segmentationId, segmentId, filter, { // optional parameters: title: 'Newly published', // string })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the Segmentation to which the new Segment should be added --- segmentId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the newly created Segment --- filter String Located in: **body** Required: **Yes** Since version: **4.1.0** ReQL filter that returns `true` for items that belong to this Segment. Otherwise returns `false`. --- title String Located in: **body** Required: **No** Since version: **4.1.0** Human-readable name of the Segment that is shown in the Recombee Admin UI. --- #### Responses 201 successful operation --- 400 segmentationId or segmentId does not match ^\[a-zA-Z0-9\_-:@.\]+$. Segmentation is of wrong type. --- 404 Segmentation with given ID does not exist. --- post ### Update Manual ReQL Segment Update definition of the Segment. ```js client.send(new requests.UpdateManualReqlSegment(segmentationId, segmentId, filter, { // optional parameters: title: 'Newly published', // string })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the Segmentation to which the updated Segment belongs --- segmentId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the Segment that will be updated --- filter String Located in: **body** Required: **Yes** Since version: **4.1.0** ReQL filter that returns `true` for items that belong to this Segment. Otherwise returns `false`. --- title String Located in: **body** Required: **No** Since version: **4.1.0** Human-readable name of the Segment that is shown in the Recombee Admin UI. --- #### Responses 201 successful operation --- 400 segmentationId or segmentId does not match ^\[a-zA-Z0-9\_-:@.\]+$. Segmentation is of wrong type. --- 404 Segmentation with given ID does not exist. Segment with given ID does not exist in the Segmentation. --- delete ### Delete Manual ReQL Segment Delete a Segment from a Manual ReQL Segmentation. ```js client.send(new requests.DeleteManualReqlSegment(segmentationId, segmentId)); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the Segmentation from which the Segment should be deleted --- segmentId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the Segment that should be deleted --- #### Responses 201 successful operation --- 400 segmentationId or segmentId does not match ^\[a-zA-Z0-9\_-:@.\]+$. Segmentation is of wrong type. --- 404 Segmentation with given ID does not exist. Segment with given ID does not exist in the Segmentation. --- ## 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. See [this section](https://docs.recombee.com/segmentations/reql-segmentations#auto-reql-segmentation) for more info. put ### Create Auto ReQL Segmentation Segment the items using a [ReQL](https://docs.recombee.com/reql) expression. For each item, the expression should return a set that contains IDs of segments to which the item belongs to. ```js client.send(new requests.CreateAutoReqlSegmentation(segmentationId, sourceType, expression, { // optional parameters: title: 'Country and Genre', // string description: 'Segmentation combining item genre and country of origin.', // string })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the newly created Segmentation --- sourceType String Located in: **body** Required: **Yes** Since version: **4.1.0** What type of data should be segmented. Currently only `items` are supported. --- expression String Located in: **body** Required: **Yes** Since version: **4.1.0** ReQL expression that returns for each item a set with IDs of segments to which the item belongs --- title String Located in: **body** Required: **No** Since version: **4.1.0** Human-readable name that is shown in the Recombee Admin UI. --- description String Located in: **body** Required: **No** Since version: **4.1.0** Description that is shown in the Recombee Admin UI. --- #### Responses 201 successful operation --- 400 segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$, ReQL expression is invalid. --- #### Examples ##### Example Create an Auto ReQL Segmentation Create a Segmentation, whose Segments combine the country of origin and the genre. See [this section](https://docs.recombee.com/segmentations/reql-segmentations#auto-reql-segmentation) for more info. ```python req = CreateAutoReqlSegmentation( "country-and-genre", "items", "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')", ) response = client.send(req) ``` post ### Update Auto ReQL Segmentation Update an existing Segmentation. ```js client.send(new requests.UpdateAutoReqlSegmentation(segmentationId, { // optional parameters: expression: 'map(lambda \'genre\': \'genre\' + "-" + \'country\', \'genres\')', // string title: 'Country and Genre', // string description: 'Segmentation combining item genre and country of origin.', // string })); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the updated Segmentation --- expression String Located in: **body** Required: **No** Since version: **4.1.0** ReQL expression that returns for each item a set with IDs of segments to which the item belongs --- title String Located in: **body** Required: **No** Since version: **4.1.0** Human-readable name that is shown in the Recombee Admin UI. --- description String Located in: **body** Required: **No** Since version: **4.1.0** Description that is shown in the Recombee Admin UI. --- #### Responses 201 successful operation --- 400 segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$. ReQL expression is invalid. Given Segmentation is of different type. --- 404 Segmentation with given ID does not exist. --- ## General get ### List Segmentations Return all existing items Segmentations. ```js const result = await client.send(new requests.ListSegmentations(sourceType)); ``` --- Since version 4.1.0 --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- sourceType String Located in: **query** Required: **Yes** Since version: **4.1.0** List Segmentations based on a particular type of data. Currently only `items` are supported. --- #### Responses 200 ``` { "segmentations": [ { "segmentationId": "category", "sourceType": "items", "segmentationType": "property", "title": "Category Segmentation", "description": "Groups items by their category" }, { "segmentationId": "homepage-rows", "sourceType": "items", "segmentationType": "manualReQL", "title": "Homepage Rows", "description": "Defines individual content rows that can be shown on the homepage" } ] } ``` --- get ### Get Segmentation Get existing Segmentation. ```js const result = await client.send(new requests.GetSegmentation(segmentationId)); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the Segmentation that should be returned --- #### Responses 200 ``` { "segmentationId": "category", "sourceType": "items", "segmentationType": "property", "title": "Category Segmentation", "description": "Groups items by their category" } ``` --- 404 Segmentation with given ID does not exist. --- delete ### Delete Segmentation Delete existing Segmentation. ```js client.send(new requests.DeleteSegmentation(segmentationId)); ``` --- Since version 4.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of your database. --- segmentationId String Located in: **path** Required: **Yes** Since version: **4.1.0** ID of the Segmentation that should be deleted --- #### Responses 200 successful operation --- 404 Segmentation with given ID does not exist. ---