Delete documents in a search index

This article explains how to delete whole documents from a search index on Azure AI Search using REST APIs or Azure SDKs. It covers these tasks:

Understand when manual deletion is required
Identify specific documents to delete
Get document counts and storage metrics
Delete a single or orphaned document
Delete documents in bulk
Confirm deletion

Tip

For a quick single-document delete, skip to Delete a single document.

Prerequisites

An Azure AI Search service (any tier). Create a service or find an existing one.
An existing search index with documents to delete. This article assumes you already created an index and loaded documents.
Permissions to delete documents:
- Key-based authentication: An admin API key for your search service.
- Role-based authentication: Search Index Data Contributor role or the Microsoft.Search/searchServices/indexes/documents/delete permission.
For SDK development, install the Azure Search client library:
- Python: azure-search-documents
- .NET: Azure.Search.Documents
- JavaScript: @azure/search-documents
- Java: azure-search-documents

Understand when manual deletion is required

Manual document deletion is necessary when you use the push mode approach to indexing, where application code handles data import and drives indexing.

You might also need manual document deletion in indexer-driven workloads if search documents become "orphaned" from source documents. An important benefit of indexers is automated content retrieval and synchronization via the change and deletion detection features of the target data source. All of the supported data sources provide some level of detection. But in some cases, synchronized deletion is predicated on a soft-delete strategy where you flag a source document (or record) for deletion, run the indexer to delete the indexed content, and only after the index is updated do you physically delete the source content. If source content is deleted first, you have orphan documents in the search index. You must manually delete orphan documents in your index to re-establish parity between source and indexed content.

The following links provide more information about change and deletion detection for each data source in indexer-driven workloads.

Identify specific documents for deletion

All documents are uniquely identified by a document key in a search index. To delete a document, you must identify which field is the document key and provide the key on the deletion request.

In the Azure portal, you can view the fields of each index. Document keys are string fields and are denoted with a key icon to make them easier to spot.

Find the document key

Once you know which field is the document key, you can get the key value by running a query that returns the key field in the search results.

In this example, the search string is used to find the document in the index, and the select statement determines what fields are in the results. The "HotelId" is the document key in this example.

POST https://[service name].search.azure.cn/indexes/hotels-sample-index/docs/search?api-version=2025-09-01
{
    "search": "this query has terms that pertain to the document I want to delete",
    "select": "HotelName, HotelId",
    "count": true
}

Results for this keyword search are the top 50 by default. If the document you want to delete satisfies the search criteria, you should see it (and it's key) in the results. Make sure the query includes a descriptive field that helps you confirm you have the correct document.

{
  "@odata.count": 50,
  "value": [
    {
      "@search.score": 4.5116634,
      "HotelId": "18",
      "HotelName": "Ocean Water Resort & Spa"
    }
   ...
  ]
}

A simple string is straightforward, but if the index uses a base-64 encoded field, or if search documents were generated from a parsingMode setting, you might be working with values that you aren't familiar with. If you're working with chunked documents create by an indexer, the document key is often a generated "chunked_id" composed of a long sequence of numbers and letters.

Look up a specific document

Now that you have the document key, run a look up query that retrieves the entire document. If the document is a chunk, you should see the ID of the parent document. The document key is included as a query parameter.

The first example returns the hotel having a document key value of 18.

GET https://[service name].search.azure.cn/indexes/hotels-sample-index/docs('18')&api-version=2025-09-01

The second example returns a chunk document. The "chunk_id" is the document key.

GET https://[service name].search.azure.cn/indexes/chunking-example-index/docs('aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb')&api-version=2025-09-01

The response from the second example includes all fields, which you should review to ensure you know what you're deleting. Fields that include parent information are useful if you need to manually reindex a single parent document into constituent chunked documents in the search index.

{
  "chunk_id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "parent_id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "chunk": "Unpopulated Slopes of an Active Volcano\u2014Naples, Italy ... 90\n\nDazzling Coastlines\u2014Italy ... .92\n\nLiving on Fertile Land\u2014Nile River, Egypt  ... 94\n\n\n\n vii",
  "title": "earth_at_night_508.pdf",
  "text_vector": [ <omitted> ]
}

Tip

Use a REST client, an Azure SDK client library, or a command line tool to run a lookup query. The Azure portal doesn't support GET requests for a query.

Get document counts and storage metrics

Before you delete documents, get initial metrics for the index document count and storage so that you can confirm deletion later.

You can get document counts and index storage using:

The Azure portal, under Search management > Indexes.
The Indexes - Get Statistics REST API

Here's an example response:

{
  "documentCount": 12,
  "storageSize": 123456,
  "vectorIndexSize": 123456
}

Delete a single document

Use the Documents - Index REST API with a delete @search.action to remove it from the search index.
Formulate a POST call specifying the index name and the docs/index endpoint.

Make sure the body of the request includes the key of the document you want to delete.

POST https://[service name].search.azure.cn/indexes/hotels-sample-index/docs/index?api-version=2025-09-01
Content-Type: application/json   
api-key: [admin key]

{  
  "value": [  
    {  
      "@search.action": "delete",  
      "id": "18"  
    }  
  ]  
}

Send the request.

The following table explains the various per-document status codes that can be returned in the response. Some status codes indicate problems with the request itself, while others indicate temporary error conditions. The latter you should retry after a delay.

Status code	Meaning	Retryable	Notes
200	Document was successfully deleted.	n/a	Delete operations are idempotent. That is, even if a document key doesn't exist in the index, attempting a delete operation with that key results in a 200 status code.
400	There was an error in the document that prevented it from being deleted.	No	The error message in the response provides details.
422	The index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'.	Yes	Wait for index to become available.
503	Your search service is temporarily unavailable, possibly due to heavy load.	Yes	Your code should wait before retrying in this case or you risk prolonging the service unavailability.

Note

If your client code frequently encounters a 207 response, one possible reason is that the system is under load. You can confirm this by checking the statusCode property for 503. If so, we recommend throttling indexing requests. Otherwise, if indexing traffic doesn't subside, the system could start rejecting all requests with 503 errors.

You can resend the Lookup query to confirm the deletion. You should get a 404 document not found message.
```
GET https://[service name].search.azure.cn/indexes/hotel-sample-index/docs/18?api-version=2025-09-01
```

Reference: Documents - Index

A successful delete request returns HTTP 200 (OK). The response body contains status for each document:

{
    "value": [
        { "key": "18", "status": true, "statusCode": 200 }
    ]
}

The following example deletes a document from an index:

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample-index"
api_key = "<your-admin-api-key>"

endpoint = f"https://{service_name}.search.azure.cn"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Delete a document by key
result = client.delete_documents(documents=[{"HotelId": "18"}])
print(f"Deleted {len(result)} document(s)")

Reference: SearchClient, delete_documents

The following example deletes a document from an index:

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample-index";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.azure.cn");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Delete a document by key
var batch = IndexDocumentsBatch.Delete("HotelId", new[] { "18" });
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(batch);

