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

Run a 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.

POST /admin/api/2020-04/graphql.json

View response

JSON response

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.

POST /admin/api/2020-04/graphql.json

View response

JSON response

Step 3. Retrieve your data

When an operation is completed, a JSONL output file is available for download at the URL specified in the url field. If the query produced no results, then the url field will return null.

See Download result data for more details on the files we return and JSONL file format for how to parse them.

Bulk query workflow

Below is the high-level workflow for creating a bulk query:

  1. Identify a potential bulk operation.

    You can use a new or existing query, but it should potentially return a lot of data. Connection-based queries work best.

  2. Test the query by using the Shopify GraphiQL app.

  3. Write a new mutation document for bulkOperationRunQuery.

  4. Include the query as the value for the query argument in the mutation.

  5. Run the mutation.

  6. Poll the bulk operation until the status field shows that the operation is no longer running.

    You can use the objectCount field to check the oparation's progress.

  7. Download the JSONL file at the URL provided in the url field.

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 query value:

  • The triple quotes (""") define a multi-line string in GraphQL.
  • The bulk operation's ID is returned so you can poll the operation.
  • The userErrors field is returned to retrieve any error messages.

Paste the original sample query into the mutation, and then make a couple of minor optional changes:

  • The first argument is optional and ignored if present, so it can be removed.
  • The cursor and pageInfo fields are also optional and ignored if present, so they can be removed.