Bubble Docs
Comment on page

Bulk operations

This section covers bulk operations, which lets you run API workflows on a list of things directly from the Bubble database editor
Bulk operations let you execute workflows on a large set of data within the editor. By scheduling a pre-defined API workflow on the provided list, you can perform the same wide array of actions on a list of things that you can do in your app.
Note on emails: the bulk operation cannot be used to mass send emails.
Note: Bulk operations run client-side, so they depend on your browser window staying open and active. In other words, you need to keep the popup open for them to continue.

Defining an API workflow

Before you can perform bulk workflows on your data, you need to define the API workflows that you are going to call.
If you are not familiar with Bubble's Workflow API and how to set up API workflows, we recommend you first get to know how they work. The first link below gives an introductory guide to the Workflow API in general, and the second shows you how to set up API workflows that can be used with bulk operations.
Article: The Workflow API
Article API Workflows

Valid API workflow parameters

To be valid for scheduling by the Bulk operation feature, APIworkflows must have a few properties in place:
A thing parameter: the workflow must include a parameter that requires a 'thing' of the same data type as the one you intend to perform the bulk operation on
The API Workflow must have a parameter that lets you specify a thing to run the workflow on. In the example above we're instructing Bubble to request a thing of the type Product.
Only set up one parameter: when a bulk operation is called, Bubble will only fill one parameter: the thing it's currently scheduling the operation on. In other words, do not set up any other parameters.
The thing cannot be a list: bulk operations are scheduled one-by-one on a list of things. In other words, the parameter that asks for which thing to perform the operation on should ask for a single think, not a list/array.
It does not need to be exposed as a public API Workflow: while it will still work if you expose it, it's better to uncheck the Expose as a public API Workflow checkbox to make sure that it cannot be triggered from outside of your app.

Adding actions

Now we have an API Workflow that accepts a single parameter: the thing that we want to run the operation on. In our example we set that thing to a custom data type called Product, so let's make a change to that thing. We have a yes/no field on the product called Published that we want to set to yes.
In our API Workflow, this is a very simple Make changes to a thing operation:
  1. 1.
    First, we add the Make changes to a thing action to the API Workflow
  2. 2.
    Then, we choose product as the thing we want to change. This is the parameter we set up earlier.
  3. 3.
    Finally, we set the Published field on the product to yes

Running the bulk operation

Now that we have the workflow we want to run the bulk operation on, let's see how we trigger it to run.
  1. 1.
    First, we select the data type that we want to run the bulk operation on. In this case, we want to work with Products
  2. 2.
    Next, select the Products that you want to run the operation on. Trucker cap and Baseball cap are ready to be published, but Product 1 still needs some work, so let's just check to two top ones.
  3. 3.
    Then, we click the Bulk button, where we'll select with API Workflow to run on the selected things.
Keep in mind that bulk operations spend your app's server capacity just like every other operation. If you run bulk operations on thousands of entries, they can take some time to finish, and can use a noticeable chunk of your capacity.
Bulk operations typically make changes to a list of records. If you make a mistake when running a bulk operation, you can restore the data type to what it looked like before the operation by using the Copy and restore database feature.
Click the image to enlarge.
  1. 1.
    In the first dropdown, we choose what list to run the operation on. You can choose to run it on the entire current view, or the selected entries – in our case we specifically selected two entries, to let's go with that
  2. 2.
    In the second dropdown you will find the list of compatible API Workflows. If the Workflow does not accept the same data type as a parameter, it will not be selectable
  3. 3.
    The text next to point three confirms that the workflow will in this case be run on 2 entries, which is what we selected
  4. 4.
    Finally, we can click Run workflow and the operation will start. Since we are only making a small change on two entries, it should finish very quickly.
Looking again at the data in our database, we can see that the two data types we selected now have their Published field set to yes.
Click the image to enlarge.

Combining bulk operations with views

Views let you filter the data displayed in the database editor by specific constraints, just like the Do a search for data source. Since bulk operations let you run the operation on all records in the current view, you can combine these features to flexibly run bulk operations on things that match specific criteria, instead of manually selecting the things in the list.
To set up a new view, click the New view button or the pencil icon next to the data type you want to run an operation on.

Other ways to learn

Schedule API Workflow on a list – used to trigger bulk operations in your app
The Bulk feature is triggered from inside the Bubble editor, but technically does the same thing as the Schedule API Workflow on a list feature. To run bulk operations in your app instead, use that action to trigger the workflow.
Recursive workflows - used to process large amounts of data sequentially
If you need to make sure that your list of things is processed sequentially (as opposed to in parallell as fast as possible), you may consider using recursive workflows. They are essentially workflows that re-schedule themselves using a Schedule API workflow in the action itself. Note that while there are corner cases where this is useful, recursive workflows are generally slower and consume more WU than Schedule API workflow on a list.
Recursive workflows must be triggered from your app, not using the Bulk feature.