Delete data in bulk

The bulk deletion feature in Microsoft Dataverse helps you maintain data quality and manage the consumption of system storage by deleting data you no longer need. For example, you can delete the following data in bulk:

• Stale data
• Data that's no longer relevant to the business
• Unneeded test or sample data
• Data incorrectly imported from other systems

You can perform the following operations:

• Delete data across multiple tables.
• Delete records in a specific table.
• Receive email notifications when a bulk deletion finishes.
• Delete data periodically.
• Schedule the start time of a recurring bulk delete.
• Retrieve information about failures that occurred during a bulk deletion.

To delete multiple rows in elastic tables, you can also use the DeleteMultiple message. DeleteMultiple deletes records in a single elastic immediately, rather than using a bulk delete job.

Run bulk delete

To delete data in bulk, use the BulkDelete message to submit a bulk delete job. By using the SDK, use the BulkDeleteRequest class. By using the Web API, use the BulkDelete action. Specify the query expressions that describe the records to delete in the QuerySet property of your request.

A bulk delete job is represented by a record in the Bulk Delete Operation (BulkDeleteOperation) table. A bulk delete operation record includes the following information:

• The number of records the job deleted
• The number of records the job failed to delete
• Whether the job is set to recur
• The start time of the job

The bulk delete job runs asynchronously without blocking other activities. It only deletes records that were created before the job starts to run. The job deletes the specified records according to cascading rules based on table relationship cascading behavior.

If a bulk delete job fails or ends prematurely, the operation doesn't roll back any deleted records. The record data remains deleted. A record of failures is stored in the Bulk Delete Failure (BulkDeleteFailure) table. You can retrieve information from the table about the error that caused the failure.

To run a bulk delete job, you must have BulkDelete and Delete privileges on the table types you're deleting. You must also have read permissions on the table records that you specify in the QuerySet property. A system administrator has the necessary permissions by default. Grant them to other users.

You can perform a bulk deletion on all tables that support the Delete message.

If the delete action on a specific table type triggers a plug-in or a workflow (process), the bulk delete job triggers the plug-in or workflow every time it deletes a table record of that type.

Control bulk delete processing

The Options parameter on the BulkDelete action controls how the bulk delete job processes table rows (records). Use the parameter to:

• Turn off deleted record keeping for bulk-deleted records. Turning off deleted record keeping improves performance by skipping the overhead of storing deleted records for recovery.
• Enable sandbox fast delete mode to bypass the standard SDK pipeline (plug-ins, workflows, deleted record keeping). Fast delete achieves higher deletion throughput. This property is supported only in sandbox environments. When used on other environment types, including production, deletions follow the standard process and honor plug-ins, workflows, and deleted record keeping policies.

Note

Support for the ability to use the new Options parameter with the SDK for .NET to control bulk delete processing is planned for a future release.

Use the Options parameter

The Options parameter accepts a BulkDeleteOptions object with the following properties.

Property	Type	Default	Description
CanRecoverDeletedRecords	Boolean	null (deleted record keeping turned-on)	When set to false, records deleted by the bulk delete job are permanently removed and can't be recovered. If deleted record keeping is already turned-off for the environment, setting CanRecoverDeletedRecords as true will not keep deleted records for this job for later recovery.
RunJobForSandbox	Boolean	null (standard pipeline)	When set to true, the bulk delete job uses the high-performance sandbox delete mode, bypassing plug-ins, workflows, and deleted record keeping. This property is particularly useful for removing large volumes of data from sandbox environments after a production copy. Supported only in sandbox environments. When used on other environment types, including production, deletions follow the standard process and honor plug-ins, workflows, and deleted record keeping policies.

Warning

Don't run the examples shown in this article as written. Modify the example code as appropriate for your development environment. Some of these examples delete all accounts, which is not something you want to do.

Example: Options parameter

The following examples demonstrate how to use the Options parameter with the BulkDelete action.

Use the Options property in the request body of the BulkDelete action. The Options parameter is a BulkDeleteOptions complex type.

Request:

POST [Organization Uri]/api/data/v9.2/BulkDelete HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json

{
    "QuerySet": [
        {
            "@odata.type": "Microsoft.Dynamics.CRM.QueryExpression",
            "EntityName": "account",
            "ColumnSet": {
                "AllColumns": true
            },
            "Distinct": false
        }
    ],
    "JobName": "Delete all accounts",
    "SendEmailNotification": false,
    "ToRecipients": [],
    "CCRecipients": [],
    "RecurrencePattern": "",
    "StartDateTime": "2026-03-13T06:30:00Z",
    "Options": {
        "CanRecoverDeletedRecords": true,
        "RunJobForSandbox": false
    }
}

Response:

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.BulkDeleteResponse",
    "JobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Options parameter values

Scenario	CanRecoverDeletedRecords	RunJobForSandbox	Effect
Default (standard delete)	true or omitted	false or omitted	Records continue to use the standard deletion pipeline. If deleted record keeping is already turned-off for the environment, setting CanRecoverDeletedRecords as true will not keep deleted records for this job for later recovery.
Skip deleted record keeping	false	false or omitted	Records continue to use the standard deletion pipeline but bypasses deleted record keeping for the job. If deleted record keeping is already enabled for the environment, setting CanRecoverDeletedRecords to false bypasses deleted record keeping for this specific job.
Sandbox fast delete	false	true	Bypasses deleted record keeping and SDK pipeline. Maximum throughput.

