Homepage
Link to WPGraphQL on Github
Link to WPGraphQL on WordPress.org

Posts and Pages

WPGraphQL provides support for querying Posts, Pages and Custom Post Types in various ways.

This page will be most useful for users what are familiar with GraphQL Concepts and understand the basics of writing GraphQL Queries.

Querying Posts

WPGraphQL supports querying posts and pages, as well as Custom Post Types that are registered to show in the GraphQL Schema.

Below are some common examples of querying posts with WPGraphQL. The below examples apply to Posts, Pages and Custom Post Types.

Lists of Posts

Below is an example of querying a list of posts. In this example we ask for posts, and then on the posts field we ask for edges, node, then the id, title and date of each node (each post).

Screenshot of a Query for Posts, Edges and node

Below is the same query, but asking for the nodes directly, skipping the edges field.

Screenshot of a Query for Posts, Edges and node

Edges? Nodes? Huh? If you’re not yet familiar with GraphQL Connections, edges and nodes will look like a foreign concept. To get a better understanding of Edges, Nodes and other conventions of GraphQL Connections: Read the GraphQL Connections Guide

Filtering a List of Posts

Queries for Connections can be filtered. Below are some examples of filtering using the where argument. There are many options available to filter posts, so it’s recommended to use a tool such as GraphiQL to get familiar with the options available to filter.

Query posts written by a specific author

This example shows querying posts written by a specific author (using the author’s DatabaseId)

Screenshot of a GraphQL Query for posts written by a specific author

Query posts by specific title

This example shows querying posts with a specific title.

Screenshot of a GraphQL Query for posts for a specific title

Query posts by specific search keyword

This example shows querying posts using a search keyword.

Screenshot of a GraphQL Query for posts using a search keyword

Single Post by Global ID

Below is an example of querying a single post using the GraphQL Global ID.

Screenshot of a GraphQL query for a single post using the Global ID

Single Post by Database ID

Below is an example of querying a single post using the Database ID as an identifier. In addition to passing a value for id, we also declare the idType to be DATABASE_ID.

Screenshot of a query for a post by Database ID

Single Post by URI

Below is an example of querying a single post using the URI (the path to the post) as an identifier.

Single Post by Slug

Below is an example of querying a single post using the slug as the ID.

NOTE: Slugs are only unique identifiers for non-hierarchcial post-types. Hierarchical post types cannot query single nodes by slug as there can be many items with the same slug. Fore example, you could have /company/about and /products/about both as Pages with an about slug.

Mutations

WPGraphQL provides Mutations (the ability to change data through GraphQL) for Posts, Pages and Custom Post Types that are configured to show in the GraphQL Schema.

WPGraphQL adheres to core access control rights, ensuring data can only be created, updated or deleted by users that have proper permission to do so. Learn more in our WPGraphQL Security guide.

Create Post

Below is an example of a GraphQL Mutation to create a post.

There are 2 required input fields to create a post: clientMutationId and title.

This Mutation will only succeed for users with proper capabilities to create posts (of the post type being created).

Successful Mutation

If the user executing the mutation is authenticated and has proper capabilities to create a post, the post will be created and the fields asked for in response will be returned.

Screenshot showing a successful mutation to create a post

Unsuccessful Mutation

If the user executing the mutation is not authenticated, or does not have proper capabilities to create a post, the post will not be created and an error will be returned.

Screenshot showing a failed mutation to create a post

Update Post

Below is an example of of a GraphQL Mutation to update a post. In order to update a post, the ID of the post must be known and provided to the input.

Successful Mutation

If the user making the request is authenticated and has proper capabilities to update the post, the post will be updated and the specified fields of the post being updated will be returned in the response.

Screenshot of a successful Mutation to update a post

Unsuccessful Mutation

If the user executing the mutation is not authenticated, or does not have proper capabilities to create a post, the post will not be created and an error will be returned.

Delete Post

Below is an example of of a GraphQL Mutation to delete a post. In order to delete a post, the ID of the post must be known and provided to the input.

Successful Mutation

If the user executing the mutation to delete a post is authenticated and has proper capabilities to delete the post of the provided ID, the post will be deleted from WordPress and the fields asked for will be returned.

Screenshot of a successful Mutation to delete a post

Unsuccessful Mutation

If the user executing the mutation to delete a post is not authenticated or does not have proper capabilities to delete a post, the post will not be deleted from WordPress and an error will be returned.

Screenshot of an unsuccessful Mutation to delete a post