Reset Documents (Preview REST API)
Applies to: 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview, 2019-05-06-Preview
Important
2023-07-01-Preview (no changes).
2021-04-30-Preview (no changes).
2020-06-30-Preview (no changes).
2019-05-06-Preview adds support for reset scenarios.
Reset Documents is an asynchronous API. It allows you to selectively reprocess documents from your data source.
The API accepts two types of document identifiers as input. They are document keys (keys that uniquely identify documents in a search index) and datasource document identifiers (keys that uniquely identify documents in a data source). Invoking the API adds the document keys or data source document identifiers to be reset to the indexer metadata. On the next scheduled or on-demand run of the indexer, the indexer processes only the reset documents.
- For indexers with a skillset and incremental enrichment enabled, the API clears the cache and rerun the full skillset for just the specified documents.
- For indexers without a skillset, the API reads the source document from the data source and update/insert the contents into the index.
If you use document keys to reset documents and your document keys are referenced in an indexer field mapping, the indexer uses field mapping to locate the appropriate field in the underlying data source.
The API works for all indexers (with or without a skillset). You can invoke it using an HTTP POST request. If the call succeeds, you get a 204 NoContent response. Specify the name of the indexer to update on the request URI:
POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
URI Parameters
| Parameter | Description |
|---|---|
| service name | Required. Set this to the unique, user-defined name of your search service. |
| indexer name | Required. The request URI specifies the name of the indexer to update. |
| api-version | Required. The current preview version is 2023-07-01-Preview. See API versions for more versions. |
| overwrite | Optional. This parameter determines whether consecutive Reset Document operations are combined or overwritten. Default is false. When false, the call’s payload of document keys or data source document identifiers are added to the list of keys already queued up for reprocessing. If true, the call’s payload of document keys or data source document identifiers overwrite the existing list, including clearing the list of reset documents if you set the keys to null. |
Request Headers
The following table describes the required and optional request headers.
| Fields | Description |
|---|---|
| Content-Type | Required. Set this to application/json |
| api-key | Optional if you're using Azure roles and a bearer token is provided on the request, otherwise a key is required. An api-key is a unique, system-generated string that authenticates the request to your search service. Reset requests must include an api-key header set to your admin key (as opposed to a query key). See Connect to Azure AI Search using key authentication for details. |
Request Body
The body should contain either a list of document keys or a list of data source document identifiers that the indexer looks for in the data source.
The following JSON is a high-level representation of the main parts of the definition.
{
"documentKeys" : [
"key1",
"key2",
"key3"
],
"datasourceDocumentIds" : [
"key1",
"key2",
"key3"
],
}
Request contains the following properties and note that one and only one of "documentKeys" and "datasourceDocumentIds" should be provided:
| Property | Description |
|---|---|
| documentKeys | This is the set of document keys the indexer selectively reprocesses from its data source. By default, calling this action multiple times appends the document key sets together. This behavior can be changed to overwrite rather than append via the overwrite URI parameter (see above). If you want the indexer to stop trying to process reset documents, you can set "documentKeys" to an empty list "[]". This results in the indexer resuming regular indexing based on the high water mark. Invalid document keys or document keys that don't exist are ignored. |
| datasourceDocumentIds | This is the set of data source document identifiers the indexer selectively reprocesses from its data source. By default, calling this action multiple times appends the data source document identifiers sets together. This behavior can be changed to overwrite rather than append via the overwrite URI parameter (see above). If you want the indexer to stop trying to process reset documents, you can set "datasourceDocumentIds" to an empty list "[]". This results in the indexer resuming regular indexing based on the high water mark. Invalid data source document identifiers or data source document identifiers that don't exist are ignored. |
Response
204 No Content for a successful request.