Control deleted record keeping behavior

By default, when you enable deleted record keeping for your environment, the system keeps all records that a bulk delete job deletes before it deletes them. Deleted record keeping helps administrators recover accidentally deleted records, but it adds significant I/O overhead for each deleted record. To bypass deleted record keeping for a bulk delete job, set CanRecoverDeletedRecords to false in the Options parameter. This setting can approximately double the deletion throughput by eliminating the overhead of:

• Creating DeletedItemReference records
• Copying record data to bin storage tables for later recovery
• Updating restore data blobs for each deleted record

Warning

When you set CanRecoverDeletedRecords to false, the bulk delete job permanently removes deleted records and can't recover them. This action is irreversible. Ensure that you verified the query criteria and have appropriate backups before running a bulk delete job with this option. This setting only affects the current bulk delete job; it doesn't change the environment-level deleted record keeping configuration.

Example: Disable deleted record keeping for faster deletion

Permanently delete records without storing them for later recovery.

POST [Organization Uri]/api/data/v9.2/BulkDelete HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json

{
    "QuerySet": [
        {
            "@odata.type": "Microsoft.Dynamics.CRM.QueryExpression",
            "EntityName": "account",
            "ColumnSet": {
                "AllColumns": true
            },
            "Distinct": false
        }
    ],
    "JobName": "Delete accounts - skip recycle bin",
    "SendEmailNotification": false,
    "ToRecipients": [],
    "CCRecipients": [],
    "RecurrencePattern": "",
    "StartDateTime": "2026-03-13T06:30:00Z",
    "Options": {
        "CanRecoverDeletedRecords": false
    }
}

Sandbox fast delete

For scenarios that require maximum deletion throughput, set RunJobForSandbox to true to enable sandbox fast delete mode. In this mode, the bulk delete job bypasses the standard SDK pipeline entirely and uses direct cascade engine deletion, so you get higher throughput.

Important

This property is particularly useful for removing large volumes of data from sandbox environments after a production copy. It's supported only in sandbox environments. When used on other environment types, including production, deletions follow the standard process and honor plug-ins, workflows, and deleted record keeping policies.

When sandbox fast delete is enabled, the following operations are skipped:

• Preoperation and post-operation plug-in execution
• Synchronous and asynchronous workflow triggers
• Deleted record keeping (records are permanently deleted)
• Custom business logic registered on the Delete message

The process preserves the following elements when it performs fast delete:

• Cascade delete rules based on table relationship configuration
• Referential integrity (foreign key relationships)
• Security privilege checks
• Sync change tracking for downstream replication

Important

Sandbox fast delete mode bypasses the entire Event Framework plug-in pipeline. Any custom plug-ins, workflows, or business logic registered on the Delete message don't execute for records deleted in this mode. This restriction includes audit plug-ins, integration plug-ins, and any custom validation logic. Additionally, you can't recover records deleted in sandbox mode. Use this option only when you're certain that no critical business logic depends on delete-time plug-in execution, and that permanent, irrecoverable deletion is acceptable.

Example: Sandbox fast delete

Learn how to use high-performance sandbox delete mode for maximum throughput.

POST [Organization Uri]/api/data/v9.2/BulkDelete HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json

{
    "QuerySet": [
        {
            "@odata.type": "Microsoft.Dynamics.CRM.QueryExpression",
            "EntityName": "account",
            "ColumnSet": {
                "AllColumns": true
            },
            "Distinct": false
        }
    ],
    "JobName": "Delete accounts - sandbox fast delete",
    "SendEmailNotification": false,
    "ToRecipients": [],
    "CCRecipients": [],
    "RecurrencePattern": "",
    "StartDateTime": "2026-03-13T06:30:00Z",
    "Options": {
        "CanRecoverDeletedRecords": false,
        "RunJobForSandbox": true
    }
}

Long-term retained data

Bulk deletion is also available for long-term retained data. Run a bulk delete as you normally would, but set the query's DataSource field to retained.

Set the QueryExpression DataSource property to retained in a Web API BulkDelete action to indicate the query is for retained rows only.

Request:

POST [Organization Uri]/api/data/v9.2/BulkDelete HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json

{
    "QuerySet": 
    [
        {
            "EntityName": "contact",
            "DataSource": "retained",
            "Criteria":
            {
                "FilterOperator": "And",
                "Conditions": 
                [
                    {
                        "AttributeName": "firstname",
                        "Operator": "Equal",
                        "Values" : [{"Value":"Bob","Type":"System.String"}]
                    }
                ]
            }
        }
    ],
    "JobName": "Bulk Delete Retained Contacts",
    "SendEmailNotification": false,
    "RecurrencePattern": "",
    "StartDateTime": "2023-03-07T05:00:00Z",
    "ToRecipients": [],
    "CCRecipients": []
}

Response:

HTTP/1.1 200 OK
{
    "@odata.context": "[Organization Uri]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.BulkDeleteResponse",
    "JobId": "3093d67f-21f0-ed11-8b48-6045bdd92a32"
}

Samples

To learn more about the bulk delete feature, see the following SDK for .NET samples:

• Sample: Bulk delete exported records
• Sample: Bulk delete records that match common criteria

See also

• Long-term data retention
• BulkDelete Action reference
• Delete data in bulk
• Restore deleted records
• Use Web API actions
• BulkDeleteOperation table reference