Posts
Learn about how to interact with Posts using WPGraphQL
Posts are at the heart of WordPress. On this page, we'll take a look at various ways to interact with Posts using WPGraphQL.
Queries
WPGraphQL comes with RootQuery fields built-in to query Post data. You can query for lists of posts, or individual posts. Below, we'll look at some common examples for querying for Posts.
List of Posts
In this example, we query a list of Post nodes. By default, WPGraphQL will return 10 items.
GraphiQL Loading...Arguments
In many cases, exactly 10 posts won't be what you need for your application. So we can use arguments
on the posts
field to declare how many items we want.
Here we're using the first
argument to declare that we want the first 5 posts.
You can adjust the number of items as well. Here we'll ask for just 1 Post:
GraphiQL Loading...whereArgs
Post connections can be further filtered by using whereArgs
.
The args available are largely similar to what's available (and end up mapping to) to the underlying WP_Query. We'll look at a few quick examples, but it's probably best for you to spend some time exploring the Schema Docs to see what options are available.
Also, keep in mind that the entire WPGraphQL Schema is filterable should you need to extend the Schema and provide custom arguments for your applications needs.
- Here's an example of using the
where
argument to pass in aDateQuery
to specify a specific date for which to grab posts for
- Here's an example of using the
where
argument to find a post with a specific title:
Pagination
When querying a list of nodes (Posts), it's common to need to paginate to fetch more items. The Schema exposes some helpful fields we can ask for to know if there are more items to fetch.
Fields that are helpful for knowing if there are more items to paginate:
- pageInfo.hasNextPage: Whether there are more items going forward
- pageInfo.hasPreviousPage: Whether there are more items going backward
- pageInfo.endCursor: The cursor for the last item in the list
- pageInfo.startCursor: The cursor for the first item in the list
The arguments used for pagination are:
- first: The number of items to fetch. To be used along with
after
for forward pagination. - after: The cursor to reference where to fetch from. To be used along with
first
for forward pagination. - last: The number of items to fetch. To be used along with
before
for backward pagination. - before: The cursor to reference where to fetch from. To be used along with
last
for backward pagination.
pageInfo
Here is an example of asking for pageInfo
fields to see if there are more items in the list of
data.
You can see that we ask for the field pageInfo
, and on that we ask for hasNextPage
and
endCursor
.
The hasNextPage
field will be either true
or false
, and the endCursor
will be an opaque
string that acts as a reference to the last node returned in the query.
The cursor can then be used as an argument in a follow-up query, to ask for posts after
that point
in the dataset.
first
We can use the first
argument to declare how many items we want from the "front" of the dataset.
In this case, we're telling WPGraphQL we want the first 5 most recent posts.
In the response, we see that hasNextPage
responds with true
, meaning there are more posts, and
we can use the endCursor
to ask for the posts after
the last item in this list.
after
The after
argument is to be used in conjunction with the first
argument for pagination purposes.
When querying for a list of posts, it's common to need to paginate. When we ask for the first 10
posts, there's a good chance we'll want to ask for the first 10
posts after the final post in
that list.
last
We can use the last
argument to declare how many items we want from the "back" of the dataset. In
this case, we're telling WPGraphQL we want the last 5 (oldest) posts.
At the bottom of the list will be the oldest item in the dataset. The top item in the list will be the newest of the 5 displayed (because we're going backward here).
GraphiQL Loading...So, we can see that hasPreviousPage
is set to true, which means we have more items before
this.
We can take the startCursor
and use that as the value of our next query as our before
value.
before
Here, we take the startCursor
from our previous query, and use it as the value for our before
input.
So, what we're saying is that we want 5
more items before the startCursor
in our previous query.
As long as hasPreviousPage
returns true, that means we have more data that we can paginate through.
Post
If we know the ID of a Post, we can query for the post individually like so:
GraphiQL Loading...idType argument
Sometimes you need to query an individual Post, but you don't have the ID.
Using the idType
argument, we can get individual nodes with alternative unique identifiers.
Here's an example of getting a post by it's URI.
GraphiQL Loading...Here's an example of getting a post by it's database ID.
GraphiQL Loading...Mutations
In this section, we'll look at various ways to mutate Posts.
Create Post
This is an example of a mutation to create a Post.
There are two required input fields to create a post, clientMutationId
and title
.
Here you can see that we define our input variable to be of the type CreatePostInput!
.
By defining our input in this way, it allows for flexibility for the input variables. Whatever we
input will validate against the shape of the CreatePostInput!
Type. This means any of the nonNull
input fields will need to be required, but any of the other fields are optional, but have to be of
the specified Type defined in the Schema.
Update Post
Below is an example mutation to update a post. For this, we must know the ID of the Post.
GraphiQL Loading...Delete Post
Below is an example mutation to delete a post. For this, we must know the ID of the Post.
GraphiQL Loading...