Class: WP_Query

The WordPress Query class.


Properties

Name Type(s) Default Value Summary
query array Query vars set by the user
query_vars array Query vars, after parsing
tax_query object Taxonomy query, as passed to get_tax_sql()
meta_query object Metadata query container
date_query object Date query container
queried_object object | array Holds the data for a single object that is queried.

Holds the contents of a post, page, category, attachment.

queried_object_id integer The ID of the queried object.
request string Get post database query.
posts array List of posts.
post_count integer The amount of posts for the current query.
current_post integer Index of the current item in the loop.
in_the_loop boolean Whether the loop has started and the caller is in the loop.
post WP_Post The current post.
comments array The list of comments for current post.
comment_count integer The amount of comments for the posts.
current_comment integer The index of the comment in the comment loop.
comment integer Current comment ID.
found_posts integer The amount of found posts for the current query.

If limit clause was not used, equals $post_count.

max_num_pages integer The amount of pages.
max_num_comment_pages integer The amount of comment pages.
is_single boolean Signifies whether the current query is for a single post.
is_preview boolean Signifies whether the current query is for a preview.
is_page boolean Signifies whether the current query is for a page.
is_archive boolean Signifies whether the current query is for an archive.
is_date boolean Signifies whether the current query is for a date archive.
is_year boolean Signifies whether the current query is for a year archive.
is_month boolean Signifies whether the current query is for a month archive.
is_day boolean Signifies whether the current query is for a day archive.
is_time boolean Signifies whether the current query is for a specific time.
is_author boolean Signifies whether the current query is for an author archive.
is_category boolean Signifies whether the current query is for a category archive.
is_tag boolean Signifies whether the current query is for a tag archive.
is_tax boolean Signifies whether the current query is for a taxonomy archive.
is_search boolean Signifies whether the current query is for a search.
is_feed boolean Signifies whether the current query is for a feed.
is_comment_feed boolean Signifies whether the current query is for a comment feed.
is_trackback boolean Signifies whether the current query is for trackback endpoint call.
is_home boolean Signifies whether the current query is for the site homepage.
is_404 boolean Signifies whether the current query couldn't find anything.
is_embed boolean Signifies whether the current query is for an embed.
is_paged boolean Signifies whether the current query is for a paged result and not for the first page.
is_admin boolean Signifies whether the current query is for an administrative interface page.
is_attachment boolean Signifies whether the current query is for an attachment page.
is_singular boolean Signifies whether the current query is for an existing single post of any post type (post, attachment, page, custom post types).
is_robots boolean Signifies whether the current query is for the robots.txt file.
is_posts_page boolean Signifies whether the current query is for the page_for_posts page.

Basically, the homepage if the option isn't set for the static homepage.

is_post_type_archive boolean Signifies whether the current query is for a post type archive.
query_vars_hash boolean | string Stores the ->query_vars state like md5(serialize( $this->query_vars ) ) so we know whether we have to re-parse because something has changed
query_vars_changed Whether query vars have changed since the initial parse_query() call. Used to catch modifications to query vars made via pre_get_posts hooks.
thumbnails_cached boolean Set if post thumbnails are cached
stopwords array Cached list of search stopwords.
compat_fields
compat_methods

Methods

WP_Query:: __call( string $name, array $arguments )

Make private/protected methods readable for backward compatibility. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$name string

Method to call.

$arguments array

Arguments to pass when calling.

Returns

mixed | false

Return value of the callback, false otherwise.


WP_Query:: __construct( string | array $query = '' )

Constructor. Since 1.5.0.

Sets up the WordPress query, if parameter is not empty.

Arguments

Name Type(s) Default Value Description
$query string | array

URL query string or array of vars.


WP_Query:: __get( string $name )

Make private properties readable for backward compatibility. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$name string

Property to get.

Returns

mixed

Property.


WP_Query:: __isset( string $name )

Make private properties checkable for backward compatibility. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$name string

Property to check if set.

Returns

