On this page, you’ll learn in detail about how to query a WPGraphQL server.
At its simplest, GraphQL is about asking for fields on objects. Let’s start by looking at a simple query and the result we get when we run it:
You can immediately see that the query has the same shape as the result. This is essential to GraphQL. As a consumer the results are predictable as you get back data in the shape you requested it, and the server is aware of what fields are being asked for before execution.
In this case, the
get_bloginfo( 'url' );
In the previous example, we just asked for the
In this example, we’re querying multiple different fields from different settings groups in a single request.
If the only thing GraphQL could do was traverse objects and their fields, GraphQL would already be useful for data fetching. But when you add the ability to pass arguments to fields, things get much more interesting.
In a system like REST, you can only pass one set of arguments, the query parameters and URL segments in your request. But in GraphQL, each field and
Arguments can be of many different types. In the above example, for
You may have noticed that since the result object fields match the name of the field in the query, but don’t include arguments, you can’t directly query for the same field with different arguments. That’s why we need aliases. Aliases in GraphQL let you rename the result of the field to anything you want:
In the above example, the two
pageBy fields would have conflicted, but since we can alias them to different names, we can get both results in one request.
Aliases can also be very powerful when building re-usable components, as you can alias the request to make sure the data comes back in the shape your component is expecting without making the transformation on the client.
Let’s say we had a relatively complicated page in our app that let us look at 2 pages side-by-side. You could imagine that query could quickly get complicated because we would need to repeat the fields at least once, one for each page being compared.
That’s why GraphQL includes reusable units called fragments. Fragments let you construct sets of fields, and then include them in queries where you need to. Here’s an example of how you could solve the above situation with fragments:
You can see how the above query would be pretty repetitive if the fields were repeated. The concept of fragments is frequently used to split complicated application data requirements into smaller chunks, especially when you need to combine lots of UI components with different fragments into one initial data fetch.
In component based UI development, fragments can be co-located with the components that render the data, easing the maintenance burden as the data dependencies are managed where the data is needed for rendering.
Up until now, we’ve been using a shorthand syntax where we omit the query keyword and the query name, but in production apps, it’s useful to use these things to make our code less ambiguous.
Here’s an example that includes the
GraphQL will respect the operation type query, mutation or subscription (NOTE: WPGraphQL currently doesn’t support subscriptions, but could
The operation name is a meaningful and explicit name for your operation. It is only required in multi-operation requests, but its use is encouraged because it is very helpful for debugging and server-side logging.
So far, we have been writing all our arguments inside the query string. But in most applications, the arguments to fields will be dynamic: For example, there might be a dropdown that lets you select the Post Status to filter posts by, or a search field, or a set of filters.
It wouldn’t be a good idea to pass these variables into the query string directly, because then our client-side code would need to dynamically manipulate the query string at runtime, and serialize it into GraphQL-specific format. Instead, GraphQL has a first-class way to factor dynamic values out of the query, and pass them as a separate dictionary. These are called variables.
When we start working with variables, we need to do three things:
- Replace the static value in the query with
$variableNameas one of the variables accepted by the query
variableName: valuein the separate, JSON variables dictionary
Here’s an example of using variables:
Now, in our client code, we can simply pass a different variable rather than needing to construct an entirely new query.
This is also
The variable definitions are the part that looks
All declared variables must be either
Variable definitions can be optional or required. In the case above, since there isn’t an
! next to the
Episode type, it’s optional. But if the field you are passing the variable into requires a non-null argument, then the variable has to be required as well.
To learn more about the syntax for these variable definitions, it’s useful to learn more about the GraphQL schema language.
Default values can also be assigned to the variables in the query by adding the default value after the type declaration.
When default values are provided for all variables, you can call the query without passing any variables. If any variables are passed as part of the variables dictionary, they will override the defaults.
We discussed above how variables enable us to avoid doing manual string interpolation to construct dynamic queries. Passing variables in arguments solves a pretty big class of these problems, but we might also need a way to dynamically change the structure and shape of our queries using variables. For example, we can imagine a UI component that has a summarized and detailed view, where one includes more fields than the other.
Let’s construct a query for such a component:
Try editing the variables above to instead
We needed to use a feature in GraphQL called a directive. A directive can be attached to a field or fragment
@include(if: Boolean)Only include this field in the result if the argument is
@skip(if: Boolean)Skip this field if the argument is
Directives can be useful to get out of situations where you otherwise would need to do string manipulation to add and remove fields in your query. Server implementations may also add experimental features by defining completely new directives.
NOTE: WPGraphQL currently doesn’t have any custom directives defined, but if you have ideas, let us know!