A Complete Guide to WP_Query Parameters for Custom Post Types and Taxonomies

In WordPress development, WP_Query is the core class for building custom queries. This article explains how to query posts from a custom post type filtered by a custom taxonomy, with a full parameter reference.

Example: Querying Popular Movies by Region

Assume we have a custom post type movie and a custom taxonomy areas (for regions). We want to query movies from the regions with slugs red and blue, ordered by a custom field views in ascending order.

<?php
$args = array(
    'post_type'      => 'movie', // Query the 'movie' post type
    'meta_key'       => 'views', // Sort by the 'views' custom field
    'orderby'        => 'meta_value_num', // Sort numerically
    'order'          => 'ASC', // Ascending order
    'tax_query'      => array( // Taxonomy query parameters
        array(
            'taxonomy'         => 'areas', // Custom taxonomy: areas
            'field'            => 'slug', // Match by term slug
            'terms'            => array( 'red', 'blue' ), // Target region slugs
            'include_children' => true, // Include child terms
            'operator'         => 'IN' // Match any term in the array
        ),
    ),
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        // Output each movie's content, e.g., the_title();
    }
}
wp_reset_postdata(); // Restore global post data
?>

Key Parameter Breakdown

• post_type: Specifies the post type to query (e.g., movie).
• tax_query: An array for taxonomy filtering.
  • taxonomy: The custom taxonomy name.
  • field: How to match terms (slug, id, etc.).
  • terms: The term(s) to match (slug, ID, or array).
  • operator: Matching logic (IN matches any term in the array).
• meta_key & orderby: Used together to sort by a custom field. meta_value_num ensures numeric sorting.

Complete WP_Query Parameter Reference

Below is a concise reference of core WP_Query parameters.

Basic Parameters

• Author: author, author_name.
• Category & Tag: cat, category_name, tag, tag_id.
• Post & Page: p (ID), name (slug), post__in, post__not_in.

Post Type & Status

'post_type' => array('post', 'page', 'movie'), // Multiple types
'post_status' => array('publish', 'pending', 'draft'), // Multiple statuses
// Use 'any' for all (non-excluded) types or statuses
'post_type' => 'any',
'post_status' => 'any',

Pagination & Ordering

• Pagination: posts_per_page, paged, nopaging.
• Ordering: order (ASC/DESC), orderby (date, title, meta_value, rand, etc.).

Custom Field (Meta) Query

'meta_query' => array(
    array(
        'key'     => 'color',
        'value'   => 'blue',
        'compare' => '=', // Options: =, !=, >, >=, <, <=, LIKE, IN, BETWEEN
        'type'    => 'CHAR' // Options: NUMERIC, BINARY, CHAR, DATE, DECIMAL
    )
)

Date Parameters

Query by date components: year, monthnum, w (week), day, hour, minute, second.

Performance & Caching

• no_found_rows: Set to true to disable pagination count (improves performance, but breaks pagination).
• cache_results, update_post_term_cache, update_post_meta_cache: Typically keep as true for caching benefits.

Best Practices & Notes

1. Reset Queries: Always call wp_reset_postdata() after a custom WP_Query to restore global post data.
2. Avoid Conflicts: Do not use mutually exclusive parameters like post__in and post__not_in together.
3. Optimize Performance: Ensure database indexes exist for fields used in complex meta_query or tax_query.
4. Version Compatibility: Parameters like tax_query require WordPress 3.1 or later.

By combining these parameters, you can build virtually any post query needed for your WordPress theme or plugin.