boolean

Whether the property is set.


WP_Query:: fill_query_vars( array $array )

Fills in the query variables, which do not exist within the parameter. Since 2.1.0. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$array array

Defined query variables.

Returns

array

Complete query variables with undefined ones filled in empty.


WP_Query:: get( string $query_var, mixed $default = '' )

Retrieve query variable. Since 1.5.0. Since 3.9.0.

Arguments

Name Type(s) Default Value Description
$query_var string

Query variable key.

$default mixed

Optional. Value to return if the query variable is not set. Default empty.

Returns

mixed

Contents of the query variable.


WP_Query:: get_posts( )

Retrieves an array of posts based on query variables. Since 1.5.0.

There are a few filters and actions that can be used to modify the post database query.

Returns

array<mixed,WP_Post> | array<mixed,integer>

Array of post objects or post IDs.


WP_Query:: get_queried_object( )

Retrieve queried object. Since 1.5.0.

If queried object is not set, then the queried object will be set from the category, tag, taxonomy, posts page, single post, page, or author query variable. After it is set up, it will be returned.

Returns

object


WP_Query:: get_queried_object_id( )

Retrieve ID of the current queried object. Since 1.5.0.

Returns

integer


WP_Query:: get_search_stopwords( )

Retrieve stopwords used when parsing search terms. Since 3.7.0.

Returns

array

Stopwords.


WP_Query:: have_comments( )

Whether there are more comments available. Since 2.2.0.

Automatically rewinds comments when finished.

Returns

boolean

True, if more comments. False, if no more posts.


WP_Query:: have_posts( )

Determines whether there are more posts available in the loop. Since 1.5.0.

Calls the \'loop_end' action when the loop is complete.

Returns

boolean

True if posts are available, false if end of loop.


WP_Query:: init( )

Initiates object properties and sets default values. Since 1.5.0.


WP_Query:: init_query_flags( )

Resets query flags to false. Since 2.0.0.

The query flags are what page info WordPress was able to figure out.


WP_Query:: is_404( )

Is the query a 404 (returns no results)? Since 3.1.0.

Returns

boolean


WP_Query:: is_archive( )

Is the query for an existing archive page? Since 3.1.0.

Month, Year, Category, Author, Post Type archive...

Returns

boolean


WP_Query:: is_attachment( mixed $attachment = '' )

Is the query for an existing attachment page? Since 3.1.0.

Arguments

Name Type(s) Default Value Description
$attachment mixed

Attachment ID, title, slug, or array of such.

Returns

boolean


WP_Query:: is_author( mixed $author = '' )

Is the query for an existing author archive page? Since 3.1.0.

If the $author parameter is specified, this function will additionally check if the query is for one of the authors specified.

Arguments

Name Type(s) Default Value Description
$author mixed

Optional. User ID, nickname, nicename, or array of User IDs, nicknames, and nicenames

Returns

boolean


WP_Query:: is_category( mixed $category = '' )

Is the query for an existing category archive page? Since 3.1.0.

If the $category parameter is specified, this function will additionally check if the query is for one of the categories specified.

Arguments

Name Type(s) Default Value Description
$category mixed

Optional. Category ID, name, slug, or array of Category IDs, names, and slugs.

Returns

boolean


WP_Query:: is_comment_feed( )

Is the query for a comments feed? Since 3.1.0.

Returns

boolean


WP_Query:: is_comments_popup( )

This method is deprecated.

Whether the current URL is within the comments popup window. Since 3.1.0.

Returns

boolean


WP_Query:: is_date( )

Is the query for an existing date archive? Since 3.1.0.

Returns

boolean


WP_Query:: is_day( )

Is the query for an existing day archive? Since 3.1.0.

Returns

boolean


WP_Query:: is_embed( )

Is the query for an embedded post? Since 4.4.0.

Returns

boolean


WP_Query:: is_feed( string | array $feeds = '' )

Is the query for a feed? Since 3.1.0.

Arguments

