bulkOperationRunQuery defaults groupObjects to false. If your parser expects children directly after their parent, either explicitly request groupObjects: true or rewrite the parser to join JSONL rows by __parentId. Don’t assume a successful export means the row order is unchanged.On this page
Why the old export parser broke
Older bulk-query examples assumed grouped JSONL: product rows followed by their variant or metafield rows. Shopify changed the default on October 29, 2025 for API 2026-01 because grouping adds processing overhead and can increase timeouts. Flat output is faster, but code that attaches a child to the most recently seen parent can now silently associate records with the wrong product.
Choose explicit grouping or order-independent parsing
First inspect the GraphQL API version and the actual JSONL output, not just the completed operation status. For a small legacy integration that truly needs adjacent parent/child rows, pass groupObjects: true to bulkOperationRunQuery. For large feeds, prefer the default flat output and build a parent lookup keyed by Shopify GID, using __parentId on child records. If the export is too large to keep all parents in memory, use a disk-backed lookup or a staged two-pass process. Do not sort all JSONL blindly by title or SKU.
Minimal GraphQL change
mutation {
bulkOperationRunQuery(
query: """{ products { edges { node { id title variants { edges { node { id sku } } } } } } }"""
groupObjects: true
) {
bulkOperation { id status }
userErrors { field message }
}
}
This restores grouped output for a query on 2026-01, at the cost of additional work by Shopify. The nested query still needs to meet Shopify’s bulk-query connection and nesting limits. Do not add groupObjects to bulk mutation jobs: Shopify deprecated that argument there because mutation output has no parent-object grouping to preserve.
Make failure observable
Log the API version, operation ID, status, file size, total rows, parent count, child count and unresolved __parentId values. Treat orphaned children as a failed import rather than silently dropping them. Run a representative export before deploying a version bump; API changes can alter data shape even when the schema validates.
How to test this
- Export two products with several variants and metafields using the old and new API versions.
- On 2026-01, compare the default flat output with an explicit
groupObjects: trueexport. - Verify every child attaches to the correct parent by GID, regardless of row order.
- Test a large dataset and compare runtime and memory use; retain grouping only if necessary.
- Force an unknown parent ID and confirm the importer reports an error instead of misassigning it.

