Bulk Create (Upsert)
The Bulk Upsert Operation allows you to insert multiple records into a table and automatically update existing records when a conflict occurs on specified unique fields.
Bulk Upsert = Bulk Insert + Update on Conflict
- If a record does not exist → it is inserted
- If a record already exists (based on conflict fields) → it is updated
Why Use Bulk Upsert?
This approach avoids:
- Duplicate rows
- Manual existence checks
- Multiple database calls
- Inefficient row-by-row updates
It is ideal for ERP systems handling large datasets.
Required Control Fields
Bulk Upsert behavior is controlled using:
__d3__updateOnDuplicate__d3__conflictFields
Both fields are mandatory for bulk upsert.
Usage
await bulkCreateOp(tableName, {
__d3__bulkData: bulkPayload,
__d3__updateOnDuplicate: true,
__d3__conflictFields: ["BPCode"]
});Payload Structure
__d3__bulkData (Required)
An array of objects where each object represents one row to insert or update.
const bulkPayload = [
{
BPCode: "CUST001",
Account_Name: "ABC Traders",
Closing_Date: "2026-01-07T00:00:00.000Z",
Closing_Balance: 12000
},
{
BPCode: "CUST002",
Account_Name: "XYZ Enterprises",
Closing_Date: "2026-01-07T00:00:00.000Z",
Closing_Balance: 8500
}
];__d3__updateOnDuplicate (Required)
__d3__updateOnDuplicate: trueEnables update behavior when a conflict occurs.
If set to false or omitted, the operation behaves like a plain bulk insert.
__d3__conflictFields (Required)
__d3__conflictFields: ["BPCode"]Defines which column(s) should be checked for conflicts.
Example Implementation
async function customizeERP(userData, apiOperations) {
const tableName = "tableName";
const { bulkCreateOp } = apiOperations;
const bulkPayload = [];
if (userData && userData.length > 0) {
userData.forEach((row) => {
bulkPayload.push({
BPCode: row?.["BPCode"] ?? null,
Account_Name: row?.["Account_Name"] ?? null,
Closing_Date: row?.["Closing_Date"] ?? null,
Closing_Balance: row?.["Closing_Balance"] ?? null
});
});
if (bulkPayload.length === 0) {
return {
result: {},
popupMsg: {
type: "error",
message: "There is no data in bulkPayload to perform the upsert operation."
}
};
}
const bulkUpdatedData = await bulkCreateOp(tableName, {
__d3__bulkData: bulkPayload,
__d3__updateOnDuplicate: true,
__d3__conflictFields: ["BPCode"]
});
return {
result: bulkUpdatedData
};
}
}Example Input
[
{
"BPCode": "CUST002",
"Account_Name": "XYZ Enterprises",
"Closing_Date": "2026-01-07T00:00:00.000Z",
"Closing_Balance": 8500
}
]