Write your own WordPress database queries with WP_Query

In this tutorial I explain how you can write your own database queries in WordPress with WP_Query to fetch certain WordPress posts and pages from the database. In addition to creating custom queries, I will also show you how you can display the result of the query in a custom loop.

Why individual queries with WP_Query?

At the beginning of the article I would like to clarify when an individual query of the database with WP_Query makes sense at all. Because your own custom query is not always required to display WordPress posts.

WordPress uses the Main Query to perform a database query every time a page is accessed.

Custom queries are useful if, in addition to the main query, additional or different content is to be fetched from the database and displayed. For example, if a list of the last articles should be displayed under a single post or if the sidebar should display all child pages of this page on a static page.

A separate query is not necessary if the displayed content is only to be slightly adapted. For performance reasons, it is advisable to adapt the main query with appropriate filters instead of creating an additional custom query.

Examples of this: The categories should show CPTs in addition to posts, the order of posts should be changed or a certain category should be excluded in the blog. For these use cases it is sufficient to modify the main query.

You can use the WP_Query class to create your own database query to display certain WordPress posts. More on this in the next section.

The WP_Query class

The WP_Query class is one of the most important parts of WordPress.

It is used to query content from the wp_posts table of the WordPress database . All posts, static pages and custom post types of your WordPress website are fetched from the database using this class. The main query is also initialized with it.

WP_Query is a helper class to facilitate WordPress database queries. It is sufficient to specify an array with arguments without having to manually create complicated SQL queries and database joins. The use of the class also ensures protection against SQL injections.

The class exists for reading posts and therefore does not cover all CRUD operations . Functions such as wp_insert_post or wp_update_post are available for this. If you want to query the data from tables other than wp_posts , you have to use the very similar classes WP_Meta_Query , WP_Comment_Query or WP_User_Query .

Create custom query with WP_Query

To create your own database query for WordPress Posts, a new object or instance of the WP_Query class can be created:

 $custom_query = new WP_Query( $args );

To define our custom query, we pass an array of arguments to the class. Detailed knowledge of SQL is therefore not necessary. The following example provides us with the five most recent posts from the category with the slug featured :

 // Get Posts from Database. $query_arguments = array( 'category_name' => 'featured', 'posts_per_page' => 5, 'ignore_sticky_posts' => true, ); $custom_query = new WP_Query( $query_arguments );

A complete list of all parameters can be found in the Code Reference for WP_Query .

Output the result of the database query in a loop

The result of our custom query can then be displayed in a separate WordPress loop . In this example, the title is output for each contribution:

 // The Query $custom_query = new WP_Query( $args ); // The Loop if ( $custom_query->have_posts() ) { while ( $custom_query->have_posts() ) { $custom_query->the_post(); // Display Post Title the_title( '<h2 class="entry-title">', '</h2>' ); } wp_reset_postdata(); }

Important: When using an additional custom query and custom loop, this must be completed with the wp_reset_postdata () function. This resets the global variable $ post and restores the current post of the main query.