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/2021-01/graphql.json
query {
shop {
id
name
email
}
customers(first:1) {
edges {
node {
id
displayName
phone
}
}
}
}
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"
}
}
]
}
}
}
]
}
}
}
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/2021-01/graphql.json
query {
orders(first:2, query:"fulfillment_status:shipped") {
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"
}
}
]
}
}
}
Next steps
- GraphQL mutations — Learn how to create and modify data using GraphQL mutations, and then send your first mutation.