feat(specs): add info and link about indexing rate limits (#4136)

Author: kai687

specs/search/paths/manage_indices/operationIndex.yml

@@ -10,6 +10,7 @@ post:
 
     - Existing destination indices are overwritten, except for their analytics data.
     - If the destination index doesn't exist yet, it'll be created.
+    - This operation is resource-intensive.
 
     **Copy**
 
@@ -28,6 +29,7 @@ post:
     - If the destination index has replicas, moving will overwrite the existing index and copy the data to the replica indices.
     - Related guide: [Move indices](https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices/how-to/move-indices/).
 
+    This operation is subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   requestBody:

specs/search/paths/objects/batch.yml

@@ -10,6 +10,8 @@ post:
 
     - Actions are applied in the order they're specified.
     - Actions are equivalent to the individual API requests of the same name.
+
+    This operation is subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   x-codegen-request-body-name: batchWriteParams

specs/search/paths/objects/clearObjects.yml

@@ -5,7 +5,9 @@ post:
   x-acl:
     - deleteIndex
   summary: Delete all records from an index
-  description: Deletes only the records from an index while keeping settings, synonyms, and rules.
+  description: |
+    Deletes only the records from an index while keeping settings, synonyms, and rules.
+    This operation is resource-intensive and subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   responses:

specs/search/paths/objects/deleteBy.yml

@@ -4,12 +4,19 @@ post:
   operationId: deleteBy
   x-acl:
     - deleteIndex
-  summary: Delete records matching a query
+  summary: Delete records matching a filter
   description: |
-    This operation doesn't accept empty queries or filters.
+    This operation doesn't accept empty filters.
 
+    This operation is resource-intensive.
+    You should only use it if you can't get the object IDs of the records you want to delete.
     It's more efficient to get a list of object IDs with the [`browse` operation](#tag/Search/operation/browse),
     and then delete the records using the [`batch` operation](#tag/Records/operation/batch).
+
+    This operation is subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
+  externalDocs:
+    url: https://support.algolia.com/hc/en-us/articles/16385098766353-Should-I-use-the-deleteby-method-for-deleting-records-matching-a-query-
+    description: Should I use the deleteBy method for deleting records.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   requestBody:

specs/search/paths/objects/multipleBatch.yml

@@ -7,6 +7,8 @@ post:
 
     - Actions are applied in the order they are specified.
     - Actions are equivalent to the individual API requests of the same name.
+
+    This operation is subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
   summary: Batch indexing operations on multiple indices
   requestBody:
     required: true

specs/search/paths/objects/objects.yml

@@ -14,6 +14,8 @@ post:
 
     To update _some_ attributes of a record, use the [`partial` operation](#tag/Records/operation/partialUpdateObject).
     To add, update, or replace multiple records, use the [`batch` operation](#tag/Records/operation/batch).
+
+    This operation is subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
   summary: Add or replace a record
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
@@ -51,7 +53,6 @@ post:
       $ref: '../../../common/responses/MethodNotAllowed.yml'
     '404':
       $ref: '../../../common/responses/IndexNotFound.yml'
-
 delete:
   tags:
     - Indices

specs/search/paths/objects/partialUpdate.yml

@@ -13,9 +13,10 @@ post:
       a new record is added to the index **if** `createIfNotExists` is true.
     - If the index doesn't exist yet, this method creates a new index.
     - You can use any first-level attribute but not nested attributes.
-      If you specify a nested attribute, the engine treats it as a replacement for its first-level ancestor.
+      If you specify a nested attribute, this operation replaces its first-level ancestor.
 
-    To update an attribute without pushing the entire record, you can use these built-in operations. These operations can be helpful if you don't have access to your initial data.
+    To update an attribute without pushing the entire record, you can use these built-in operations.
+    These operations can be helpful if you don't have access to your initial data.
 
     - Increment: increment a numeric attribute
     - Decrement: decrement a numeric attribute
@@ -29,6 +30,8 @@ post:
 
     - _operation: the operation to apply on the attribute
     - value: the right-hand side argument to the operation, for example, increment or decrement step, value to add or remove.
+
+    This operation is subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: '../../../common/parameters.yml#/ObjectID'

specs/search/paths/rules/saveRules.yml

@@ -10,6 +10,8 @@ post:
 
     If a rule with the specified object ID doesn't exist, Algolia creates a new one.
     Otherwise, existing rules are replaced.
+
+    This operation is subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
   x-codegen-request-body-name: rules
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'

specs/search/paths/synonyms/saveSynonyms.yml

@@ -8,6 +8,8 @@ post:
   description: |
     If a synonym with the `objectID` doesn't exist, Algolia adds a new one.
     Otherwise, existing synonyms are replaced.
+
+    This operation is subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: '../../../common/parameters.yml#/ForwardToReplicas'

specs/search/spec.yml

@@ -161,6 +161,7 @@ tags:
       Records are individual items in your index.
       When they match a search query, they're returned as search results, in the order determined by your ranking.
       Records are schemaless JSON objects.
+      When adding or updating many records, check the [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
     externalDocs:
       url: https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/
       description: |