Batching in Flask-SQLAlchemyBatching Operations in Flask-SQLAlchemy: A Comprehensive Guide

In this tutorial, we will discuss a strategy that can help you significantly improve the performance of your Flask-SQLAlchemy application when dealing with large amounts of data: batching.

Understanding Batching

Batching refers to performing operations in “batches” or groups rather than individually. When you’re dealing with a large volume of data, performing operations one by one can be time-consuming and inefficient. By grouping similar operations together into a batch, you can reduce the number of transactions with the database and increase the speed of your operations.

For example, suppose we need to add 1,000 new products to our e-commerce database. Without batching, we would have to execute 1,000 individual INSERT statements, which can be quite slow. With batching, however, we can group these INSERT operations together and execute them in fewer transactions, which can greatly improve performance.

Batching with Flask-SQLAlchemy

Flask-SQLAlchemy provides several methods that can be used to perform batch operations. The most commonly used ones are add_all() and bulk_insert_mappings(), bulk_update_mappings()

Using add_all()

The add_all() method allows you to add multiple new records to the session at once. This method expects a list of model instances to be added to the session.

Let’s consider an example where we have a list of new products that we want to add to our database:

new_products = [
    Product(name='Product 1', price=10.0, quantity=100),
    Product(name='Product 2', price=20.0, quantity=200),
    Product(name='Product 3', price=30.0, quantity=300),
    # More products...


While add_all() helps by reducing the number of calls to add(), it doesn’t significantly improve performance because SQLAlchemy still processes each record individually when committing the transaction.

Using bulk_insert_mappings()

To truly leverage the power of batching in Flask-SQLAlchemy, you can use the bulk_insert_mappings() method. This method allows you to perform a bulk insert operation using a list of dictionaries, where each dictionary represents a new record.

Here’s how you can use bulk_insert_mappings() to add our new products:

new_products = [
    {'name': 'Product 1', 'price': 10.0, 'quantity': 100},
    {'name': 'Product 2', 'price': 20.0, 'quantity': 200},
    {'name': 'Product 3', 'price': 30.0, 'quantity': 300},
    # More products...

db.session.bulk_insert_mappings(Product, new_products)

bulk_insert_mappings() is significantly faster than adding records individually or even using add_all(), because it performs a single INSERT operation with multiple rows.

It’s important to note that bulk_insert_mappings() doesn’t trigger events like before_insert or after_insert, and it doesn’t populate the id field of the inserted records.

This will insert all the data in a single transaction, which is significantly faster than adding and committing each Product instance individually.

bulk_update_mappings(model, mappings):

This method performs an efficient multi-row UPDATE statement of the given list of dictionary objects representing rows to be updated.

Here’s how you might use bulk_update_mappings:

data = [
    {'id': 1, 'price': 150.0},
    {'id': 2, 'price': 250.0},
    # More dictionaries...

db.session.bulk_update_mappings(Product, data)

Each dictionary must at least contain the primary key(s) of the rows to update, plus the updated values. Like bulk_insert_mappings, bulk_update_mappings will perform all updates in a single transaction, which can be much faster than updating and committing each instance individually.

However, while these methods can greatly increase performance for large operations, there are a few caveats to keep in mind:

  • These methods do not trigger any save-update events, so if your application relies on these events (or any other events triggered by normal inserts or updates), you’ll need to handle them manually.
  • These methods do not support cascading – you need to handle that manually as well.
  • bulk_insert_mappings does not return the inserted primary key(s), so if you need these, you might still be better off using the regular insert method.

Despite these limitations, bulk_insert_mappings and bulk_update_mappings can be very useful for improving the efficiency of large insert or update operations.


When dealing with large amounts of data in Flask-SQLAlchemy, batching can be an effective way to improve the performance of your operations. By using methods like add_all() and bulk_insert_mappings(), you can reduce the number of transactions with the database and make your operations run faster.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top