Batch Delete

Delete multiple documents matching IDs or filter criteria

DELETE /{collection}/batch

Batch Delete

cURL

curl --request DELETE \
  --url https://api.example.com/{collection}/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "ids": [
    {}
  ],
  "filter": {}
}
'

200

{
  "deleted": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Overview

The batch delete endpoint allows you to delete multiple documents in a single request using either an array of document IDs or a filter query. All matched documents are permanently deleted.

Request

collection · string · required

The name of the collection containing the documents to delete

ids · array

Array of document IDs to delete. Either ids or filter must be provided.

Maximum: 1000 IDs (configurable)

filter · object

MongoDB-style filter query to match documents to delete. Either ids or filter must be provided.

Delete by IDs Example

{
  "ids": [
    "65f1a2b3c4d5e6f7a8b9c0d1",
    "65f1a2b3c4d5e6f7a8b9c0d2",
    "65f1a2b3c4d5e6f7a8b9c0d3"
  ]
}

Delete by Filter Example

{
  "filter": {
    "status": "archived",
    "created_at": {
      "$lt": "2023-01-01T00:00:00Z"
    }
  }
}

Response

deleted · integer

Number of documents that were successfully deleted

Response Example

{
  "deleted": 47
}

Delete Behavior

Permanent Deletion

Deleted documents are permanently removed from the collection. For collections with versioning enabled, a snapshot is saved before deletion.

Version Snapshots

From handlers_batch.go:546-556:

For collections with versioning enabled, the current state of each document is saved as a version snapshot before deletion. This allows for potential recovery through the version history.

Hook Execution

From handlers_batch.go:559-595:

• Pre-delete hooks: Executed for each document before deletion (best-effort in batch mode)
• Post-delete hooks: Executed after successful deletion with the total deleted count
• Hook failures do not prevent the deletion from proceeding

RBAC Filter Combination

From handlers_batch.go:541-544:

The provided filter/IDs are combined with RBAC query filters to ensure users can only delete documents they have permission to access.

Filter Query Syntax

The filter parameter supports MongoDB query operators:

{
  "filter": {
    "status": "archived",
    "last_login": { "$lt": "2023-01-01T00:00:00Z" },
    "email_verified": false,
    "role": { "$in": ["guest", "trial"] }
  }
}

Supported operators:

• $eq, $ne: Equal, not equal
• $gt, $gte, $lt, $lte: Comparison operators
• $in, $nin: Array membership
• $and, $or, $not: Logical operators
• $exists: Field existence check
• $regex: Pattern matching

Safety Considerations

Batch delete is a destructive operation. Deleted documents cannot be recovered unless:

• Versioning is enabled for the collection
• You have a backup strategy in place

Best Practices

1. Test filters first: Use the Count endpoint to verify how many documents will be deleted
2. Use specific filters: Avoid overly broad filters that might delete more than intended
3. Enable versioning: Configure versioning for collections where you might need to recover deleted data
4. Implement soft deletes: Consider adding a deleted field and filtering it in queries instead of hard deletes

Validation

1. Permission Check: User must have delete permission for the collection
2. Request Validation: Either ids or filter must be provided (not both)
3. Batch Size: Maximum 1000 IDs if using ids parameter
4. RBAC Enforcement: Only documents the user has permission to delete are affected

Error Responses

error · object

code · string

Error code:

• collection_not_found: Collection does not exist
• forbidden: User lacks delete permission
• bad_request: Invalid request (missing ids/filter, invalid IDs, batch size exceeded)
• internal_error: Database operation failed

message · string

Human-readable error message

details · object

Additional error context

Error Examples

{
  "error": {
    "code": "bad_request",
    "message": "Either 'ids' or 'filter' must be provided"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "Batch size exceeds maximum limit of 1000",
    "details": {
      "max_batch_size": 1000,
      "requested": 1500
    }
  }
}

Audit Logging

All batch delete operations are logged to the audit trail with:

• User ID and roles
• Collection name
• Filter criteria or IDs
• Number of documents deleted
• Timestamp

From handlers_batch.go:597-602

Code Reference

Implementation: pkg/api/handlers_batch.go:461-610

Related Endpoints

• Batch Create - Create multiple documents
• Batch Update - Update multiple documents
• Count Documents - Count matching documents
• Delete Document - Delete a single document