Miscellaneous

post

Batch

Allowed on Client-Side

Batch processing allows you to submit arbitrary sequence of requests within a single HTTPS request.

Any type of request from the above documentation may be used in the Batch, and the Batch may combine different types of requests arbitrarily as well.

Using Batch requests is beneficial for example, when synchronizing the catalog of items or uploading historical interaction data, as sending the data in Batch is considerably faster than sending the individual requests (thanks to optimizations and reducing network and HTTPS overhead).

Javascript Kotlin Swift Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new recombee.Batch(requests, {
  // optional parameters:
  distinctRecomms: true,  // boolean
}));

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

requests

Array

Located in: body

Required: Yes

JSON array containing the requests.

distinctRecomms

Boolean

Located in: body

Required: No

Since version: 1.2.4

Makes all the recommended items for a certain user distinct among multiple recommendation requests in the batch.

Responses

200

Successful operation. There is an array with responses. The order of the responses in the array follows the order of the sent requests.

[
  {
    "code": 200,
    "json": "ok"
  },
  {
    "code": 200,
    "json": "ok"
  },
  {
    "code": 200,
    "json": {
      "recommId": "3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb",
      "recomms": [
        {
          "id": "item-146"
        },
        {
          "id": "item-462"
        },
        {
          "id": "item-463"
        }
      ],
      "numberNextRecommsCalls": 0
    }
  }
]

400

Many possibilities, see the error description in the result JSON. Examples: invalid or missing Content-type (not application/json), request body is not a valid JSON, request JSON does not have the prescribed structure.

404

There is at least one request in the batch with an invalid (non-existing) URL. In such a case, the batch as a whole is not executed and you'll get HTTP 404, because the batch is apriori erroneous.

413

Too large batch (containing more than 10,000 requests in case of a server side request).

Examples

Example Sending multiple requests in a single Batch request

Batch can encapsulate requests of various types.

Javascript Kotlin Swift Python Ruby Java Node.js PHP C#Go REST

Copy

let reqs = [new recombee.AddDetailView(userId, itemId),
            new recombee.RecommendItemsToUser(userId, 5, {scenario: 'just_for_you'}),
            new recombee.RecommendItemsToItem(itemId, userId, 5, {scenario: 'similar_products'})
           ];

const responses = await client.send(new recombee.Batch(reqs));

Example Checking the result of the individual requests

You should check that the requests in the Batch succeeded. A request can fail for example due to invalid parameters - the returned error mesage gives you a hint what went wrong.

Javascript Kotlin Swift Python Ruby Java Node.js PHP C#Go

Copy

try {
  const responses = await client.send(new recombee.Batch(reqs));
  for (const response of responses) {
    if (response.code < 200 || response.code > 299) {
      // A request in the Batch did not succeed
      console.log(response);
    }
  }
} catch (error) {
    // The whole Batch request failed
}

Example Using distinctRecomms parameter to deduplicate results in multiple boxes

If you show multiple boxes with recommendations on a single page, you may want to ensure that the same item is not recommended in multiple boxes. You can achieve that by specifying distinctRecomms=true.

Javascript Kotlin Swift Python Ruby Java Node.js PHP C#Go REST

Copy

const batchRequest = new rqs.Batch([
  new RecommendItemsToUser('user-id', 5, {scenario:'new_releases', cascadeCreate: true}),
  new RecommendItemsToUser('user-id', 5, {scenario:'just_for_you', cascadeCreate: true})
], {
  distinctRecomms: true
});

const responses = await client.send(batchRequest);

Notes

Executing the requests in a Batch is equivalent as if they were executed one-by-one individually; there are, however, many optimizations to make batch execution as fast as possible.

The status code of the Batch request itself is 200 even if the individual requests result in error – you have to inspect the code values in the resulting array.

If the status code of the whole batch is not 200, then there is an error in the Batch request itself; in such a case, the error message returned should help you to resolve the problem.

The batch size is limited to 10,000 requests when sent from the server side; if you wish to execute even larger number of requests, please split the Batch into multiple parts. Client libraries do the splitting automatically.

In case of the client side integration, the limit is 30 requests and only the requests that can be called from the client side are allowed.

get

List Scenarios

Get all Scenarios of the given database.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

const result = await client.send(new requests.ListScenarios());

Since version

5.1.0

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

Responses

200

Successful operation.

[
  {
    "id": "relatedArticles",
    "endpoint": "recommendItemsToItem"
  },
  {
    "id": "justForYou",
    "endpoint": "recommendItemsToUser"
  },
  {
    "id": "homepageSectionsOrdering",
    "endpoint": "recommendItemSegmentsToUser"
  },
  {
    "id": "homepageSectionContent",
    "endpoint": "recommendItemsToItemSegment"
  }
]

delete

Reset Database

Completely erases all your data, including items, item properties, series, user database, purchases, ratings, detail views, and bookmarks. Make sure the request is never executed in the production environment! Resetting your database is irreversible.

Node.js Python Ruby Java PHP C#Go REST

Copy

Initialization

client.send(new requests.ResetDatabase());

Parameters

databaseId

String

Located in: path

Required: Yes

ID of your database.

Responses

200

Successful operation.

docs.recombee.com