Perform bulk operations with the GraphQL Admin API
With the GraphQL Admin API, you can use bulk operations to asynchronously fetch data in bulk. The API is designed to reduce complexity when dealing with pagination of large volumes of data. You can bulk query any connection field that's defined by the GraphQL Admin API schema.
Instead of manually paginating results and managing a client-side throttle, you can instead run a bulk query operation. Shopify’s infrastructure does the hard work of executing your query, and then provides you with a URL where you can download all of the data.
The GraphQL Admin API supports querying a single top-level field, and then selecting the fields that you want returned. You can also nest connections, such as variants on products.
Apps are limited to running a single bulk operation at a time per shop. When the operation is complete, the results are delivered in the form of a JSONL file that Shopify makes available at a URL.
Bulk query overview
The complete flow for running bulk queries is covered later, but below are some small code snippets that you can use to get started quickly.
Step 1. Submit a query
bulkOperationRunQuery mutation and specify what information you want from Shopify.
The following mutation queries the
products connection and returns each product's ID and title.
Step 2. Poll your operation’s status
While the operation is running, you need to poll to see its progress using the
currentBulkOperation field. The
objectCount field increments to indicate the operation's progress, and the
status field returns whether the operation is completed.
Step 3. Retrieve your data
When an operation is completed, a JSONL output file is available for download at the URL specified in the
If the query produced no results, then the
url field will return
Bulk query workflow
Below is the high-level workflow for creating a bulk query:
You can use a new or existing query, but it should potentially return a lot of data. Connection-based queries work best.
Test the query by using the Shopify GraphiQL app.
Write a new mutation document for
Include the query as the value for the
queryargument in the mutation.
Run the mutation.
Poll the bulk operation until the
statusfield shows that the operation is no longer running.
You can use the
objectCountfield to check the oparation's progress.
Download the JSONL file at the URL provided in the
Identify a potential bulk query
Identify a new or existing query that could return a lot of data and would benefit from being a bulk operation. Queries that use pagination to get all pages of results are the most common candidates.
The example query below retrieves some basic information from a store's first 50 products that were created on or after January 1, 2019.
Write a bulk operation
To turn the query above into a bulk query, use the
bulkOperationRunQuery mutation. It’s easiest to begin with a skeleton mutation without the
- The triple quotes (""") define a multi-line string in GraphQL.
- The bulk operation's ID is returned so you can poll the operation.
userErrorsfield is returned to retrieve any error messages.
Paste the original sample query into the mutation, and then make a couple of minor optional changes:
firstargument is optional and ignored if present, so it can be removed.
pageInfofields are also optional and ignored if present, so they can be removed.