GraphQL queries

The QueryRoot object is the initial entry point for all queries in the GraphQL API. Everything that can be queried is defined as a field or connection on the QueryRoot object.

To learn about what data you can query, refer to the QueryRoot object in the relevant API's reference.

The following diagram illustrates example relationships between objects that are retrieved in an query:

The query requests the Shop object, data from a few fields, the child ShopAddress object, and the products connection. The following is the single request structure to retrieve this data. In the response, the structure of the data object mirrors the query's shape:

A field is unit of data associated with an object or type. For example, in the GraphQL Admin API's QueryRoot object, the customer field queries a single customer, and returns a Customer object.

An argument is a set of key-value pairs attached to a field, providing a parameterized input to the field that influences the returned data or an operation's behavior. For example, the customer field requires the id argument, which specifies the customer to query. After selecting the customer field and providing an ID, you list the fields on the Customer object that you want to return.

To learn about what data you can query, refer the object's fields in the relevant API's reference.

The following query retrieves a specific customer, and selects a few fields from the Customer object:

Connections in GraphQL represent relationships between associated types. Nodes are elements within connections. You can traverse connections to perform nested queries, retrieving data from multiple nodes in a single GraphQL query. If you're selecting something with a pluralized name, then you're likely using a connection.

When you select a connection, you must pass a first or last argument to limit the number of nodes that are returned. This is a key component to manage rate-limiting and pagination.

You can access the nodes in a connection in the following ways:

• edges: customers { edges { node { ... } } }
• nodes: customers { nodes { ... } }

Regardless of the syntax that you use, the return is an array of objects of the same type. For example, when you query a product's variants, an array of Variant objects is returned.

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

If you want to retrieve the next batch of objects, or you need to retrieve more than the maximum number of objects, then you can paginate the objects using cursor-based pagination.

The following diagram illustrates example relationships between GraphQL types in a connection, including the connection, its constituent edges and nodes, and the associated objects and fields:

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

In the response, only one set of data is returned because the store only has a single product and variant.

You can filter connections with query argument, to return only the 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 retrieves the first two orders that are fulfilled:

Learn how to create and modify data with mutations.