<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "CloudKitJS",
  "identifier" : "/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "CloudKit JS"
    ],
    "preciseIdentifier" : "cl/CloudKit.RecordsBatchBuilder"
  },
  "title" : "CloudKit.RecordsBatchBuilder"
}
-->

# CloudKit.RecordsBatchBuilder

A [`CloudKit.RecordsBatchBuilder`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder) object encapsulates the results of changes to multiple records in a single database operation.

```
interface CloudKit.RecordsBatchBuilder
```

## Overview

It is more efficient to use this class to batch multiple record changes into a single operation than to use the individual record change methods in the [`CloudKit.Database`](/documentation/CloudKitJS/CloudKit.Database) class. Using this class is especially important if the record types contain `Reference` fields. CloudKit ensures that in a graph of related records, target records are saved before source records.

You should not create instances of this class directly. Instead use the [`newRecordsBatch`](/documentation/CloudKitJS/CloudKit.Database/newRecordsBatch) method in the [`CloudKit.Database`](/documentation/CloudKitJS/CloudKit.Database) class to get a [`CloudKit.RecordsBatchBuilder`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder) object. Then use the create, replace, and delete methods in this class to build the batch operation. Use the [`commit`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder/commit) method to execute the batch operation.

For convenience, most methods in this class that add operations return the [`CloudKit.RecordsBatchBuilder`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder) object so that you can chain method calls together; for example:

```javascript
myDatabase.newRecordsBatch()
    .create(someRecord)
    .update(someOtherRecord)
    .delete(aThirdRecord)
    .commit()
```

For similar web service operations, read [Modifying Records (records/modify)](https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/ModifyRecords.html#//apple_ref/doc/uid/TP40015240-CH2) in [CloudKit Web Services Reference](https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/index.html#//apple_ref/doc/uid/TP40015240).

## Topics

### Creating and Updating Records

[`CloudKit.RecordsBatchBuilder create(
	CloudKit.Record|CloudKit.Record[] records,
	optional Object options
);`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder/create)

Creates one or more records.

[`CloudKit.RecordsBatchBuilder createOrUpdate(
	CloudKit.Record|CloudKit.Record[] records,
	optional Object options
);`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder/createOrUpdate)

Creates or updates one or more records depending on the information provided.

[`CloudKit.RecordsBatchBuilder update(
	CloudKit.Record|CloudKit.Record[] records,
	optional Object options
);`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder/update)

Updates one or more existing records.

[`CloudKit.RecordsBatchBuilder forceUpdate(
	CloudKit.Record|CloudKit.Record[] records,
	optional Object options
);`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder/forceUpdate)

Updates one or more existing records regardless of conflicts.

### Replacing Records

[`CloudKit.RecordsBatchBuilder replace(
	CloudKit.Record|CloudKit.Record[] records,
	optional Object options
);`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder/replace)

Replaces one or more records with the specified records.

[`CloudKit.RecordsBatchBuilder forceReplace(
	CloudKit.Record|CloudKit.Record[] records,
	optional Object options
);`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder/forceReplace)

Replaces one or more records with the specified records regardless of conflicts.

### Deleting Records

[`CloudKit.RecordsBatchBuilder delete(
	CloudKit.Record|CloudKit.Record[] records
);`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder/delete)

Deletes one or more records.

[`RecordsBatchBuilder forceDelete(
	CloudKit.Record|CloudKit.Record[] records
);`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder/forceDelete)

Deletes one or more records regardless of conflicts.

### Executing Operations

[`Promise<CloudKit.RecordsResponse, CloudKit.CKError> commit();`](/documentation/CloudKitJS/CloudKit.RecordsBatchBuilder/commit)

Executes the operations on the database that created this batch builder object.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)