Console.WriteLine($"Deleted {result.Results.Count} document(s)");

Reference: SearchClient, IndexDocumentsAsync, IndexDocumentsBatch

Delete documents in bulk

Use the Documents - Index REST API with a delete @search.action to remove it from the search index. Formulate a POST call specifying the index name and the docs/index endpoint.

Make sure the body of the request includes the keys of all of the documents you want to delete.

POST https://[service name].search.azure.cn/indexes/hotels-sample-index/docs/index?api-version=2025-09-01
Content-Type: application/json   
api-key: [admin key]

{
  "value": [
    {
      "@search.action": "delete",
      "id": "doc1"
    },
    {
      "@search.action": "delete",
      "id": "doc2"
    }
  ]
}

Batch limits: It is recommended to limit batches to 1,000 documents or roughly 16 MB per request to ensure optimal performance.
Idempotency: Deletion is idempotent; if you attempt to delete a document ID that does not exist, the API will still return a 200 OK status.
Latency: Documents are not always removed instantly from storage. A background process performs the physical deletion every few minutes.
Vector storage: Deleting documents does not immediately free up vector storage quotas. It takes several minutes for physical deletion. For immediate reclamation of vector space, you may need to drop and rebuild the index.

Reference: Documents - Index

The following example deletes multiple documents in bulk:

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample-index"
api_key = "<your-admin-api-key>"

endpoint = f"https://{service_name}.search.azure.cn"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Delete multiple documents by key
documents_to_delete = [
    {"HotelId": "doc1"},
    {"HotelId": "doc2"},
    {"HotelId": "doc3"}
]
result = client.delete_documents(documents=documents_to_delete)
print(f"Deleted {len(result)} document(s)")

Reference: SearchClient, delete_documents

The following example deletes multiple documents in bulk:

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample-index";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.azure.cn");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Delete multiple documents by key
var batch = IndexDocumentsBatch.Delete("HotelId", new[] { "doc1", "doc2", "doc3" });
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(batch);

Console.WriteLine($"Deleted {result.Results.Count} document(s)");

Reference: SearchClient, IndexDocumentsAsync, IndexDocumentsBatch

Verify document deletion

After deleting documents, verify the deletion was successful.

In the Azure portal, open the search service Overview page.
Select Search management > Indexes.
Check the Document count column for your index.
Wait a few minutes and refresh if the count hasn't changed (deletion is asynchronous).

Use the Get Document API to confirm the document no longer exists:

GET https://[service-name].search.azure.cn/indexes/hotels-sample-index/docs/18?api-version=2025-09-01
api-key: [admin-key]

Expected response: HTTP 404 Not Found if the document was deleted successfully.

You can also check index statistics:

GET https://[service-name].search.azure.cn/indexes/hotels-sample-index/stats?api-version=2025-09-01
api-key: [admin-key]

# Python - verify document was deleted
try:
    document = client.get_document(key="18")
    print("Document still exists")
except Exception as e:
    print(f"Document not found (expected): {e}")

// C# - verify document was deleted
try
{
    var document = await searchClient.GetDocumentAsync<Hotel>("18");
    Console.WriteLine("Document still exists");
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine("Document not found (expected)");
}

Deleting a document doesn't immediately free up space in the index. Every few minutes, a background process performs the physical deletion. Whether you use the Azure portal or the Get Statistics API to return index statistics, you can expect a small delay before the deletion is reflected in the Azure portal and API metrics.

Troubleshoot document deletion

The following table lists common issues when deleting documents and how to resolve them.

Issue	Cause	Resolution
Document count unchanged	Deletion is asynchronous. Background process runs every few minutes.	Wait 2-3 minutes and refresh. Check index statistics again.
400 Bad Request	Invalid document key or malformed request body.	Verify the document key field name matches your index schema. Check JSON syntax.
403 Forbidden	Insufficient permissions.	Use an admin API key or ensure your identity has Search Index Data Contributor role.
404 Not Found on index	Index name is incorrect or doesn't exist.	Verify the index name in your request URL.
Storage not reclaimed	Physical deletion happens asynchronously in background.	Wait several minutes. For immediate vector storage reclamation, drop and rebuild the index.
Orphaned documents remain	Source documents deleted before indexer ran with deletion detection.	Manually delete orphaned documents using their document keys.