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.
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.
This query requests the shop object, a few fields, and the customers connection in a single request.
Notice that after the
data key, the shape of the response keys reflects the shape of the query keys.
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:
Returns a Customer resource by ID.
The ID of the Customer to return.
This 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 type that you want to return.
This query gets a specific customer, and selects a few fields from that object.
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
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
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.
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.
- GraphQL mutations — Learn how to create and modify data using GraphQL mutations, and then send your first mutation.