GraphQL queries

A GraphQL query retrieves data from a server, similar to a GET request for a REST API. However, unlike REST, all GraphQL queries are sent to a single endpoint and use the POST http method.

A GraphQL API models data as nodes connected by edges. A node is an object that has a global ID, such as an Order object or Product object. You can fetch data about an individual node, or you can follow the edges to fetch data about a collection of related nodes. At each node, you specify the fields that you want to retrieve.

QueryRoot

The QueryRoot represents easily accessible entry points into the GraphQL API. Everything that can be queried is defined as a field or connection on the QueryRoot object.

To see what data you can query, see the QueryRoot reference for the GraphQL Admin API and the Storefront API.

This query requests the shop object, a few fields, and the customers connection in a single request.

POST /admin/api/2019-07/graphql.json

query {
  shop {
    id
    name
    email
  }
  customers(first:1) {
    edges {
      node {
        id
        displayName
        phone
      }
    }
  }
}

JSON response

{
  "data": {
    "shop": {
      "id": "gid:\/\/shopify\/Shop\/17681717",
      "name": "johns-apparel",
      "email": "john@johns-apparel.com"
    }
  },
  "customers": {
      "edges": [
        {
          "node": {
            "id": "gid:\/\/shopify\/Customer\/6581271756",
            "displayName": "Beatrice Alighieri",
            "phone": "+12345678912"
          }
        }
      ]
    }
  ...
}

Run in GraphiQL

Notice that after the data key, the shape of the response keys reflects the shape of the query keys.

Fields

A field is a single resource or property. For example, the customer field queries a single customer. In the GraphQL Admin API reference, the customer field is defined like this:

customer (Customer)

Returns a Customer resource by ID.

id (ID!) required

The ID of the Customer to return.

This field field requires the id argument, which specifiees the customer to query. After selecting the customer field and providing an ID, you list the fields on the Customer type that you want to return.

This query gets a specific customer, and selects a few fields from that object.

query {
  customer(id: "gid://shopify/Customer/6581271756") {
    displayName
    phone
  }
}
{
  "data": {
    "customer": {
      "displayName": "Beatrice Alighieri",
      "phone": "+12345678912"
    }
  }
}

Run in GraphiQL

Connections

Connections are links between related nodes. You can use connections to make nested queries, gathering information from multiple nodes by traversing their connections in a single GraphQL call. If you're selecting something with a pluralized name, then you're often (but not always) using a connection.

When selecting a connection, you must provide a first or last argument. This limits how many results are returned, and is a key component in managing rate-limiting and pagination. These subjects are covered later in this guide.

Within a connection, you need to select the edges field. The edges field returns an array of objects of the same type, such as the variants belonging to a product. After you’ve selected the edges, you need to access the individual objects by using the node field.

Similar to querying an individual node, you list the fields that you want to return. The response returns that data for each node in the connection. If a connection has fewer than the requested number of objects, then the response contains all the data that's available.

The following example requests the products connection, and asks for the first three products. Because the Product type has a variants connection, the same pattern is used to get information on the first three variants for the original products.

POST /admin/api/2019-07/graphql.json

query {
  products(first:3) {
    edges {
      node {
        id
        handle
        variants(first:3) {
          edges {
            node {
              id
              displayName
            }
          }
        }
      }
    }
  }
}

JSON response

{
  "data": {
    "products": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Product/1321540321336",
            "handle": "ocean-blue-shirt",
            "variants": {
              "edges": [
                {
                  "node": {
                    "id": "gid://shopify/ProductVariant/12195005104184",
                    "displayName": "Ocean Blue Shirt - xs"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Run in GraphiQL

Filtering connections using a search query

You can filter connections by using the query argument to return only nodes that match a search query. To learn which fields you can filter a connection by, refer to the API documentation for the connection's query argument. To learn how to format a search query, refer to Search syntax.

The following query finds the first two orders that are fulfilled.

POST /admin/api/2019-07/graphql.json

query {
  orders(first:2, query:"fulfillment_status:fulfilled") {
    edges {
      node {
        id
        name
        displayFulfillmentStatus          
      }
    }
  }
}

JSON response

{
  "data": {
    "orders": {
      "edges": [
        {
          "node": {
            "id": "gid:\/\/shopify\/Order\/410479493176",
            "name": "#1592",
            "displayFulfillmentStatus": "FULFILLED"
          }
        },
        {
          "node": {
            "id": "gid:\/\/shopify\/Order\/410478542904",
            "name": "#1564",
            "displayFulfillmentStatus": "FULFILLED"
          }
        }
      ]
    }
  }
}

Run in GraphiQL

Next steps

  • GraphQL mutations — Learn how to create and modify data using GraphQL mutations, and then send your first mutation.

Sign up for a Partner account to get started.

Sign up