Batch Recommendations
With batch recommendations, recommendation job requests can be made and the results will be saved in the client workspace. All the recommendations generated will be saved in a folder named with the request ID and contain one json file per recommendation that has been made. Also Endpoints to check the recommendation work order status and to cancel them also exist.
The number of recommendations made to recipients will be added to the client's request counter, and if the number of recommendations is greater than the available requests for the client, the request will be rejected.
There are five possible statuses for the batch recommendation process:
Status | Description |
---|---|
queued | The recommendation request has been logged, but it has not been processed yet. |
processing | The recommendation request is being processed. |
canceled | The recommendation request has been canceled at the request of the user. |
error | An error occurred while generating the recommendations. No changes have been applied. |
completed | The recommendation request completed successfully. |
When batch recommendation is requested for the first time (see Schedule Batch Recommendations, the API automatically assigns queued
status. To check the updated status, please refer to Get batch recommendation Status.
Schedule Batch Recommendations
The batch recommendation for the given table will be scheduled.
URL
- Items for each user: POST /{tableId}/users/items/recommend
- Users for each item: POST /{tableId}/items/users/recommend
- Items for each item: POST /{tableId}/items/items/recommend
- Users for each user: POST /{tableId}/users/users/recommend
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
engine | String | Engine to perform the training: content_based or hybrid. If no engine is specified, the default table engine will be used. | |
configuration | Map<String, Object> | Configuration for batch recommendations. |
Configuration map available parameters:
Configuration parameter | Mandatory | Type | Description |
---|---|---|---|
recipientsFilter | String | Boolean-returning RSQL expression, which allows you to filter the recipients to be recommended. Only the recipients for which the expression is true will be returned. | |
recommendationsFilter | String | Boolean-returning RSQL expression, which allows you to filter the items to be listed. Only the items for which the expression is true will be returned. | |
attributeId | String | Attribute ID of the items to be used as a weight in the recommendation, i.e. s^i=siai, where si,ai are the score and the value of the attribute of the i-th item. The corresponding attribute should be numeric and if there is more than one interaction, the interactionId parameter should be provided. | |
interactionId | String | ID of the main interaction to be used for the recommendation. If undefined, the recommendation s is performed by taking the weighted average of the scores associated to each interaction, i.e. s=∑Iw(I)∑Iw(I)s(I), where w(I),s(I) are the weight and score of the I-th interaction, respectively. | |
limit | Integer | Number of recommendations for each recipient. Default value is 500 | |
sort | String | RSQL expression used to sort the result list. | |
diversity | Double | Value between 0 and 1 representing the amount of diversity, where 0 means no diversity and 1 means a high level of diversity. If undefined, it defaults to 0. Note that diversity can reduce the degree of matching. The diversity parameter is only available for the hybrid engine . |
Examples:
Recommendations with the default table engine, for all recipients, using all the items and all the interactions defined for the table:
{
// no parameters
}
Recommendations with the hybrid engine, only for interaction rating, using filters for both recipients and recommendation entities, with diversity and with a limit of 100 recommendations per recommendation recipient. The results will be sorted by year ascending:
{
"engine" : "hybrid",
"configuration":{
"recipientsFilter" : "age=gt=65",
"recommendationsFilter" : "year=lt=1980",
"interactionId" : "rating",
"limit" : 100,
"diversity": 0.45,
"sort": "year==ASC"
}
}
Response
Code | Name |
---|---|
202 | Accepted |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
503 | Service Unavailable |
JSON that includes the ID and the status of the request.
Example
Schedule content_based
items batch recommendation for all users of the movies
table, with a max of 100 items per recommendation.
curl -X POST "https://recom.sherpa.ai/v2/recomm/movies/users/items/recommend" \
-H "Content-Type: application/json" \
-H "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H "X-Sherpa-timestamp: 1548084514112" \
-H "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-d "{\"engine\":\"content_based\",\"limit\":100}"
{
"requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
"status": "queued",
"recommendationsCount" : 939
}
Get Batch Recommendation Status
Return the status of the batch recommendation work order.
URL
GET /{tableId}/recommend/{requestId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
requestId | ✓ | String | ID returned by the work order request |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |
JSON that includes the current status of the request.
Example
Get the current status of the request 0f1105ed-9b09-42d9-a377-635ea44d2519
.
curl -X GET "https://recom.sherpa.ai/v2/recomm/movies/recommend/0f1105ed-9b09-42d9-a377-635ea44d2519" \
-H "Content-Type: application/json" \
-H "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H "X-Sherpa-timestamp: 1548084514112" \
-H "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H "X-Sherpa-hmac: xxxxyyyyyyy***signature******"
{
"requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
"status": "completed",
"recommendationsCount" : 939
}
Cancel Batch Recommendation
Cancel a work order request. This can only be done when the status of the request is queued
.
URL
DELETE /{tableId}/recommend/{requestId}
Parameters
URL parameters:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
requestId | ✓ | String | ID returned by a work order request |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
503 | Service Unavailable |
JSON that includes the current status of the request.
Example
Cancel the request 0f1105ed-9b09-42d9-a377-635ea44d2519
.
curl -X DELETE "https://recom.sherpa.ai/v2/recomm/movies/recommend/0f1105ed-9b09-42d9-a377-635ea44d2519" \
-H "Content-Type: application/json" \
-H "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H "X-Sherpa-timestamp: 1548084514112" \
-H "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H "X-Sherpa-hmac: xxxxyyyyyyy***signature******"
{
"requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
"status": "canceled",
"recommendationsCount" : 939
}