GRAPHQL Admin API: Query products metafield references via bulk queries

Retired Boards Appdev Metafields
,

Topic summary

A user encountered an error when attempting to bulk query products with their metafield references using the GraphQL Admin API. The error message stated “Selections can’t be made directly on unions (see selections on MetafieldReference)”.

The Issue:
The metafields.references field returns a union type (MetafieldReference) that can be multiple types like Metaobject, ProductVariant, Product, etc. GraphQL doesn’t allow direct field selections on unions without specifying which type is being queried.

The Solution:
Use GraphQL fragments to handle each possible union type separately. Instead of querying fields directly on the union, specify the type case first (e.g., ... on Metaobject) and then query the desired fields within that fragment.

Resolution:
The original poster understood the solution after the explanation. They restructured their bulk query to use type-specific fragments, moving fields like id into the appropriate union case (e.g., ... on Metaobject { id }). This approach requires some field repetition across different type cases but properly handles the union structure required by GraphQL.

Summarized with AI on November 12. AI used: claude-sonnet-4-5-20250929.
1

Hi, i am trying to query all my products with all corresponding metafields. When i try to create new bulk query operation I get response with error “Selections can’t be made directly on unions (see selections on MetafieldReference)”. How can i get my products and metafields linked together?

I am using GraphQL Admin API.

Thanks for any help.

Here asi my query:

mutation {
  bulkOperationRunQuery(
    query: """
    {
      products {
        edges {
          node {
            title
            id
            metafields {
              edges {
                node {
                  id
                  key
                  value
                  references {
                    edges {
                      node {
                        id
                        ... on Metaobject {
                          type
                          fields {
                            key
                            value
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
    """
  ) {
    bulkOperation {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}
2

You cannot use selections directly on unions in GraphQL. Instead of directly querying the references field on Metafield, you might need to structure your query to handle the specific types of references you expect to return using GraphQL fragments or a similar approach.

For example:

query {
  products(first: 5) {
    edges {
      node {
        id
        title
        metafields(first: 5) {
          edges {
            node {
              key
              value
              type
              # Include fragment for handling Metafield references
              references(first: 5) {
                edges {
                  node {
                    ... on ProductVariant {
                      id
                      title
                    }
                    ... on Product {
                      id
                      title
                    }
                    # Add more fragments as needed for other types of references
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
3

What you posted is still querying metafields.references.edges[N].node which is still union (of Metaobject | ProductVariant | Product | OrWhatever). Also this is normal query, and I need bulk query

UPDATE:

Oh i didnt get it when i wrote this reply.. :grinning_face_with_smiling_eyes:

You just cant use or query any field outside the specific case of the union. You have to always specify the case you need and then query the fields you need. Even if it means some repetition.

so my query should look like this:

mutation {
  bulkOperationRunQuery(
    query: """
    {
      products {
        edges {
          node {
            title
            id
            metafields {
              edges {
                node {
                  id
                  namespace
                  key
                  value
                  references {
                    edges {
                      node {
                        ... on Metaobject {
                          id
                          type
                          fields {
                            key
                            value
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
    """
  ) {
    bulkOperation {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

In my case i just moved “id” field to “… on Metaobject” union case.

Thanks again @SomeUsernameHe for your help