You may have noticed that the query declarations in our examples above contain references to an
$id symbol inside the GraphQL code: these are GraphQL Variables.
GraphQL variables are a construct that allows referencing dynamic values inside a GraphQL query. When fetching a query from the server, we also need to provide as input the actual set of values to use for the variables declared inside the query:
In the above,
ID! is the type of the
$id variable. That is, it is a required ID.
When sending a network request to fetch the query above, we need to provide both the query, and the variables to be used for this particular execution of the query. For example:
Fetching the above query and variables from the server would produce the following response:
- Note that changing the value of the
idvariable used as input would of course produce a different response.
Fragments can also reference variables that have been declared by a query:
- Even though the fragment above doesn't declare the
$scalevariable directly, it can still reference it. Doing so makes it so any query that includes this fragment, either directly or transitively, must declare the variable and its type, otherwise an error will be produced.
- In other words, query variables are available globally by any fragment that is a descendant of the query.
- A fragment which references a global variable can only be included (directly or transitively) in a query which defines that global variable.
In Relay, fragment declarations inside components can also reference query variables:
- The above fragment could be included by multiple queries, and rendered by different components, which means that any query that ends up rendering/including the above fragment must declare the
- If any query that happens to include this fragment doesn't declare the
$scalevariable, an error will be produced by the Relay Compiler at build time, ensuring that an incorrect query never gets sent to the server (sending a query with missing variable declarations will also produce an error in the server).
However, in order to prevent bloating queries with global variable declarations, Relay also provides a way to declare variables that are scoped locally to a fragment using the
- Note that when passing
@argumentsto a fragment, we can pass a literal value or pass another variable. The variable can be a global query variable, or another local variable declared via
- When we actually fetch
PictureComponent_useras part of a query, the
scalevalue passed to the
profile_picturefield will depend on the argument that was provided by the parent of
UserComponent_userthe value of
$scalewill be 2.0.
OtherUserComponent_user, the value of
$scalewill be whatever value we pass to the server for the
$pictureScalevariable when we fetch the query.
Fragments that expect arguments can also declare default values, making the arguments optional:
- Not passing the argument to
PictureComponent_usermakes it use the default value for its locally declared
$scalevariable, in this case 2.0.
If you want to access the variables that were set at the query root, the recommended approach is to pass the variables down the component tree in your application, using props, or your own application-specific context.
Relay currently does not expose the resolved variables (i.e. after applying argument definitions) for a specific fragment, and you should very rarely need to do so.
Is this page useful?