ObjectStackBatch
Batch protocol schemas
Batch Operations API
Provides efficient bulk data operations with transaction support.
Implements P0/P1 requirements for ObjectStack kernel.
Features:
-
Batch create/update/delete operations
-
Atomic transaction support (all-or-none)
-
Partial success handling
-
Detailed error reporting per record
Industry alignment: Salesforce Bulk API, Microsoft Dynamics Bulk Operations
Source: packages/spec/src/api/batch.zod.ts
TypeScript Usage
import { BatchConfig, BatchOperationResult, BatchOperationType, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, DeleteManyRequest, UpdateManyRequest } from '@objectstack/spec/api';
import type { BatchConfig, BatchOperationResult, BatchOperationType, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, DeleteManyRequest, UpdateManyRequest } from '@objectstack/spec/api';
// Validate data
const result = BatchConfig.parse(data);BatchConfig
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| enabled | boolean | ✅ | Enable batch operations |
| maxRecordsPerBatch | integer | ✅ | Maximum records per batch |
| defaultOptions | Object | optional | Default batch options |
BatchOperationResult
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | optional | Record ID if operation succeeded |
| success | boolean | ✅ | Whether this record was processed successfully |
| errors | Object[] | optional | Array of errors if operation failed |
| data | Record<string, any> | optional | Full record data (if returnRecords=true) |
| index | number | optional | Index of the record in the request array |
BatchOperationType
Allowed Values
createupdateupsertdelete
BatchOptions
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| atomic | boolean | ✅ | If true, rollback entire batch on any failure (transaction mode) |
| returnRecords | boolean | ✅ | If true, return full record data in response |
| continueOnError | boolean | ✅ | If true (and atomic=false), continue processing remaining records after errors |
| validateOnly | boolean | ✅ | If true, validate records without persisting changes (dry-run mode) |
BatchRecord
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| id | string | optional | Record ID (required for update/delete) |
| data | Record<string, any> | optional | Record data (required for create/update/upsert) |
| externalId | string | optional | External ID for upsert matching |
BatchUpdateRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| operation | Enum<'create' | 'update' | 'upsert' | 'delete'> | ✅ | Type of batch operation |
| records | Object[] | ✅ | Array of records to process (max 200 per batch) |
| options | Object | optional | Batch operation options |
BatchUpdateResponse
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | Object | optional | Error details if success is false |
| meta | Object | optional | Response metadata |
| operation | Enum<'create' | 'update' | 'upsert' | 'delete'> | optional | Operation type that was performed |
| total | number | ✅ | Total number of records in the batch |
| succeeded | number | ✅ | Number of records that succeeded |
| failed | number | ✅ | Number of records that failed |
| results | Object[] | ✅ | Detailed results for each record |
DeleteManyRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| ids | string[] | ✅ | Array of record IDs to delete (max 200) |
| options | Object | optional | Delete options |
UpdateManyRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| records | Object[] | ✅ | Array of records to update (max 200 per batch) |
| options | Object | optional | Update options |