Bulk delete in the FHIR service

The bulk delete capability enables you to delete resources from a FHIR® service asynchronously. The FHIR service supports bulk delete capability with two operations: $bulk-delete and $bulk-delete-soft-deleted. The $bulk-delete operation deletes resources in the FHIR service, except for soft deleted resources. To delete soft deleted FHIR resources, use the $bulk-delete-soft-deleted operation.

Configure headers and roles for bulk delete

Headers

Bulk delete capability header parameters are:

• Accept: application/fhir+json

• Prefer: respond-async

Role requirements

• Assign the FHIR Data Writer role to a user or application to perform the bulk delete capability.
• Assign the FHIR Data Contributor role to a user or application to perform bulk delete capability with a hard delete query parameter and bulk delete on soft deleted resources.

Bulk delete operation details

$bulk-delete operation

You can execute the $bulk-delete operation at the system level or for individual resource types.

• System level: When you execute the operation at the system level, you can delete FHIR resources across all the resource types on the FHIR server.

    DELETE  [base]/$bulk-delete
  

• Individual resource types: When you execute the operation for individual resource types, you can delete FHIR resources that map to the resource type in the URL.

    DELETE [base]/<Resource Type>/$bulk-delete
  

Parameters for bulk delete

Parameters allow you to control the behavior of the bulk delete operation and filter the resources that are deleted. Use these parameters to specify whether the delete is soft or hard, whether to purge history, exclude certain resource types, remove references, and filter resources by using FHIR search parameters.

All the parameters are optional.

Use bulk delete with FHIR search parameters

The $bulk-delete operation supports using FHIR service supported search parameters as query parameters. Singular deletes don't support extra parameters. When you use bulk delete with FHIR search parameters, consider using the same query in a FHIR search first, so that you can verify the data you want to delete.

Bulk delete resources with references

Use $bulk-delete with _include and _revinclude to bulk delete resources that have references. For more information about _include and _revinclude as search result parameters, see Include and RevInclude.

Here are some examples of using $bulk-delete with _include and _revinclude:

The following example uses _revinclude to bulk delete all Patient resources that were last updated before December 18, 2021, and all resources that reference those patients:

DELETE [base]/Patient/$bulk-delete?_lastUpdated=lt2021-12-18&_revinclude=*:* 

The following example uses _include to bulk delete all DiagnosticReport resources that were last updated before December 18, 2021, and all ServiceRequest resources referenced by those DiagnosticReport resources (via DiagnosticReport.basedOn relationship), and all Encounter resources referenced by those ServiceRequest resources (via ServiceRequest.encounters relationship):

DELETE [base]/DiagnosticReport/$bulk-delete?_lastUpdated=lt2021-12-12&_include=DiagnosticReport:based-on:ServiceRequest&_include:iterate=ServiceRequest:encounter

Bulk delete resources that aren't referenced

By using $bulk-delete with the _not-referenced parameter, you can search for and delete resources that no other resources reference.

This example bulk deletes all Patient resources that no Encounter resources list as a subject.

DELETE [base]/Patient/$bulk-delete?_not-referenced=Encounter:subject

This example bulk deletes all Patient resources that Encounter resources don’t reference in any field.

DELETE [base]/Patient/$bulk-delete?_not-referenced=Encounter:* 

This example bulk deletes all Patient resources that Encounter and DiagnosticReport resources don’t reference.

DELETE [base]/Patient/$bulk-delete?_not-referenced=Encounter:subject&_not-referenced=DiagnosticReport:subject

This example bulk deletes all Patient resources that no other resources reference.

DELETE [base]/Patient/$bulk-delete?_not-referenced=*:* 

$bulk-delete-soft-deleted operation

To delete soft-deleted resources within a FHIR service, use the $bulk-delete-soft-deleted operation. You can run this operation at the system level or for individual resource types.

Understand bulk delete operation responses

After you request to bulk delete FHIR resources, you receive a Content-Location header with the absolute URL of an endpoint for subsequent status requests, such as a polling endpoint.

Polling endpoint

A request to the polling endpoint returns one of four outcomes depending on the status of the bulk delete job. The FHIR response's OperationOutcome provides the outcome.

1. Jobs in progress: This outcome states the job is in progress. Status code 202.

2. Completed: This outcome states the job completed successfully. At completion, the response provides information about the number of resources deleted at the individual resource type level. Status code 200.

3. Canceled: This outcome states the user canceled the job and provides information on the number of resources deleted at the individual resource level. Status code 200.

4. Failed: This outcome states the job failed. Status code depends on the failure type.

Sample request and response for determining the status request:

{{fhir_url}}/_operations/bulk-delete/<job id>

Here's a sample response for a successfully completed delete job:

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "ResourceDeletedCount",
            "part": [
                {
                    "name": "Practitioner",
                    "valueInteger64": 10.0
                },
                {
                    "name": "Specimen",
                    "valueInteger64": 7.0
                },
                {
                    "name": "Device",
                    "valueInteger64": 3.0
                }
            ]
        }
    ]
}

Error messages

Here's a list of error messages that might occur if the bulk delete operation fails.

FAQ

What are the steps for resolution if my bulk delete job seems to be stuck?

To check if a bulk delete job is stuck, run a FHIR search with the same parameters as the bulk delete job and _summary=count. If the count of resources is going down, the job is working. You can also cancel the bulk delete job and try again.

Do API interactions see any latency when a bulk delete operation job is executed concurrently?

When you run a bulk delete operation, you might see increased latency on concurrent calls to the service. To avoid a latency increase, cancel the bulk delete job, and then rerun it during a period of lower traffic.

Use case example

You can use the various features of $bulk-delete together to satisfy different use cases. The following example shows how to use $bulk-delete for data retention.

Suppose you want to delete Patient data that's older than three years, along with all data that references that patient. You also want to delete Practitioner resources that no Patient resources reference.

You can achieve this use case with these two calls.

First, delete all Patient resources that are older than three years, along with all data that references that patient.

DELETE [base] /Patient/$bulk-delete?_lastUpdated=lt{date}&_revinclude=*:* 

Next, delete all Practitioner resources that no Patient resources reference.

DELETE [base]/Practitioner/$bulk-delete?_not-referenced=Patient:*

Related content

Supported FHIR features

FHIR REST API capabilities