Add or update a composition rule

If a composition rule with the provided ID already exists, it’s replaced.

PUT /1/compositions/{compositionID}/rules/{objectID}

curl

cURL

curl --request PUT \
  --url https://algolia_application_id.algolia.net/1/compositions/my_composition_object_id/rules/lorem \
  --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 '
{
  "objectID": "my_composition_rule_object_id",
  "conditions": [
    {
      "pattern": "{facet:genre}",
      "anchoring": "is",
      "context": "mobile",
      "filters": "genre:comedy",
      "sortBy": "price-low-to-high"
    }
  ],
  "consequence": {
    "behavior": {
      "injection": {
        "main": {
          "source": {
            "search": {
              "index": "Products",
              "params": {
                "advancedSyntax": false,
                "advancedSyntaxFeatures": [
                  "exactPhrase",
                  "excludeWords"
                ],
                "allowTyposOnNumericTokens": true,
                "alternativesAsExact": [
                  "ignorePlurals",
                  "singleWordSynonym"
                ],
                "attributeCriteriaComputedByMinProximity": false,
                "attributesToHighlight": [
                  "author",
                  "title",
                  "conten",
                  "content"
                ],
                "attributesToRetrieve": [
                  "author",
                  "title",
                  "content"
                ],
                "attributesToSnippet": [
                  "content:80",
                  "description"
                ],
                "clickAnalytics": false,
                "disableExactOnAttributes": [
                  "description"
                ],
                "disableTypoToleranceOnAttributes": [
                  "sku"
                ],
                "distinct": 1,
                "enableABTest": true,
                "enablePersonalization": false,
                "enableReRanking": true,
                "enableRules": true,
                "exactOnSingleWordQuery": "attribute",
                "facetFilters": [
                  [
                    "category:Book",
                    "category:-Movie"
                  ],
                  "author:John Doe"
                ],
                "filters": "(category:Book OR category:Ebook) AND _tags:published",
                "getRankingInfo": false,
                "highlightPostTag": "</em>",
                "highlightPreTag": "<em>",
                "ignorePlurals": [
                  "ca",
                  "es"
                ],
                "minProximity": 1,
                "minWordSizefor1Typo": 4,
                "minWordSizefor2Typos": 8,
                "naturalLanguages": [],
                "numericFilters": [
                  [
                    "inStock = 1",
                    "deliveryDate < 1441755506"
                  ],
                  "price < 1000"
                ],
                "optionalFilters": [
                  "category:Book",
                  "author:John Doe"
                ],
                "optionalWords": "lorem",
                "percentileComputation": true,
                "personalizationImpact": 100,
                "queryLanguages": [
                  "es"
                ],
                "queryType": "prefixLast",
                "removeStopWords": [
                  "ca",
                  "es"
                ],
                "removeWordsIfNoResults": "firstWords",
                "replaceSynonymsInHighlight": false,
                "responseFields": [
                  "*"
                ],
                "restrictHighlightAndSnippetArrays": false,
                "restrictSearchableAttributes": [
                  "title",
                  "author"
                ],
                "ruleContexts": [
                  "mobile"
                ],
                "snippetEllipsisText": "…",
                "synonyms": true,
                "typoTolerance": true,
                "facetingAfterDistinct": false,
                "facets": [
                  "category",
                  "disjunctive(brand)",
                  "price"
                ],
                "hitsPerPage": 20,
                "maxValuesPerFacet": 100,
                "renderingContent": {
                  "facetOrdering": {
                    "facets": {
                      "order": [
                        "lorem"
                      ]
                    },
                    "values": {
                      "property1": {
                        "order": [
                          "lorem"
                        ],
                        "sortRemainingBy": "count",
                        "hide": [
                          "lorem"
                        ]
                      },
                      "property2": {
                        "order": [
                          "lorem"
                        ],
                        "sortRemainingBy": "count",
                        "hide": [
                          "lorem"
                        ]
                      }
                    }
                  },
                  "redirect": {
                    "url": "lorem"
                  },
                  "widgets": {
                    "banners": [
                      {
                        "image": {
                          "urls": [
                            {
                              "url": "lorem"
                            }
                          ],
                          "title": "lorem"
                        },
                        "link": {
                          "url": "lorem"
                        }
                      }
                    ]
                  }
                },
                "sortFacetValuesBy": "count",
                "sumOrFiltersScores": false
              }
            }
          }
        },
        "injectedItems": [
          {
            "key": "lorem",
            "source": {
              "search": {
                "index": "Products",
                "params": {
                  "advancedSyntax": false,
                  "advancedSyntaxFeatures": [
                    "exactPhrase",
                    "excludeWords"
                  ],
                  "allowTyposOnNumericTokens": true,
                  "alternativesAsExact": [
                    "ignorePlurals",
                    "singleWordSynonym"
                  ],
                  "attributeCriteriaComputedByMinProximity": false,
                  "attributesToHighlight": [
                    "author",
                    "title",
                    "conten",
                    "content"
                  ],
                  "attributesToRetrieve": [
                    "author",
                    "title",
                    "content"
                  ],
                  "attributesToSnippet": [
                    "content:80",
                    "description"
                  ],
                  "clickAnalytics": false,
                  "disableExactOnAttributes": [
                    "description"
                  ],
                  "disableTypoToleranceOnAttributes": [
                    "sku"
                  ],
                  "distinct": 1,
                  "enableABTest": true,
                  "enablePersonalization": false,
                  "enableReRanking": true,
                  "enableRules": true,
                  "exactOnSingleWordQuery": "attribute",
                  "facetFilters": [
                    [
                      "category:Book",
                      "category:-Movie"
                    ],
                    "author:John Doe"
                  ],
                  "filters": "(category:Book OR category:Ebook) AND _tags:published",
                  "getRankingInfo": false,
                  "highlightPostTag": "</em>",
                  "highlightPreTag": "<em>",
                  "ignorePlurals": [
                    "ca",
                    "es"
                  ],
                  "minProximity": 1,
                  "minWordSizefor1Typo": 4,
                  "minWordSizefor2Typos": 8,
                  "naturalLanguages": [],
                  "numericFilters": [
                    [
                      "inStock = 1",
                      "deliveryDate < 1441755506"
                    ],
                    "price < 1000"
                  ],
                  "optionalFilters": [
                    "category:Book",
                    "author:John Doe"
                  ],
                  "optionalWords": "lorem",
                  "percentileComputation": true,
                  "personalizationImpact": 100,
                  "queryLanguages": [
                    "es"
                  ],
                  "queryType": "prefixLast",
                  "removeStopWords": [
                    "ca",
                    "es"
                  ],
                  "removeWordsIfNoResults": "firstWords",
                  "replaceSynonymsInHighlight": false,
                  "responseFields": [
                    "*"
                  ],
                  "restrictHighlightAndSnippetArrays": false,
                  "restrictSearchableAttributes": [
                    "title",
                    "author"
                  ],
                  "ruleContexts": [
                    "mobile"
                  ],
                  "snippetEllipsisText": "…",
                  "synonyms": true,
                  "typoTolerance": true
                }
              }
            },
            "position": 0,
            "length": 0,
            "metadata": {
              "hits": {
                "addItemKey": true,
                "extra": {}
              }
            }
          }
        ],
        "deduplication": {
          "positioning": "highest"
        }
      }
    }
  },
  "description": "Display a promotional banner",
  "enabled": true,
  "validity": [
    {
      "from": 42,
      "until": 42
    }
  ],
  "tags": [
    "conditional"
  ]
}
'

200

{
  "taskID": 1514562690001
}

Otherwise, a new one is added.

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

compositionID · string · required

Unique Composition ObjectID. Composition unique identifier.

Example:

"my_composition_object_id"

objectID · string · required

Unique identifier of a rule object.

Body

application/json

consequence · compositionRuleConsequence · object · required

Effect of the rule.

Show child attributes

objectID · string · required

Composition rule unique identifier.

Example:

"my_composition_rule_object_id"

conditions · object[]

Conditions that trigger a composition rule.

Maximum array length: 25

Show child attributes

description · string

Description of the rule's purpose to help you distinguish between different rules.

Example:

"Display a promotional banner"

enabled · boolean · default: true

Whether the rule is active.

tags · string[]

A list of tags.

Example:

["conditional"]

validity · object[]

Time periods when the rule is active.

Show child attributes

Response

200

application/json

OK

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