Overview
The batch update endpoint allows you to update multiple documents in a single request using either an array of document IDs or a filter query. All matched documents are updated with the same field values.
Request
The name of the collection containing the documents to update
Array of document IDs to update. Either ids or filter must be provided.Maximum: 1000 IDs (configurable)
MongoDB-style filter query to match documents. Either ids or filter must be provided.
Object containing the fields to update and their new values
Update by IDs Example
{
"ids": [
"65f1a2b3c4d5e6f7a8b9c0d1",
"65f1a2b3c4d5e6f7a8b9c0d2",
"65f1a2b3c4d5e6f7a8b9c0d3"
],
"update": {
"status": "active",
"verified": true
}
}
Update by Filter Example
{
"filter": {
"department": "Engineering",
"status": "pending"
},
"update": {
"status": "active",
"approved_at": "2024-03-15T10:30:00Z"
}
}
Response
Number of documents that matched the filter criteria
Number of documents that were actually modified (may be less than matched if documents already had the update values)
Array of failures (currently unused for batch updates, reserved for future use)
Response Example
{
"matched": 15,
"modified": 12
}
Update Behavior
Automatic Fields
All updates automatically set:
updated_at: Current UTC timestampupdated_by: Authenticated user’s ID
From handlers_batch.go:427-428
Field-Level Permissions
Users cannot update fields in their role’s deny_write list. The operation is rejected if any denied field is included in the update.
From handlers_batch.go:363-373
Version Snapshots
For collections with versioning enabled, a snapshot of each document is saved before the update.
From handlers_batch.go:414-424
RBAC Filter Combination
The provided filter/IDs are combined with RBAC query filters to ensure users can only update documents they have permission to access.
From handlers_batch.go:408-411
Filter Query Syntax
The filter parameter supports MongoDB query operators:
{
"filter": {
"age": { "$gte": 18 },
"status": { "$in": ["active", "pending"] },
"created_at": { "$lt": "2024-01-01T00:00:00Z" }
},
"update": {
"category": "adult"
}
}
$eq, $ne: Equal, not equal$gt, $gte, $lt, $lte: Comparison operators$in, $nin: Array membership$and, $or, $not: Logical operators$exists: Field existence check
Validation
- Permission Check: User must have
update permission for the collection
- Schema Validation: Update data is validated against the schema (partial validation)
- Deny Write Fields: Update is rejected if it includes fields the user cannot modify
- Batch Size: Maximum 1000 IDs if using
ids parameter
Error Responses
Error code:
collection_not_found: Collection does not existforbidden: User lacks update permission or attempts to modify denied fieldsbad_request: Invalid request (missing ids/filter, empty update, invalid IDs)internal_error: Database operation failed
Human-readable error message
Error Example
{
"error": {
"code": "forbidden",
"message": "You don't have permission to modify this field",
"details": {
"field": "salary"
}
}
}
Code Reference
Implementation: pkg/api/handlers_batch.go:302-459