datasource.createBatch ^v2.7.0

Creates a Batch object which can batch database operations with configurable types such as insert, update, or ignore using a specified datasource.

By grouping database operations into batches, the Batch object can significantly reduce the number of round-trips to the database, greatly improving performance for bulk data operations.

datasource.createBatch(datasourceNameOrId, tableName, fields)
datasource.createBatch(datasourceNameOrId, batchType, tableName, fields, updateFields)
datasource.createBatch(datasourceNameOrId, batchType, tableName, fields, updateFields, batchSize)

Parameters

• datasource (string): The datasource name or id used for the batch operation.
• batchType (string): The type of batch operation (e.g., INSERT, INSERT_OR_UPDATE, INSERT_OR_IGNORE). (Default: "INSERT") (optional)
• tableName (string): The name of the database table.
• batchSize (int): The number of rows in each batch before triggering a flush. (Default: 500) (optional)
• fields (array): The field names that each row will contain.
• updateFields (array): The field names to update on duplicate keys if applicable. (optional)

Methods

• setAllowNulls(allowNulls) - Sets whether null values are allowed in the batch operation.

  • allowNulls (boolean): Whether or not null values are allowed in the batch operation.

• insert(values) - Adds a new row to the batch. Automatically flushes the batch if the batch size is reached.

  • values (array): Array of values to insert for the row, the length of this array must match the length of fields assigned to the batch.

• flush() - Manually flushes all pending batch operations to the database.

• truncate() - Clears the entire database table associated with the batch.

Examples

// Example of creating an INSERT type batch with default 500 batch size.
var batch = datasource.createBatch(
    "Internal Datastore",   
    "test_table",
    ["field_1", "field_2", "field_3"]
);

// Truncate database table assosiated with batch, clearing all existing data.
batch.truncate();

// Insert rows into the batch. if batch reaches the batchSize threshold, it will automatically flush.
for (let i = 0; i < 15; i++) {
    batch.insert([
        `test_value_1`, // Value for 'field_1'
        "test_value_2", // Value for 'field_2'
        "test_value_3", // Value for 'field_3'
    ]);
}

// Manually flush the remaining data in the batch to the database if any didn't make the batch size threshold.
batch.flush();

// Example of creating an INSERT_OR_UPDATE type batch, where on duplicate key it will update "field_2" for that row otherwise it insert a new row.
var batch = datasource.createBatch(
    "Internal Datastore",   
    "INSERT_OR_UPDATE",
    "test_table",
    ["field_1", "field_2", "field_3"],
    ["field_2"]
);

// Example of creating an INSERT_OR_IGNORE type batch, where on duplicate key nothing will be updated.
var batch = datasource.createBatch(
    "Internal Datastore",   
    "INSERT_OR_IGNORE",
    "test_table",
    ["field_1", "field_2", "field_3"],
    []
);