Skip to main content
PUT
/
{collection}
/
batch
Batch Update
curl --request PUT \
  --url https://api.example.com/{collection}/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "ids": [
    {}
  ],
  "filter": {},
  "update": {}
}
'
{
  "matched": 123,
  "modified": 123,
  "failed": [
    {}
  ],
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

​
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

​
collection
string
required
The name of the collection containing the documents to update
​
ids
array
Array of document IDs to update. Either ids or filter must be provided.Maximum: 1000 IDs (configurable)
​
filter
object
MongoDB-style filter query to match documents. Either ids or filter must be provided.
​
update
object
required
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

​
matched
integer
Number of documents that matched the filter criteria
​
modified
integer
Number of documents that were actually modified (may be less than matched if documents already had the update values)
​
failed
array
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 timestamp
  • updated_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"
  }
}
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

​
Validation

  1. Permission Check: User must have update permission for the collection
  2. Schema Validation: Update data is validated against the schema (partial validation)
  3. Deny Write Fields: Update is rejected if it includes fields the user cannot modify
  4. Batch Size: Maximum 1000 IDs if using ids parameter

​
Error Responses

​
error
object
​
code
string
Error code:
  • collection_not_found: Collection does not exist
  • forbidden: User lacks update permission or attempts to modify denied fields
  • bad_request: Invalid request (missing ids/filter, empty update, invalid IDs)
  • internal_error: Database operation failed
​
message
string
Human-readable error message
​
details
object
Additional error context

​
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