Do the children in a bulk operation JSONL with nested connections come right after their parent?

Technical Q&A

AI-generated summary

Core Question: When parsing a bulk operation JSONL file line-by-line, are all children guaranteed to appear immediately after their parent object?

Use Case: The original poster needs to process parents with all their children while minimizing memory usage, requiring confirmation that encountering a new parent means the previous parent’s children are complete.

Example Scenario: In a Product/ProductVariant JSONL file, when reaching Product 1921569259576 on line 4, can one assume all variants for the previous Product 1921569226808 have already been encountered?

Solution (API Version 2025-07+):

  • New groupObjects parameter controls whether children are grouped under parents
  • Currently defaults to true but grouping increases processing time and failure risk
  • Recommendation: Explicitly set groupObjects: true to ensure children follow parents, as future default behavior may change
  • Earlier API versions lack this parameter and don’t document grouping guarantees

Status: Resolved for users on recent API versions; older versions have uncertain behavior.

1

When parsing a bulk operation JSONL file with nested items from top to bottom line by line, when I reach a new top level parent object, does that mean I’ve gone through all children of the previous parent?

Context

When processing a bulk operation JSONL file, I do some processing that requires having a parent and all of their children. I’d like to keep my memory requirements as small as possible, so I need to know when I’m done processing an object and all of its children.

Example for clarification

Using the documentation page’s JSONL example:

{"id":"gid://shopify/Product/1921569226808"}
{"id":"gid://shopify/ProductVariant/19435458986123","title":"52","__parentId":"gid://shopify/Product/1921569226808"}
{"id":"gid://shopify/ProductVariant/19435458986040","title":"70","__parentId":"gid://shopify/Product/1921569226808"}
{"id":"gid://shopify/Product/1921569259576"}
{"id":"gid://shopify/ProductVariant/19435459018808","title":"34","__parentId":"gid://shopify/Product/1921569259576"}
{"id":"gid://shopify/Product/1921569292344"}
{"id":"gid://shopify/ProductVariant/19435459051576","title":"Default Title","__parentId":"gid://shopify/Product/1921569292344"}
{"id":"gid://shopify/Product/1921569325112"}
{"id":"gid://shopify/ProductVariant/19435459084344","title":"36","__parentId":"gid://shopify/Product/1921569325112"}
{"id":"gid://shopify/Product/1921569357880"}
{"id":"gid://shopify/ProductVariant/19435459117112","title":"47","__parentId":"gid://shopify/Product/1921569357880"}

If I’m reading the file line by line from top to bottom and I hit Product with id gid://shopify/Product/1921569259576 on line 4, does this mean that I’ve already seen all of the previous product’s (gid://shopify/Product/1921569226808) product variants the JSONL file contains?

2

Hello I’m having a similar issue, I want to add the product variant nested with the product - unsure how to do this via the bulk API. I managed to get product bulk to work, but not with nested variants

3

For anyone wondering this in 2025, the latest version of the API as of today (2025-07) has a new parameter groupObjects:

mutation bulkOperationRunQuery($groupObjects: Boolean!, $query: String!) {
  bulkOperationRunQuery(groupObjects: $groupObjects, query: $query) {
    bulkOperation {
      # BulkOperation fields
    }
    userErrors {
      field
      message
    }
  }
}

According to the docs, this param defaults to true, and has the following description:

Whether to group objects under their corresponding parent objects in the JSONL output. Grouping is costly, causes bulk operations to take longer to complete, and increases the chances of failures such as timeouts.

Since the previous versions don’t make any mention of grouping, it’s safest to upgrade to the latest version and set groupObjects to true (in case the default changes in the future) if you need subobjects to be grouped with their parents