Name Type(s) Default Value Description
$feeds string | array

Optional feed types to check.

Returns

boolean


WP_Query:: is_front_page( )

Is the query for the front page of the site? Since 3.1.0.

This is for what is displayed at your site's main URL.

Depends on the site's "Front page displays" Reading Settings 'show_on_front' and 'page_on_front'.

If you set a static page for the front page of your site, this function will return true when viewing that page.

Otherwise the same as @see WP_Query::is_home()

Returns

boolean

True, if front of site.


WP_Query:: is_home( )

Is the query for the blog homepage? Since 3.1.0.

This is the page which shows the time based blog content of your site.

Depends on the site's "Front page displays" Reading Settings 'show_on_front' and 'page_for_posts'.

If you set a static page for the front page of your site, this function will return true only on the page you set as the "Posts page".

Returns

boolean

True if blog view homepage.


WP_Query:: is_main_query( )

Is the query the main query? Since 3.3.0.

Returns

boolean


WP_Query:: is_month( )

Is the query for an existing month archive? Since 3.1.0.

Returns

boolean


WP_Query:: is_page( integer | string | array $page = '' )

Is the query for an existing single page? Since 3.1.0.

If the $page parameter is specified, this function will additionally check if the query is for one of the pages specified.

Arguments

Name Type(s) Default Value Description
$page integer | string | array

Optional. Page ID, title, slug, path, or array of such. Default empty.

Returns

boolean

Whether the query is for an existing single page.


WP_Query:: is_paged( )

Is the query for paged result and not for the first page? Since 3.1.0.

Returns

boolean


WP_Query:: is_post_type_archive( mixed $post_types = '' )

Is the query for an existing post type archive page? Since 3.1.0.

Arguments

Name Type(s) Default Value Description
$post_types mixed

Optional. Post type or array of posts types to check against.

Returns

boolean


WP_Query:: is_preview( )

Is the query for a post or page preview? Since 3.1.0.

Returns

boolean


WP_Query:: is_robots( )

Is the query for the robots file? Since 3.1.0.

Returns

boolean


Is the query for a search? Since 3.1.0.

Returns

boolean


WP_Query:: is_single( integer | string | array $post = '' )

Is the query for an existing single post? Since 3.1.0.

Works for any post type excluding pages.

If the $post parameter is specified, this function will additionally check if the query is for one of the Posts specified.

Arguments

Name Type(s) Default Value Description
$post integer | string | array

Optional. Post ID, title, slug, path, or array of such. Default empty.

Returns

boolean

Whether the query is for an existing single post.


WP_Query:: is_singular( string | array $post_types = '' )

Is the query for an existing single post of any post type (post, attachment, page, custom post types)? Since 3.1.0.

If the $post_types parameter is specified, this function will additionally check if the query is for one of the Posts Types specified.

Arguments

Name Type(s) Default Value Description
$post_types string | array

Optional. Post type or array of post types. Default empty.

Returns

boolean

Whether the query is for an existing single post of any of the given post types.


WP_Query:: is_tag( mixed $tag = '' )

Is the query for an existing tag archive page? Since 3.1.0.

If the $tag parameter is specified, this function will additionally check if the query is for one of the tags specified.

Arguments

Name Type(s) Default Value Description
$tag mixed

Optional. Tag ID, name, slug, or array of Tag IDs, names, and slugs.

Returns

boolean


WP_Query:: is_tax( mixed $taxonomy = '', mixed $term = '' )

Is the query for an existing custom taxonomy archive page? Since 3.1.0.

If the $taxonomy parameter is specified, this function will additionally check if the query is for that specific $taxonomy.

If the $term parameter is specified in addition to the $taxonomy parameter, this function will additionally check if the query is for one of the terms specified.

Arguments

Name Type(s) Default Value Description
$taxonomy mixed

Optional. Taxonomy slug or slugs.

$term mixed

Optional. Term ID, name, slug or array of Term IDs, names, and slugs.

Returns

boolean

