GraphQL variables
You can simplify GraphQL queries and mutations by extracting data into separate variables. GraphQL variables let you re-use the same requests with different arguments.
Variable structure
GraphQL requests can be split into two sections: the query, and variables.
In the query section, GraphQL variables begin with the $
symbol and are declared after the query
or mutation
keyword, similar to passing an argument to a function.
When you declare a variable, you need to specify its type, such as CustomerInput
.
This lets GraphQL know that you intend to refer to this type by this variable name later in the actual query.
The following query declares an $input
variable and passes it to the input
argument.
mutation($input: CustomerInput!) {
customerCreate(input: $input) { ... }
}
In the variables section, the variables themselves are defined as a JSON object.
The following JSON object defines the $input
variable for the query above.
{
"input": {
"firstName": "Greg",
"lastName": "Variables",
"email": "gregvariables@teleworm.us"
}
}
Simplify the customer creation request
The following example uses the customerCreate
mutation from the previous article, but simplifies the mutation by using variables. The result is a much cleaner and reusable mutation.
POST /admin/api/2021-01/graphql.json
mutation ($input: CustomerInput!) {
customerCreate(input: $input)
{
customer {
id
displayName
}
userErrors {
field
message
}
}
}
Variables
{
"input": {
"firstName": "Greg",
"lastName": "Variables",
"email": "gregvariables@teleworm.us"
}
}
JSON response
{
"data": {
"customerCreate": {
"customer": {
"id": "gid://shopify/Customer/1310038130710",
"displayName": "Greg Variables"
},
"userErrors": []
}
}
...
}
Variables in cURL
Because variables are a core concept of GraphQL, you can use them outside of fully featured clients.
For example, you can perform the customerCreate
mutation with variables by using cURL.
The cURL command below creates a customer. The JSON data
object has two properties:
query
— The mutation, provided as a string.variables
- An object for holding variables. The only variable is theinput
object that's used for the mutation.
To run the cURL command from the command line, make the following substitutions:
{ store }
— The name of your development store.{ access_token }
— Your app's API access token.
curl -X POST \
https://{ store }.myshopify.com/admin/api/2021-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'x-shopify-access-token: { access_token }' \
-d '{
"query": "mutation($input: CustomerInput!) { customerCreate(input: $input) { customer { id displayName } userErrors { field message } } }",
"variables": {
"input": {
"firstName": "Greg",
"lastName": "Variables",
"email": "gregvariables@teleworm.us""
}
}
}'
The response will look similar to this:
{
"data": {
"customerCreate": {
"customer": {
"id": "gid://shopify/Customer/1322001989654",
"displayName": "Greg Variables"
},
"userErrors": []
}
},
...
}
Next steps
- Paginating results with GraphQL — Learn how to use cursor-based pagination with GraphQL.