Skip to content

batch.mdx

Latest commit

 

History

History
218 lines (136 loc) · 8.85 KB

batch.mdx

File metadata and controls

218 lines (136 loc) · 8.85 KB
Raw
title Batch
description Batch protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

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, CrossObjectBatchDroppedFields, CrossObjectBatchOperation, CrossObjectBatchRequest, CrossObjectBatchResponse, DeleteManyRequest, UpdateManyRequest } from '@objectstack/spec/api';
import type { BatchConfig, BatchOperationResult, BatchOperationType, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, CrossObjectBatchDroppedFields, CrossObjectBatchOperation, CrossObjectBatchRequest, CrossObjectBatchResponse, 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 { atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean } 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 { code: string; message: string; category?: string; details?: any; … }[] 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
droppedFields { object: string; fields: string[]; reason: Enum<'readonly' | 'readonly_when'> }[] optional Write-observability (#3407/#3431/#3455): caller-supplied fields LEGALLY stripped from THIS row before it was written — static readonly (#2948) / TRUE readonlyWhen (#3042) on update, or the #3043 create-ingress strip. Per-row because a batch can drop different fields on different rows (readonlyWhen is record-state-dependent). Present ONLY when ≥1 field was dropped for this row; the row still succeeded (success unchanged). A single response header cannot express per-row drops, so this body field is the canonical bulk channel — REST does not emit X-ObjectStack-Dropped-Fields for batches. Optional — omit-when-empty keeps the shape backward-compatible.

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 { id?: string; data?: Record<string, any>; externalId?: string }[] ✅ Array of records to process (max 200 per batch)
options { atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean } optional Batch operation options

BatchUpdateResponse

Properties

Property Type Required Description
success boolean ✅ Operation success status
error { code: string; message: string; category?: string; details?: any; … } optional Error details if success is false
meta { timestamp: string; duration?: number; requestId?: string; traceId?: string } 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 { id?: string; success: boolean; errors?: { code: string; message: string; category?: string; details?: any; … }[]; data?: Record<string, any>; … }[] ✅ Detailed results for each record

CrossObjectBatchDroppedFields

A cross-object batch strip event: dropped fields plus the operation index

Properties

Property Type Required Description
object string ✅ Object the write targeted (resolved object name)
fields string[] ✅ Caller-supplied field names the engine removed from the write payload
reason Enum<'readonly' | 'readonly_when'> ✅ Why the fields were dropped: static readonly (#2948) or a TRUE readonlyWhen predicate (#3042)
index integer ✅ Index of the operation in the request operations array

CrossObjectBatchOperation

Properties

Property Type Required Description
object string ✅ Target object (table) name
action Enum<'create' | 'update' | 'delete'> ✅ Operation to perform (default: create)
id string optional Target record id — required for update and delete
data Record<string, any> optional Record payload for create/update; a value may be { $ref: <opIndex> } to reference an earlier op's created id

CrossObjectBatchRequest

Properties

Property Type Required Description
operations { object: string; action: Enum<'create' | 'update' | 'delete'>; id?: string; data?: Record<string, any> }[] ✅ Ordered operations executed in one transaction
atomic boolean ✅ Always true — the cross-object batch is all-or-nothing

CrossObjectBatchResponse

Properties

Property Type Required Description
results any[] ✅ Per-operation result, index-aligned with the request operations
droppedFields { object: string; fields: string[]; reason: Enum<'readonly' | 'readonly_when'>; index: integer }[] optional Write-observability (#3407/#3431/#3455/#3794): caller-supplied fields the engine LEGALLY stripped from an operation before it was written — static readonly (#2948) or a TRUE readonlyWhen predicate (#3042). This endpoint is the console record form's save path (master-detail writes parent + children in one transaction), so without it the ONE surface where a user edits a readonlyWhen field reported plain success while the value never landed. Each event carries the index of its operation. Present ONLY when ≥1 field was dropped; the batch still committed without them (results/success semantics unchanged). Optional — omit-when-empty keeps the shape backward-compatible.

DeleteManyRequest

Properties

Property Type Required Description
ids string[] ✅ Array of record IDs to delete (max 200)
options { atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean } optional Delete options

UpdateManyRequest

Properties

Property Type Required Description
records { id?: string; data?: Record<string, any>; externalId?: string }[] ✅ Array of records to update (max 200 per batch)
options { atomic: boolean; returnRecords: boolean; continueOnError: boolean; validateOnly: boolean } optional Update options