True for custom taxonomy archive pages, false for built-in taxonomies (category and tag archives).


WP_Query:: is_time( )

Is the query for a specific time? Since 3.1.0.

Returns

boolean


WP_Query:: is_trackback( )

Is the query for a trackback endpoint call? Since 3.1.0.

Returns

boolean


WP_Query:: is_year( )

Is the query for an existing year archive? Since 3.1.0.

Returns

boolean


WP_Query:: lazyload_comment_meta( mixed $check, integer $comment_id )

This method is deprecated.

Lazyload comment meta for comments in the loop. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$check mixed
$comment_id integer

Returns

mixed


WP_Query:: lazyload_term_meta( mixed $check, integer $term_id )

This method is deprecated.

Lazyload term meta for posts in the loop. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$check mixed
$term_id integer

Returns

mixed


WP_Query:: next_comment( )

Iterate current comment index and return WP_Comment object. Since 2.2.0.

Returns

WP_Comment

Comment object.


WP_Query:: next_post( )

Set up the next post and iterate current post index. Since 1.5.0.

Returns

WP_Post

Next post.


WP_Query:: parse_order( string $order )

Parse an 'order' query variable and cast it to ASC or DESC as necessary. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$order string

The 'order' query variable.

Returns

string

The sanitized 'order' query variable.


WP_Query:: parse_orderby( string $orderby )

Converts the given orderby alias (if allowed) to a properly-prefixed value. Since 4.0.0.

Arguments

Name Type(s) Default Value Description
$orderby string

Alias for the field to order by.

Returns

string | false

Table-prefixed value to used in the ORDER clause. False otherwise.


WP_Query:: parse_query( string | array $query = '' )

Parse a query string and set query type booleans. Since 1.5.0. Since 4.2.0. Since 4.4.0. Since 4.5.0. Since 4.6.0. Since 4.9.0. Since 5.1.0.

Arguments

Name Type(s) Default Value Description
$query string | array

