---
title: Batch
description: Batch protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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

<Callout type="info">
**Source:** `packages/spec/src/api/batch.zod.ts`
</Callout>

## TypeScript Usage

```typescript
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

* `create`
* `update`
* `upsert`
* `delete`


---

## 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 |


---

