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.

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

{
  "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.

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

{
  "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.