{ Optional. Array or string of Query parameters.

@type int          $attachment_id           Attachment post ID. Used for 'attachment' post_type.
@type int|string   $author                  Author ID, or comma-separated list of IDs.
@type string       $author_name             User 'user_nicename'.
@type array        $author__in              An array of author IDs to query from.
@type array        $author__not_in          An array of author IDs not to query from.
@type bool         $cache_results           Whether to cache post information. Default true.
@type int|string   $cat                     Category ID or comma-separated list of IDs (this or any children).
@type array        $category__and           An array of category IDs (AND in).
@type array        $category__in            An array of category IDs (OR in, no children).
@type array        $category__not_in        An array of category IDs (NOT in).
@type string       $category_name           Use category slug (not name, this or any children).
@type array|int    $comment_count           Filter results by comment count. Provide an integer to match
                                            comment count exactly. Provide an array with integer 'value'
                                            and 'compare' operator ('=', '!=', '>', '>=', '<', '<=' ) to
                                            compare against comment_count in a specific way.
@type string       $comment_status          Comment status.
@type int          $comments_per_page       The number of comments to return per page.
                                            Default 'comments_per_page' option.
@type array        $date_query              An associative array of WP_Date_Query arguments.
                                            See WP_Date_Query::__construct().
@type int          $day                     Day of the month. Default empty. Accepts numbers 1-31.
@type bool         $exact                   Whether to search by exact keyword. Default false.
@type string|array $fields                  Which fields to return. Single field or all fields (string),
                                            or array of fields. 'id=>parent' uses 'id' and 'post_parent'.
                                            Default all fields. Accepts 'ids', 'id=>parent'.
@type int          $hour                    Hour of the day. Default empty. Accepts numbers 0-23.
@type int|bool     $ignore_sticky_posts     Whether to ignore sticky posts or not. Setting this to false
                                            excludes stickies from 'post__in'. Accepts 1|true, 0|false.
                                            Default 0|false.
@type int          $m                       Combination YearMonth. Accepts any four-digit year and month
                                            numbers 1-12. Default empty.
@type string       $meta_compare            Comparison operator to test the 'meta_value'.
@type string       $meta_compare_key        Comparison operator to test the 'meta_key'.
@type string       $meta_key                Custom field key.
@type array        $meta_query              An associative array of WP_Meta_Query arguments. See WP_Meta_Query.
@type string       $meta_value              Custom field value.
@type int          $meta_value_num          Custom field value number.
@type int          $menu_order              The menu order of the posts.
@type int          $monthnum                The two-digit month. Default empty. Accepts numbers 1-12.
@type string       $name                    Post slug.
@type bool         $nopaging                Show all posts (true) or paginate (false). Default false.
@type bool         $no_found_rows           Whether to skip counting the total rows found. Enabling can improve
                                            performance. Default false.
@type int          $offset                  The number of posts to offset before retrieval.
@type string       $order                   Designates ascending or descending order of posts. Default 'DESC'.
                                            Accepts 'ASC', 'DESC'.
@type string|array $orderby                 Sort retrieved posts by parameter. One or more options may be
                                            passed. To use 'meta_value', or 'meta_value_num',
                                            'meta_key=keyname' must be also be defined. To sort by a
                                            specific `$meta_query` clause, use that clause's array key.
                                            Accepts 'none', 'name', 'author', 'date', 'title',
                                            'modified', 'menu_order', 'parent', 'ID', 'rand',
                                            'relevance', 'RAND(x)' (where 'x' is an integer seed value),
                                            'comment_count', 'meta_value', 'meta_value_num', 'post__in',
                                            'post_name__in', 'post_parent__in', and the array keys
                                            of `$meta_query`. Default is 'date', except when a search
                                            is being performed, when the default is 'relevance'.

@type int          $p                       Post ID.
@type int          $page                    Show the number of posts that would show up on page X of a
                                            static front page.
@type int          $paged                   The number of the current page.
@type int          $page_id                 Page ID.
@type string       $pagename                Page slug.
@type string       $perm                    Show posts if user has the appropriate capability.
@type string       $ping_status             Ping status.
@type array        $post__in                An array of post IDs to retrieve, sticky posts will be included
@type string       $post_mime_type          The mime type of the post. Used for 'attachment' post_type.
@type array        $post__not_in            An array of post IDs not to retrieve. Note: a string of comma-
                                            separated IDs will NOT work.
@type int          $post_parent             Page ID to retrieve child pages for. Use 0 to only retrieve
                                            top-level pages.
@type array        $post_parent__in         An array containing parent page IDs to query child pages from.
@type array        $post_parent__not_in     An array containing parent page IDs not to query child pages from.
@type string|array $post_type               A post type slug (string) or array of post type slugs.
                                            Default 'any' if using 'tax_query'.
@type string|array $post_status             A post status (string) or array of post statuses.
@type int          $posts_per_page          The number of posts to query for. Use -1 to request all posts.
@type int          $posts_per_archive_page  The number of posts to query for by archive page. Overrides
                                            'posts_per_page' when is_archive(), or is_search() are true.
@type array        $post_name__in           An array of post slugs that results must match.
@type string       $s                       Search keyword(s). Prepending a term with a hyphen will
                                            exclude posts matching that term. Eg, 'pillow -sofa' will
                                            return posts containing 'pillow' but not 'sofa'. The
                                            character used for exclusion can be modified using the
                                            the 'wp_query_search_exclusion_prefix' filter.
@type int          $second                  Second of the minute. Default empty. Accepts numbers 0-60.
@type bool         $sentence                Whether to search by phrase. Default false.
@type bool         $suppress_filters        Whether to suppress filters. Default false.
@type string       $tag                     Tag slug. Comma-separated (either), Plus-separated (all).
@type array        $tag__and                An array of tag ids (AND in).
@type array        $tag__in                 An array of tag ids (OR in).
@type array        $tag__not_in             An array of tag ids (NOT in).
@type int          $tag_id                  Tag id or comma-separated list of IDs.
@type array        $tag_slug__and           An array of tag slugs (AND in).
@type array        $tag_slug__in            An array of tag slugs (OR in). unless 'ignore_sticky_posts' is
                                            true. Note: a string of comma-separated IDs will NOT work.
@type array        $tax_query               An associative array of WP_Tax_Query arguments.
                                            See WP_Tax_Query->queries.
@type string       $title                   Post title.
@type bool         $update_post_meta_cache  Whether to update the post meta cache. Default true.
@type bool         $update_post_term_cache  Whether to update the post term cache. Default true.
@type bool         $lazy_load_term_meta     Whether to lazy-load term meta. Setting to false will
                                            disable cache priming for term meta, so that each
                                            get_term_meta() call will hit the database.
                                            Defaults to the value of `$update_post_term_cache`.
@type int          $w                       The week number of the year. Default empty. Accepts numbers 0-53.
@type int          $year                    The four-digit year. Default empty. Accepts any four-digit year.

}


