Create or update a batch of Recommend Rules

Create or update a batch of Recommend Rules

Each Recommend Rule is created or updated, depending on whether a Recommend Rule with the same objectID already exists. You may also specify true for clearExistingRules, in which case the batch will atomically replace all the existing Recommend Rules.

Recommend Rules are similar to Search Rules, except that the conditions and consequences apply to a source item instead of a query. The main differences are the following:

• Conditions pattern and anchoring are unavailable.
• Condition filters triggers if the source item matches the specified filters.
• Condition filters accepts numeric filters.
• Consequence params only covers filtering parameters.
• Consequence automaticFacetFilters doesn’t require a facet value placeholder (it tries to match the data source item’s attributes instead).

POST /1/indexes/{indexName}/{model}/recommend/rules/batch

curl

cURL

curl --request POST \
  --url https://algolia_application_id.algolia.net/1/indexes/ALGOLIA_INDEX_NAME/related-products/recommend/rules/batch \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-algolia-api-key: ALGOLIA_API_KEY' \
  --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
  --data '[{"_metadata":{"lastUpdate":"2023-07-04T12:49:15Z"},"objectID":"lorem","condition":{"filters":"(category:Book OR category:Ebook) AND _tags:published","context":"mobile"},"consequence":{"hide":[{"objectID":"test-record-123"}],"promote":[{"objectID":"test-record-123","position":0}],"params":{"automaticFacetFilters":[{"facet":"lorem","negative":true}],"filters":"(category:Book OR category:Ebook) AND _tags:published","optionalFilters":["category:books<score=1>","category:-movies<score=1>"]}},"description":"Boost on-sale items","enabled":true,"validity":[{"from":42,"until":42}]}]'

200

{
  "taskID": 1514562690001,
  "updatedAt": "2023-07-04T12:49:15Z"
}

Required ACL: editSettings

Authorizations

x-algolia-application-id · string · header · required

Your Algolia application ID.

x-algolia-api-key · string · header · required

Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions. The required ACL to make a request is listed in each endpoint's reference.

Path Parameters

indexName · string · required

Name of the index on which to perform the operation.

Example:

"ALGOLIA_INDEX_NAME"

model · enum<string> · required

Recommend model.

Available options: related-products, bought-together, trending-facets, trending-items

Body

application/json

_metadata · ruleMetadata · object

Rule metadata.

Show child attributes

_metadata. lastUpdate · string

Date and time when the object was updated, in RFC 3339 format.

Example:

"2023-07-04T12:49:15Z"

objectID · string

Unique identifier of a rule object.

condition · object

Condition that triggers the rule. If not specified, the rule is triggered for all recommendations.

Show child attributes

condition. filters · string

Filter expression to only include items that match the filter criteria in the response.

You can use these filter expressions:

• Numeric filters. <facet> <op> <number>, where <op> is one of <, <=, =, !=, >, >=.
• Ranges. <facet>:<lower> TO <upper> where <lower> and <upper> are the lower and upper limits of the range (inclusive).
• Facet filters. <facet>:<value> where <facet> is a facet attribute (case-sensitive) and <value> a facet value.
• Tag filters. _tags:<value> or just <value> (case-sensitive).
• Boolean filters. <facet>: true | false.

You can combine filters with AND, OR, and NOT operators with the following restrictions:

• You can only combine filters of the same type with OR. Not supported: facet:value OR num > 3.
• You can't use NOT with combinations of filters. Not supported: NOT(facet:value OR facet:value)
• You can't combine conjunctions (AND) with OR. Not supported: facet:value OR (facet:value AND facet:value)

Use quotes around your filters, if the facet attribute name or facet value has spaces, keywords (OR, AND, NOT), or quotes. If a facet attribute is an array, the filter matches if it matches at least one element of the array.

For more information, see Filters.

Example:

"(category:Book OR category:Ebook) AND _tags:published"

condition. context · string

An additional restriction that only triggers the rule, when the search has the same value as ruleContexts parameter. For example, if context: mobile, the rule is only triggered when the search request has a matching ruleContexts: mobile. A rule context must only contain alphanumeric characters.

Example:

"mobile"

consequence · object

Effect of the rule.

Show child attributes

consequence. hide · object[]

Exclude items from recommendations.

Minimum array length: 1

Show child attributes

consequence.hide. objectID · string

Unique record identifier.

Example:

"test-record-123"

consequence. promote · object[]

Place items at specific positions in the list of recommendations.

Minimum array length: 1

Show child attributes

consequence.promote. objectID · string

Unique record identifier.

Example:

"test-record-123"

consequence.promote. position · integer

Index in the list of recommendations where to place this item.

Required range: x >= 0

consequence. params · object

Filter or boost recommendations matching a facet filter.

Show child attributes

consequence.params. automaticFacetFilters · object[]

Filter recommendations that match or don't match the same facet:facet_value combination as the viewed item.

Show child attributes

consequence.params.automaticFacetFilters. facet · string

Facet attribute.

consequence.params.automaticFacetFilters. negative · boolean

Whether the filter is negative. If true, recommendations must not have the same value for the facet attribute. If false, recommendations must have the same value for the facet attribute.

consequence.params. filters · string

Filter expression to only include items that match the filter criteria in the response.

You can use these filter expressions:

• Numeric filters. <facet> <op> <number>, where <op> is one of <, <=, =, !=, >, >=.
• Ranges. <facet>:<lower> TO <upper> where <lower> and <upper> are the lower and upper limits of the range (inclusive).
• Facet filters. <facet>:<value> where <facet> is a facet attribute (case-sensitive) and <value> a facet value.
• Tag filters. _tags:<value> or just <value> (case-sensitive).
• Boolean filters. <facet>: true | false.

You can combine filters with AND, OR, and NOT operators with the following restrictions:

• You can only combine filters of the same type with OR. Not supported: facet:value OR num > 3.
• You can't use NOT with combinations of filters. Not supported: NOT(facet:value OR facet:value)
• You can't combine conjunctions (AND) with OR. Not supported: facet:value OR (facet:value AND facet:value)

Use quotes around your filters, if the facet attribute name or facet value has spaces, keywords (OR, AND, NOT), or quotes. If a facet attribute is an array, the filter matches if it matches at least one element of the array.

For more information, see Filters.

Example:

"(category:Book OR category:Ebook) AND _tags:published"

consequence.params. optionalFilters · string[]

Filters to promote or demote records in the search results.

Optional filters work like facet filters, but they don't exclude records from the search results. Records that match the optional filter rank before records that don't match. Matches with higher weights (<score=N>) rank before matches with lower weights. If you're using a negative filter facet:-value, matching records rank after records that don't match.

Example:

[
  "category:books<score=1>",
  "category:-movies<score=1>"
]

description · string

Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.

Example:

"Boost on-sale items"

enabled · boolean · default: true

Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.

validity · object[]

Time periods when the rule is active.

Show child attributes

validity. from · integer<int64>

When the rule should start to be active, in Unix epoch time.

validity. until · integer<int64>

When the rule should stop to be active, in Unix epoch time.

Response

200

application/json

OK

Response, taskID, and update timestamp.

taskID · integer<int64> · required

Unique identifier of a task.

A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress with the task operation and this task ID.

Example:

1514562690001

updatedAt · string · required

Date and time when the object was updated, in RFC 3339 format.

Example:

"2023-07-04T12:49:15Z"