Selections Syntax

With GraphQL, you must specify exactly what data you retrieve from Shopify. This is achieved via the 'Selections' setting, which is available on most of the GraphQL tasks. It allows you to specify which fields you want to retrieve, and also to retrieve related objects too.

In the context of an export task, the selections define the data that should be exported. In the context of an import task, the selections define the data that will be present in the success file.

A complete example of the syntax used is provided below. This example is based on exporting order information from Shopify. Further details are provided in the sections below.

{
  id
  name
  createdAt
  updatedAt
  billingAddress {
    address1
    address2
    city
    countryCodeV2
    firstName
    lastName
    zip
  }
  lineItems (first: 100) {
    nodes {
      id
      name
      quantity
      sku
    }
  }
  purchasingEntity {
    __typename
    ... on Customer {
      id
      email
      firstName
      lastName
    }
    ... on PurchasingCompany {
      company {
        id
        name
        externalId
      }
    }
  }
}

Syntax

Objects

The fields at each level within the object hierarchy must be enclosed in curly braces { }.

Fields

The field names must match those defined for each object in Shopify's GraphQL documentation.

Each of the field names you want to select should be separated by white space. So they can be separated by line breaks to improve readability, or spaces if you want to place them all on one line.

Arguments

Some fields may require arguments to be specified. Arguments are placed after the field name, enclosed within brackets ( ). Each argument is separated by a comma ,. Each argument consists of a name and a value, separated by a colon :.

For example, to provide a first and reverse argument for the lineItems field, you would use: lineItems (first: 10, reverse: true)

Connections

Connections are a special type of field that represents a relationship to another object. They usually require at least one argument to be specified. The related object can be accessed via the nodes field of the connection.

For example, to select the id and quantity of the first 10 line items related an order, you would use:

lineItems (first: 10) {
  nodes {
    id
  }
}

Unions

Unions are a special type of field that represents a value that can be one of multiple different types of object. For example the purchasingEntity field on an order, which can be either a customer or a company.

When dealing with this type of field, you must add __typename as one of the child fields. This identifies which type of object the union contains.

You can choose different fields to be returned depending on which type of object you are dealing with. This is done using an ellipsis ..., followed by the word on, followed by the object name, and then the list of field names wrapped in curly braces { }.

The example below shows how to select the email if the purchasingEntity is a customer, or select the company name if the purchasingEntity is a company.

purchasingEntity {
  __typename
  ... on Customer {
    email
  }
  ... on PurchasingCompany {
    company {
      name
    }
  }
}