WP_Query:: parse_query_vars( )

Reparse the query vars. Since 1.5.0.


Generates SQL for the WHERE clause based on passed search terms. Since 3.7.0.

Arguments

Name Type(s) Default Value Description
$q array

Query variables.

Returns

string

WHERE clause.


WP_Query:: parse_search_order( array &$q )

Generates SQL for the ORDER BY condition based on passed search terms. Since 3.7.0.

Arguments

Name Type(s) Default Value Description
$q array

Query variables.

Returns

string

ORDER BY clause.


WP_Query:: parse_search_terms( array<mixed,string> $terms )

Check if the terms are suitable for searching. Since 3.7.0.

Uses an array of stopwords (terms) that are excluded from the separate term matching when searching for posts. The list of English stopwords is the approximate search engines list, and is translatable.

Arguments

Name Type(s) Default Value Description
$terms array<mixed,string>

Array of terms to check.

Returns

array

Terms that are not stopwords.


WP_Query:: parse_tax_query( array &$q )

Parses various taxonomy related query vars. Since 3.1.0.

For BC, this method is not marked as protected. See [28987].

Arguments

Name Type(s) Default Value Description
$q array

The query variables. Passed by reference.


WP_Query:: query( string | array $query )

Sets up the WordPress query by parsing query string. Since 1.5.0.

Arguments

Name Type(s) Default Value Description
$query string | array

URL query string or array of query arguments.

Returns

array<mixed,WP_Post> | array<mixed,integer>

Array of post objects or post IDs.


WP_Query:: reset_postdata( )

After looping through a nested query, this function restores the $post global to the current post in this query. Since 3.7.0.


WP_Query:: rewind_comments( )

Rewind the comments, resets the comment index and comment to first. Since 2.2.0.


WP_Query:: rewind_posts( )

Rewind the posts and reset post index. Since 1.5.0.


WP_Query:: set( string $query_var, mixed $value )

Set query variable. Since 1.5.0.

Arguments

Name Type(s) Default Value Description
$query_var string

Query variable key.

$value mixed

Query variable value.


WP_Query:: set_404( )

Sets the 404 property and saves whether query is feed. Since 2.0.0.


WP_Query:: set_found_posts( array $q, string $limits )

Set up the amount of found posts and the number of pages (if limit clause was used) for the current query. Since 3.5.0.

Arguments

Name Type(s) Default Value Description
$q array

Query variables.

$limits string

LIMIT clauses of the query.


WP_Query:: setup_postdata( WP_Post | object | integer $post )

Set up global post data. Since 4.1.0. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$post WP_Post | object | integer

WP_Post instance or Post ID/object.

Returns

true

True when finished.


WP_Query:: the_comment( )

Sets up the current comment. Since 2.2.0.


WP_Query:: the_post( )

Sets up the current post. Since 1.5.0.

Retrieves the next post, sets up the post, sets the 'in the loop' property to true.


WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.