Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

ko:Class Reference/WP Query

This page redirects to an external site: https://developer.wordpress.org/reference/classes/wp_query/

클래스 설명

WP_Querywp-includes/query.php 안에 정의된 클래스입니다. WP_Query 클래스는 포스트 또는 페이지가 워드프레스 블로그에 요청하는 복잡한 사항들을 처리합니다. The wp-blog-header.php (or the WP class in Version 2.0) gives the $wp_query object information defining the current request, and then $wp_query determines what type of query it's dealing with (possibly a category archive, dated archive, feed, or search), and fetches the requested posts. It retains a lot of information on the request, which can be pulled at a later date.

WP_Query와 상호작용하기

대부분의 경우에 클래스 내부와 전역 변수를 다루지 않고 당신이 원하는 정보를 찾을 수 있습니다. 어디서든지 당신이 원하는 정보를 얻게 해주는 함수들의 전체 묶음이 있습니다.

당신이 WP_Query를 사용하기를 원하는 경우가 대표적으로 두 가지 경우가 있습니다. 첫번째 경우에는 워드프레스가 현재 처리하고 있는 요청의 타입을 확인하는 것입니다. $is_* 속성은 이 정보를 담도록 디자인 되었습니다. 조건 태그를 사용하여 상호작용 할 수 있습니다.

The second is during The Loop. WP_Query provides numerous functions for common tasks within The Loop. To begin with, have_posts(), which calls $wp_query->have_posts(), is called to see if there are any posts to show. If there are, a while loop is begun, using have_posts() as the condition. This will iterate around as long as there are posts to show. In each iteration, the_post(), which calls $wp_query->the_post() is called, setting up internal variables within $wp_query and the global $post variable (which the Template Tags rely on), as above. These are the functions you should use when writing a theme file that needs a loop. See also The Loop and The Loop in Action for more information.

Note: If you use the_post() with your query, you need to run wp_reset_postdata() afterwards to have Template Tags use the main query's current post again.

사용방법

표준 루프(Loop)

<?php

// The Query
$the_query = new WP_Query( $args );

// The Loop
if ( $the_query->have_posts() ) {
	echo '<ul>';
	while ( $the_query->have_posts() ) {
		$the_query->the_post();
		echo '<li>' . get_the_title() . '</li>';
	}
	echo '</ul>';
} else {
	// no posts found
}
/* Restore original Post Data */
wp_reset_postdata();

표준 루프(Loop) (대안)

<?php 
// the query
$the_query = new WP_Query( $args ); ?>

<?php if ( $the_query->have_posts() ) : ?>

	<!-- pagination here -->

	<!-- the loop -->
	<?php while ( $the_query->have_posts() ) : $the_query->the_post(); ?>
		<h2><?php the_title(); ?></h2>
	<?php endwhile; ?>
	<!-- end of the loop -->

	<!-- pagination here -->

	<?php wp_reset_postdata(); ?>

<?php else : ?>
	<p><?php _e( 'Sorry, no posts matched your criteria.' ); ?></p>
<?php endif; ?>

중첩 루프

여러 쿼리가 있으면 다음과 같이 다중 루프문을 수행할 필요가 있을 것입니다.

<?php

// The Query
$query1 = new WP_Query( $args );

// The Loop
while ( $query1->have_posts() ) {
	$query1->the_post();
	echo '<li>' . get_the_title() . '</li>';
}

/* Restore original Post Data 
 * NB: Because we are using new WP_Query we aren't stomping on the 
 * original $wp_query and it does not need to be reset with 
 * wp_reset_query(). We just need to set the post data back up with
 * wp_reset_postdata().
 */
wp_reset_postdata();


/* The 2nd Query (without global var) */
$query2 = new WP_Query( $args2 );

// The 2nd Loop
while ( $query2->have_posts() ) {
	$query2->next_post();
	echo '<li>' . get_the_title( $query2->post->ID ) . '</li>';
}

// Restore original Post Data
wp_reset_postdata();

?>

메소드와 멤버변수

This is the formal documentation of WP_Query. You shouldn't alter the properties directly, but instead use the methods to interact with them. Also see Interacting with WP_Query for some useful functions that avoid the need to mess around with class internals and global variables.

멤버변수

$query
WP 클래스에 의해 $wp_query 객체로 넘겨진 쿼리문을 담고 있습니다.
$query_vars
An associative array containing the dissected $query: an array of the query variables and their respective values.
$queried_object
Applicable if the request is a category, author, permalink or Page. Holds information on the requested category, author, post or Page.
$queried_object_id
If the request is a category, author, permalink or post / page, holds the corresponding ID.
$posts
Gets filled with the requested posts from the database.
$post_count
The number of posts being displayed.
$found_posts
현재 쿼리 파라미터에 매치되어 찾은 포스트의 전체 개수
$max_num_pages
The total number of pages. Is the result of $found_posts / $posts_per_page
$current_post
(루프 안에서 사용가능) Index of the post currently being displayed.
$post
(루프 안에서 사용가능) The post currently being displayed.
$is_single, $is_page, $is_archive, $is_preview, $is_date, $is_year, $is_month, $is_time, $is_author, $is_category, $is_tag, $is_tax, $is_search, $is_feed, $is_comment_feed, $is_trackback, $is_home, $is_404, $is_comments_popup, $is_admin, $is_attachment, $is_singular, $is_robots, $is_posts_page, $is_paged
Booleans dictating what type of request this is. For example, the first three represent 'is it a permalink?', 'is it a Page?', 'is it any type of archive page?', respectively. See also Conditional_Tags.

메소드

(An ampersand (&) before a method name indicates it returns by reference.)

init()
객체를 초기화 합니다. 모든 멤버변수를 null, 제로(0) 또는 false 상태로 만듭니다.
parse_query( $query )
Takes a query string defining the request, parses it and populates all properties apart from $posts, $post_count, $post and $current_post.
parse_query_vars()
Reparse the old query string.
get( $query_var )
Get a named query variable.
set( $query_var, $value )
Set a named query variable to a specific value.
&get_posts()
Fetch and return the requested posts from the database. Also populate $posts and $post_count.
next_post()
(루프 안에서 사용됩니다) Advance onto the next post in $posts. Increment $current_post and set $post to the (new) current post object (note: this does not set the global $post variable, only the WP_Query object's instance variable.) Returns the current post object
the_post()
(루프 안에서 사용됩니다) Advance onto the next post, and set the global $post variable.
have_posts()
(to be used when in The Loop, or just before The Loop) Determine if we have posts remaining to be displayed. Calls rewind_posts() and returns false if don't have posts remaining. Because of the rewind, you can't rely on have_posts() staying false. See have_posts() note.
rewind_posts()
Reset $current_post and $post.
&query( $query )
Call parse_query() and get_posts(). Return the results of get_posts().
get_queried_object()
Set $queried_object if it's not already set and return it.
get_queried_object_id()
Set $queried_object_id if it's not already set and return it.
WP_Query( $query = '' ) (constructor)
If you provide a query string, call query() with it.

파라메터

저자(Author) 파라메터

특정 저자(글쓴이)와 관련된 포스트를 보여줍니다.

  • author (int) - 저자 ID를 사용합니다.
  • author_name (string) - 'user_nicename'을 사용합니다. (name 이 아닙니다).
  • author__in (array) - 저자 ID를 사용합니다. (Version 3.7이상에서 사용가능).
  • author__not_in (array) - 저자 ID를 사용합니다. (Version 3.7이상에서 사용가능).

특정 저자가 작성한 포스트 보여주기

저자 ID 를 사용하여 특정 저자가 작성한 포스트를 표시합니다 :

$query = new WP_Query( 'author=123' );

'user_nicename'을 사용하여 특정 저자가 작성한 포스트를 표시합니다 :

$query = new WP_Query( 'author_name=rami' );

다수의 저자가 작성한 포스트 보여주기

몇몇 특정 저자들이 작성한 포스트를 표시합니다 :

$query = new WP_Query( 'author=2,6,17,38' );

특정 저자가 쓴 포스트를 제외시켜서 표시하기

Display all posts except those from an author(singular) by prefixing its id with a '-' (minus) sign:

$query = new WP_Query( 'author=-12' );

다수의 저자 다루기

다수의 저자 ID를 배열로 넘겨, 그 저자들이 작성한 포스트를 표시합니다 :

$query = new WP_Query( array( 'author__in' => array( 2, 6 ) ) );

또한 다음과 같이 다수의 저자를 제외시킬 수도 있습니다 :

$query = new WP_Query( array( 'author__not_in' => array( 2, 6 ) ) );

카테고리 파라메터

특정 카테고리와 관련된 포스트들을 보여줍니다.

  • cat (int) - 카테고리 ID를 사용합니다.
  • category_name (string) - 카테고리 슬러그(slug)를 사용합니다. (이름이 아닙니다)
  • category__and (array) - 카테고리 ID를 사용합니다.
  • category__in (array) - 카테고리 ID를 사용합니다.
  • category__not_in (array) - 카테고리 ID를 사용합니다.

특정 카테고리의 글 표시하기

해당 카테고리가 가지고 있는 포스트를 표시합니다 (해당 카테고리의 자손 카테고리에 포함된 글도 포함). 카테고리 ID를 사용 :

$query = new WP_Query( 'cat=4' );

해당 카테고리가 가지고 있는 포스트를 표시합니다 (해당 카테고리의 자손 카테고리에 포함된 글도 포함). 카테고리 슬러그(Slug)를 사용 :

$query = new WP_Query( 'category_name=staff' );

해당 카테고리가 가지고 있는 포스트를 표시합니다 (해당 카테고리의 자손 카테고리에 포함된 글은 제외). 카테고리 ID를 사용 :

$query = new WP_Query( 'category__in=4' );

몇개의 카테고리에 속한 포스트 표시하기

여러 개의 카테고리를 지정하여 해당 카테고리에 속한 포스트를 모두 표시합니다. 카테고리 ID 사용 :

$query = new WP_Query( 'cat=2,6,17,38' );

여러 개의 카테고리를 지정하여 해당 카테고리에 속한 포스트를 모두 표시합니다. 카테고리 슬러그(Slug) 사용 :

$query = new WP_Query( 'category_name=staff,news' );

Display posts that have "all" of these categories:

$query = new WP_Query( 'category_name=staff+news' );

Exclude Posts Belonging to Category

Display all posts except those from a category by prefixing its id with a '-' (minus) sign.

$query = new WP_Query( 'cat=-12,-34,-56' );

Multiple Category Handling

Display posts that are in multiple categories. This shows posts that are in both categories 2 and 6:

$query = new WP_Query( array( 'category__and' => array( 2, 6 ) ) );

To display posts from either category 2 OR 6, you could use cat as mentioned above, or by using category__in (note this does not show posts from any children of these categories):

$query = new WP_Query( array( 'category__in' => array( 2, 6 ) ) );

You can also exclude multiple categories this way:

$query = new WP_Query( array( 'category__not_in' => array( 2, 6 ) ) );

태그 파라메터

특정 태그와 관련된 포스트를 보여줍니다.

  • tag (string) - use tag slug.
  • tag_id (int) - use tag id.
  • tag__and (array) - use tag ids.
  • tag__in (array) - use tag ids.
  • tag__not_in (array) - use tag ids.
  • tag_slug__and (array) - use tag slugs.
  • tag_slug__in (array) - use tag slugs.

Show Posts for One Tag

Display posts that have this tag, using tag slug:

$query = new WP_Query( 'tag=cooking' );

Display posts that have this tag, using tag id:

$query = new WP_Query( 'tag_id=13' );

Show Posts From Several Tags

Display posts that have "either" of these tags:

$query = new WP_Query( 'tag=bread,baking' );

Display posts that have "all" of these tags:

$query = new WP_Query( 'tag=bread+baking+recipe' );

Multiple Tag Handling

Display posts that are tagged with both tag id 37 and tag id 47:

$query = new WP_Query( array( 'tag__and' => array( 37, 47 ) ) );

To display posts from either tag id 37 or 47, you could use tag as mentioned above, or explicitly specify by using tag__in:

$query = new WP_Query( array( 'tag__in' => array( 37, 47 ) ) );

Display posts that do not have any of the two tag ids 37 and 47:

$query = new WP_Query( array( 'tag__not_in' => array( 37, 47 ) ) );

The tag_slug__in and tag_slug__and behave much the same, except match against the tag's slug.

택소노미(분류, Taxonomy) 파라메터

특정 택소노미(Taxonomy)와 관련된 포스트를 보여줍니다.

  • {tax} (string) - use taxonomy slug. Deprecated as of Version 3.1 in favor of 'tax_query'.
  • tax_query (array) - use taxonomy parameters (available with Version 3.1).
    • relation (string) - The logical relationship between each inner taxonomy array when there is more than one. Possible values are 'AND', 'OR'. Do not use with a single inner taxonomy array.
      • taxonomy (string) - Taxonomy.
      • field (string) - Select taxonomy term by ('term_id'(default), 'name' or 'slug')
      • terms (int/string/array) - Taxonomy term(s).
      • include_children (boolean) - Whether or not to include children for hierarchical taxonomies. Defaults to true.
      • operator (string) - Operator to test. Possible values are 'IN'(default), 'NOT IN', 'AND'.

Important Note: tax_query takes an array of tax query arguments arrays (it takes an array of arrays) - you can see this in the second example below. This construct allows you to query multiple taxonomies by using the relation parameter in the first (outer) array to describe the boolean relationship between the taxonomy arrays. See the second and third multiple taxonomy handling examples below.

As of 3.5, a bug was fixed where tax_query would inadvertently return all posts when a result was empty.

Simple Taxonomy Query:

Display posts tagged with bob, under people custom taxonomy:

$args = array(
	'post_type' => 'post',
	'people'    => 'bob',
);
$query = new WP_Query( $args );

Display posts tagged with bob, under people custom taxonomy, using tax_query:

$args = array(
	'post_type' => 'post',
	'tax_query' => array(
		array(
			'taxonomy' => 'people',
			'field'    => 'slug',
			'terms'    => 'bob',
		),
	),
);
$query = new WP_Query( $args );

Multiple Taxonomy Handling:

Display posts from several custom taxonomies:

$args = array(
	'post_type' => 'post',
	'people'    => 'bob',
	'language'  => 'english',
);
$query = new WP_Query( $args );

Display posts from several custom taxonomies, using tax_query:

$args = array(
	'post_type' => 'post',
	'tax_query' => array(
		'relation' => 'AND',
		array(
			'taxonomy' => 'movie_genre',
			'field'    => 'slug',
			'terms'    => array( 'action', 'comedy' ),
		),
		array(
			'taxonomy' => 'actor',
			'field'    => 'id',
			'terms'    => array( 103, 115, 206 ),
			'operator' => 'NOT IN',
		),
	),
);
$query = new WP_Query( $args );

Display posts that are in the quotes category OR have the quote format:

$args = array(
	'post_type' => 'post',
	'tax_query' => array(
		'relation' => 'OR',
		array(
			'taxonomy' => 'category',
			'field'    => 'slug',
			'terms'    => array( 'quotes' ),
		),
		array(
			'taxonomy' => 'post_format',
			'field'    => 'slug',
			'terms'    => array( 'post-format-quote' ),
		),
	),
);
$query = new WP_Query( $args );

Search Parameter

Show posts based on a keyword search.

  • s (string) - Search keyword.

Show Posts based on a keyword search

Display posts that match the search term "keyword":

$query = new WP_Query( 's=keyword' );

포스트 & 페이지 파라메터

Display content based on post and page parameters. Remember that default post_type is only set to display posts but not pages.

Show Post/Page by ID

Display post by ID:

$query = new WP_Query( 'p=7' );

Display page by ID:

$query = new WP_Query( 'page_id=7' );

Show Post/Page by Slug

Display post by slug:

$query = new WP_Query( 'name=about-my-life' );

Display page by slug:

$query = new WP_Query( 'pagename=contact' );

Show Child Posts/Pages

Display child page using the slug of the parent and the child page, separated by a slash (e.g. 'parent_slug/child_slug'):

$query = new WP_Query( 'pagename=contact_us/canada' );

Display child pages using parent page ID:

$query = new WP_Query( 'post_parent=93' );

Display only top-level pages, exclude all child pages:

$query = new WP_Query( 'post_parent=0' );

Display posts whose parent is in an array:

$query = new WP_Query( array( 'post_parent__in' => array( 2, 5, 12, 14, 20 ) ) );

Multiple Posts/Pages Handling

Display only the specific posts:

$query = new WP_Query( array( 'post_type' => 'page', 'post__in' => array( 2, 5, 12, 14, 20 ) ) );

Display all posts but NOT the specified ones:

$query = new WP_Query( array( 'post_type' => 'post', 'post__not_in' => array( 2, 5, 12, 14, 20 ) ) );

Note: you cannot combine post__in and post__not_in in the same query.

Also note that using a string containing a comma separated list will not work here. If you're passing a variable, make sure it's a proper array of integer values:

// This will NOT work
$exclude_ids = '1,2,3';
$query = new WP_Query( array( 'post__not_in' => array( $exclude_ids ) ) );

// This WILL work
$exclude_ids = array( 1, 2, 3 );
$query = new WP_Query( array( 'post__not_in' => $exclude_ids ) );

Password Parameters

Show content based on post and page parameters. Remember that default post_type is only set to display posts but not pages.

  • has_password (bool) - true for posts with passwords ; false for posts without passwords ; null for all posts with and without passwords (available with Version 3.9).
  • post_password (string) - show posts with a particular password (available with Version 3.9)

Show Posts with/without passwords

Display only password protected posts:

$query = new WP_Query( array( 'has_password' => true ) );

Display only posts without passwords:

$query = new WP_Query( array( 'has_password' => false ) );

Display only posts with and without passwords:

$query = new WP_Query( array( 'has_password' => null ) );

Show Posts with particular password

Display posts with 'zxcvbn' password:

$query = new WP_Query( array( 'post_password' => 'zxcvbn' ) );

Type Parameters

Show posts associated with certain type.

  • post_type (string / array) - use post types. Retrieves posts by Post Types, default value is 'post'. If 'tax_query' is set for a query, the default value becomes 'any';
    • 'post' - a post.
    • 'page' - a page.
    • 'revision' - a revision.
    • 'attachment' - an attachment. The default WP_Query sets 'post_status'=>'publish', but attachments default to 'post_status'=>'inherit' so you'll need to explicitly set post_status to 'inherit' or 'any' as well. (See post_status, below)
    • 'nav_menu_item' - a navigation menu item
    • 'any' - retrieves any type except revisions and types with 'exclude_from_search' set to true.
    • Custom Post Types (e.g. movies)

Show Post by Type

Display only pages:

$query = new WP_Query( 'post_type=page' );

Display 'any' post type (retrieves any type except revisions and types with 'exclude_from_search' set to TRUE):

$query = new WP_Query( 'post_type=any' );

Display multiple post types, including custom post types:

$query = new WP_Query( array(
	'post_type' => array( 'post', 'page', 'movie', 'book' )
) );

Status Parameters

Show posts associated with certain status.

  • post_status (string / array) - use post status. Retrieves posts by Post Status. Default value is 'publish', but if the user is logged in, 'private' is added. And if the query is run in an admin context (administration area or AJAX call), protected statuses are added too. By default protected statuses are 'future', 'draft' and 'pending'.
    • 'publish' - a published post or page.
    • 'pending' - post is pending review.
    • 'draft' - a post in draft status.
    • 'auto-draft' - a newly created post, with no content.
    • 'future' - a post to publish in the future.
    • 'private' - not visible to users who are not logged in.
    • 'inherit' - a revision. see get_children.
    • 'trash' - post is in trashbin (available with Version 2.9).
    • 'any' - retrieves any status except those from post statuses with 'exclude_from_search' set to true (i.e. trash and auto-draft).

Show Post by Status

Display only drafts:

$query = new WP_Query( 'post_status=draft' );

Display multiple post status:

$query = new WP_Query( array( 'post_status' => array( 'pending', 'draft', 'future' ) ) );

Display all attachments:

$query = new WP_Query( array( 'post_status' => 'any', 'post_type' => 'attachment' ) );

Pagination Parameters

  • nopaging (boolean) - show all posts or use pagination. Default value is 'false', use paging.
  • posts_per_page (int) - number of post to show per page (available with Version 2.1, replaced showposts parameter). Use 'posts_per_page'=>-1 to show all posts (the 'offset' parameter is ignored with a -1 value). Set the 'paged' parameter if pagination is off after using this parameter. Note: if the query is in a feed, wordpress overwrites this parameter with the stored 'posts_per_rss' option. To reimpose the limit, try using the 'post_limits' filter, or filter 'pre_option_posts_per_rss' and return -1
  • posts_per_archive_page (int) - number of posts to show per page - on archive pages only. Over-rides posts_per_page and showposts on pages where is_archive() or is_search() would be true.
  • offset (int) - number of post to displace or pass over. Warning: Setting the offset parameter overrides/ignores the paged parameter and breaks pagination (Click here for a workaround). The 'offset' parameter is ignored when 'posts_per_page'=>-1 (show all posts) is used.
  • paged (int) - number of page. Show the posts that would normally show up just on page X when using the "Older Entries" link.
  • page (int) - number of page for a static front page. Show the posts that would normally show up just on page X of a Static Front Page.
  • ignore_sticky_posts (boolean) - ignore post stickiness (available with Version 3.1, replaced caller_get_posts parameter). false (default): move sticky posts to the start of the set. true: do not move sticky posts to the start of the set.


Show x Posts per page

Display 3 posts per page:

$query = new WP_Query( 'posts_per_page=3' );

Show All Post

Display all posts in one page:

$query = new WP_Query( 'posts_per_page=-1' );

Display all posts by disabling pagination:

$query = new WP_Query( 'nopaging=true' );

Pass over Posts

Display posts from the 4th one:

$query = new WP_Query( 'offset=3' ) );

Display 5 posts per page which follow the 3 most recent posts:

$query = new WP_Query( array( 'posts_per_page' => 5, 'offset' => 3 ) );

Show Posts from page x

Display posts from page number 6:

$query = new WP_Query( 'paged=6' );

Show Posts from Current Page

Display posts from current page:

$query = new WP_Query( array( 'paged' => get_query_var( 'paged' ) ) );

Display posts from the current page and set the 'paged' parameter to 1 when the query variable is not set (first page).

$paged = ( get_query_var('paged') ) ? get_query_var('paged') : 1;
$query = new WP_Query( array( 'paged' => $paged ) );

Pagination Note: Use get_query_var('page'); if you want your query to work in a Page template that you've set as your static front page. The query variable 'page' also holds the pagenumber for a single paginated Post or Page that includes the <!--nextpage--> Quicktag in the post content.

Display posts from current page on a static front page:

$paged = ( get_query_var('page') ) ? get_query_var('page') : 1;
$query = new WP_Query( array( 'paged' => $paged ) );

Show Sticky Posts

Display just the first sticky post:

$sticky = get_option( 'sticky_posts' );
$query = new WP_Query( 'p=' . $sticky[0] );

Display just the first sticky post, if none return the last post published:

$args = array(
	'posts_per_page'      => 1,
	'post__in'            => get_option( 'sticky_posts' ),
	'ignore_sticky_posts' => 1,
);
$query = new WP_Query( $args );

Display just the first sticky post, if none return nothing:

$sticky = get_option( 'sticky_posts' );
$args = array(
	'posts_per_page'      => 1,
	'post__in'            => $sticky,
	'ignore_sticky_posts' => 1,
);
$query = new WP_Query( $args );
if ( $sticky[0] ) {
	// insert here your stuff...
}

Don't Show Sticky Posts

Exclude all sticky posts from the query:

$query = new WP_Query( array( 'post__not_in' => get_option( 'sticky_posts' ) ) );

Exclude sticky posts from a category. Return ALL posts within the category, but don't show sticky posts at the top. The 'sticky posts' will still show in their natural position (e.g. by date):

$query = new WP_Query( array( 'ignore_sticky_posts' => 1, 'posts_per_page' => 3, 'cat' => 6 );

Exclude sticky posts from a category. Return posts within the category, but exclude sticky posts completely, and adhere to paging rules:

$paged = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;
$sticky = get_option( 'sticky_posts' );
$args = array(
	'cat'                 => 3,
	'ignore_sticky_posts' => 1,
	'post__not_in'        => $sticky,
	'paged'               => $paged,
);
$query = new WP_Query( $args );

Order & Orderby Parameters

Sort retrieved posts.

  • order (string | array) - Designates the ascending or descending order of the 'orderby' parameter. Defaults to 'DESC'. An array can be used for multiple order/orderby sets.
    • 'ASC' - ascending order from lowest to highest values (1, 2, 3; a, b, c).
    • 'DESC' - descending order from highest to lowest values (3, 2, 1; c, b, a).
  • orderby (string | array) - Sort retrieved posts by parameter. Defaults to 'date (post_date)'. One or more options can be passed.
    • 'none' - No order (available with Version 2.8).
    • 'ID' - Order by post id. Note the capitalization.
    • 'author' - Order by author.
    • 'title' - Order by title.
    • 'name' - Order by post name (post slug).
    • 'type' - Order by post type (available since Version 4.0).
    • 'date' - Order by date.
    • 'modified' - Order by last modified date.
    • 'parent' - Order by post/page parent id.
    • 'rand' - Random order.
    • 'comment_count' - Order by number of comments (available with Version 2.9).
    • 'menu_order' - Order by Page Order. Used most often for Pages (Order field in the Edit Page Attributes box) and for Attachments (the integer fields in the Insert / Upload Media Gallery dialog), but could be used for any post type with distinct 'menu_order' values (they all default to 0).
    • 'meta_value' - Note that a 'meta_key=keyname' must also be present in the query. Note also that the sorting will be alphabetical which is fine for strings (i.e. words), but can be unexpected for numbers (e.g. 1, 3, 34, 4, 56, 6, etc, rather than 1, 3, 4, 6, 34, 56 as you might naturally expect). Use 'meta_value_num' instead for numeric values. You may also specify 'meta_type' if you want to cast the meta value as a specific type. Possible values are 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED', same as in '$meta_query'.
    • 'meta_value_num' - Order by numeric meta value (available with Version 2.8). Also note that a 'meta_key=keyname' must also be present in the query. This value allows for numerical sorting as noted above in 'meta_value'.
    • 'post__in' - Preserve post ID order given in the post__in array (available with Version 3.5).

Show Posts sorted by Title, Descending order

Display posts sorted by post title in a descending order:

$query = new WP_Query( array ( 'orderby' => 'title', 'order' => 'DESC' ) );

Display posts sorted by menu_order with a fallback to post title, in a descending order:

$query = new WP_Query( array ( 'orderby' => 'menu_order title', 'order' => 'DESC' ) );

Show Random Post

Display one random post:

$query = new WP_Query( array ( 'orderby' => 'rand', 'posts_per_page' => '1' ) );

Show Popular Posts

Display posts ordered by comment count:

$query = new WP_Query( array( 'orderby' => 'comment_count' ) );

Show Products sorted by Price

Display posts with 'Product' type ordered by 'Price' custom field:

$query = new WP_Query( array ( 'post_type' => 'product', 'orderby' => 'meta_value_num', 'meta_key' => 'price' ) );

Multiple 'orderby' values

Display pages ordered by 'title' and 'menu_order'. (title is dominant):

$query = new WP_Query( array( 'post_type' => 'page', 'orderby' => 'title menu_order', 'order' => 'ASC' ) );

Multiple 'orderby' values using an array

Display pages ordered by 'title' and 'menu_order' with different sort orders (ASC/DESC):

$query = new WP_Query( array( 'orderby' => array( 'title' => 'DESC', 'menu_order' => 'ASC' ) ) );

Mulitiple orderby/order pairs

'orderby' => array( 'meta_value_num' => 'DESC', 'title' => 'ASC' ), 'meta_key' => 'age'

'orderby' with 'meta_value' and custom post type

Display posts of type 'my_custom_post_type', ordered by 'age', and filtered to show only ages 3 and 4 (using meta_query).

$args = array(
	'post_type'  => 'my_custom_post_type',
	'meta_key'   => 'age',
	'orderby'    => 'meta_value_num',
	'order'      => 'ASC',
	'meta_query' => array(
		array(
			'key'     => 'age',
			'value'   => array( 3, 4 ),
			'compare' => 'IN',
		),
	),
);
$query = new WP_Query( $args );

Date Parameters

Show posts associated with a certain time and date period.

  • year (int) - 4 digit year (e.g. 2011).
  • monthnum (int) - Month number (from 1 to 12).
  • w (int) - Week of the year (from 0 to 53). Uses MySQL WEEK command. The mode is dependent on the "start_of_week" option.
  • day (int) - Day of the month (from 1 to 31).
  • hour (int) - Hour (from 0 to 23).
  • minute (int) - Minute (from 0 to 60).
  • second (int) - Second (0 to 60).
  • m (int) - YearMonth (For e.g.: 201307).
  • date_query (array) - Date parameters (available with Version 3.7).
    • year (int) - 4 digit year (e.g. 2011).
    • month (int) - Month number (from 1 to 12).
    • week (int) - Week of the year (from 0 to 53).
    • day (int) - Day of the month (from 1 to 31).
    • hour (int) - Hour (from 0 to 23).
    • minute (int) - Minute (from 0 to 59).
    • second (int) - Second (0 to 59).
    • after (string/array) - Date to retrieve posts after. Accepts strtotime()-compatible string, or array of 'year', 'month', 'day' values:
      • year (string) Accepts any four-digit year. Default is empty.
      • month (string) The month of the year. Accepts numbers 1-12. Default: 12.
      • day (string) The day of the month. Accepts numbers 1-31. Default: last day of month.
    • before (string/array) - Date to retrieve posts before. Accepts strtotime()-compatible string, or array of 'year', 'month', 'day' values:
      • year (string) Accepts any four-digit year. Default is empty.
      • month (string) The month of the year. Accepts numbers 1-12. Default: 1.
      • day (string) The day of the month. Accepts numbers 1-31. Default: 1.
    • inclusive (boolean) - For after/before, whether exact value should be matched or not'.
    • compare (string) - See WP_Date_Query::get_compare().
    • column (string) - Column to query against. Default: 'post_date'.
    • relation (string) - OR or AND, how the sub-arrays should be compared. Default: AND.

Returns posts dated December 12, 2012:

$query = new WP_Query( 'year=2012&monthnum=12&day=12' );

or:

$args = array(
	'date_query' => array(
		array(
			'year'  => 2012,
			'month' => 12,
			'day'   => 12,
		),
	),
);
$query = new WP_Query( $args );

Returns posts for today:

$today = getdate();
$query = new WP_Query( 'year=' . $today['year'] . '&monthnum=' . $today['mon'] . '&day=' . $today['mday'] );

or:

$today = getdate();
$args = array(
	'date_query' => array(
		array(
			'year'  => $today['year'],
			'month' => $today['mon'],
			'day'   => $today['mday'],
		),
	),
);
$query = new WP_Query( $args );

Returns posts for this week:

$week = date( 'W' );
$year = date( 'Y' );
$query = new WP_Query( 'year=' . $year . '&w=' . $week );

or:

$args = array(
	'date_query' => array(
		array(
			'year' => date( 'Y' ),
			'week' => date( 'W' ),
		),
	),
);
$query = new WP_Query( $args );

Return posts between 9AM to 5PM on weekdays

$args = array(
	'date_query' => array(
		array(
			'hour'      => 9,
			'compare'   => '>=',
		),
		array(
			'hour'      => 17,
			'compare'   => '<=',
		),
		array(
			'dayofweek' => array( 2, 6 ),
			'compare'   => 'BETWEEN',
		),
	),
	'posts_per_page' => -1,
);
$query = new WP_Query( $args );

Return posts from January 1st to February 28th

$args = array(
	'date_query' => array(
		array(
			'after'     => 'January 1st, 2013',
			'before'    => array(
				'year'  => 2013,
				'month' => 2,
				'day'   => 28,
			),
			'inclusive' => true,
		),
	),
	'posts_per_page' => -1,
);
$query = new WP_Query( $args );

Note that if a strtotime()-compatible string with just a date was passed in the before parameter, this will be converted to 00:00:00 on that date. In this case, even if inclusive was set to true, the date would not be included in the query. If you want a before date to be inclusive, include the time as well, such as 'before' => '2013-02-28 23:59:59', or use the array format, which is adjusted automatically if inclusive is set.

Return posts made over a year ago but modified in the past month

$args = array(
	'date_query' => array(
		array(
			'column' => 'post_date_gmt',
			'before' => '1 year ago',
		),
		array(
			'column' => 'post_modified_gmt',
			'after'  => '1 month ago',
		),
	),
	'posts_per_page' => -1,
);
$query = new WP_Query( $args );

Custom Field Parameters

Show posts associated with a certain custom field.

This part of the query is parsed by WP_Meta_Query, so check the docs for it as well in case this list of arguments isn't up to date.

  • meta_key (string) - Custom field key.
  • meta_value (string) - Custom field value.
  • meta_value_num (number) - Custom field value.
  • meta_compare (string) - Operator to test the 'meta_value'. Possible values are '!=', '>', '>=', '<', or '<='. Default value is '='.
  • meta_query (array) - Custom field parameters (available with Version 3.1).
    • relation (string) - The logical relationship between each inner meta_query array when there is more than one. Possible values are 'AND', 'OR'. Do not use with a single inner meta_query array.

meta_query also contains one or more arrays with the following keys:

  • key (string) - Custom field key.
  • value (string|array) - Custom field value. It can be an array only when compare is 'IN', 'NOT IN', 'BETWEEN', or 'NOT BETWEEN'. You don't have to specify a value when using the 'EXISTS' or 'NOT EXISTS' comparisons in WordPress 3.9 and up.
    (Note: Due to bug #23268, value is required for NOT EXISTS comparisons to work correctly prior to 3.9. You must supply some string for the value parameter. An empty string or NULL will NOT work. However, any other string will do the trick and will NOT show up in your SQL when using NOT EXISTS. Need inspiration? How about 'bug #23268'.)
  • compare (string) - Operator to test. Possible values are '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' (only in WP >= 3.5), and 'NOT EXISTS' (also only in WP >= 3.5). Default value is '='.
  • type (string) - Custom field type. Possible values are 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'. Default value is 'CHAR'.

The 'type' DATE works with the 'compare' value BETWEEN only if the date is stored at the format YYYYMMDD and tested with this format.

Important Note: meta_query takes an array of meta query arguments arrays (it takes an array of arrays) - you can see this in the examples below. This construct allows you to query multiple metadatas by using the relation parameter in the first (outer) array to describe the boolean relationship between the meta queries. Accepted arguments are 'AND', 'OR'. The default is 'AND'.

Simple Custom Field Query:

Display posts where the custom field key is 'color', regardless of the custom field value:

$query = new WP_Query( 'meta_key=color' );

Display posts where the custom field value is 'blue', regardless of the custom field key:

$query = new WP_Query( 'meta_value=blue' );

Display Page where the custom field value is 'blue', regardless of the custom field key:

$query = new WP_Query( 'meta_value=blue&post_type=page' );

Display posts where the custom field key is 'color' and the custom field value is 'blue':

$query = new WP_Query( array( 'meta_key' => 'color', 'meta_value' => 'blue' ) );

Display posts where the custom field key is 'color' and the custom field value IS NOT 'blue':

$query = new WP_Query( array( 'meta_key' => 'color', 'meta_value' => 'blue', 'meta_compare' => '!=' ) );

Display 'product'(s) where the custom field key is 'price' and the custom field value that is LESS THAN OR EQUAL TO 22.
By using the 'meta_value' parameter the value 99 will be considered greater than 100 as the data are stored as 'strings', not 'numbers'. For number comparison use 'meta_value_num'.

$query = new WP_Query( array( 'meta_key' => 'price', 'meta_value' => '22', 'meta_compare' => '<=', 'post_type' => 'product' ) );

Display posts with a custom field value of zero (0), regardless of the custom field key:

$query = new WP_Query( array( 'meta_value' => '_wp_zero_value' ) );

Single Custom Field Handling:

Display posts from a single custom field:

$args = array(
	'post_type'  => 'product',
	'meta_query' => array(
		array(
			'key'     => 'color',
			'value'   => 'blue',
			'compare' => 'NOT LIKE',
		),
	),
);
$query = new WP_Query( $args );

(Note that meta_query expects nested arrays, even if you only have one query.)

Multiple Custom Field Handling:

Display posts from several custom field:

$args = array(
	'post_type'  => 'product',
	'meta_query' => array(
		array(
			'key'     => 'color',
			'value'   => 'blue',
			'compare' => 'NOT LIKE',
		),
		array(
			'key' => 'price',
			'value'   => array( 20, 100 ),
			'type'    => 'numeric',
			'compare' => 'BETWEEN',
		),
	),
);
$query = new WP_Query( $args );

Display posts that have meta key 'color' NOT LIKE value 'blue' OR meta key 'price' with values BETWEEN 20 and 100:

$args = array(
	'post_type'  => 'product',
	'meta_query' => array(
		'relation' => 'OR',
		array(
			'key'     => 'color',
			'value'   => 'blue',
			'compare' => 'NOT LIKE',
		),
		array(
			'key'     => 'price',
			'value'   => array( 20, 100 ),
			'type'    => 'numeric',
			'compare' => 'BETWEEN',
		),
	),
);
$query = new WP_Query( $args );

Permission Parameters

  • perm (string) - User permission.

Show posts if user has the appropriate capability:

Display published and private posts, if the user has the appropriate capability:

$query = new WP_Query( array( 'post_status' => array( 'publish', 'private' ), 'perm' => 'readable' ) );

Caching Parameters

Stop the data retrieved from being added to the cache.

  • cache_results (boolean) - Post information cache.
  • update_post_meta_cache (boolean) - Post meta information cache.
  • update_post_term_cache (boolean) - Post term information cache.

Show Posts without adding post information to the cache

Display 50 posts, but don't add post information to the cache:

$query = new WP_Query( array( 'posts_per_page' => 50, 'cache_results' => false ) );

Show Posts without adding post meta information to the cache

Display 50 posts, but don't add post meta information to the cache:

$query = new WP_Query( array( 'posts_per_page' => 50, 'update_post_meta_cache' => false ) );

Show Posts without adding post term information to the cache

Display 50 posts, but don't add post term information to the cache:

$query = new WP_Query( array( 'posts_per_page' => 50, 'update_post_term_cache' => false ) );

In general usage you should not need to use these, adding to the cache is the right thing to do, however they may be useful in specific circumstances. An example of such circumstances might be when using a WP_Query to retrieve a list of post titles and URLs to be displayed, but in which no other information about the post will be used and the taxonomy and meta data won't be needed. By not loading this information, you can save time from the extra unnecessary SQL queries.

Note: If a persistent object cache backend (such as memcached) is used, these flags are set to false by default since there is no need to update the cache every page load when a persistent cache exists.

Return Fields Parameter

Set return values.

  • fields (string) - Which fields to return. All fields are returned by default. There are two other options:
    • 'ids' - Return an array of post IDs.
    • 'id=>parent' - Return an associative array [ parent => ID, … ].
    • Passing anything else will return all fields (default) - an array of post objects.

Filters

  • posts_distinct - Alters SQL 'DISTINCTROW' clause to the query that returns the post array.
  • posts_groupby - Alters SQL 'GROUP BY' clause of the query that returns the post array.
  • posts_join - Alters SQL 'JOIN' clause of the query that returns the post array.
  • post_limits - Alters SQL 'LIMIT' clause of the query that returns the post array.
  • posts_orderby - Alters SQL 'ORDER BY' clause of the query that returns the post array.
  • posts_where - Alters SQL 'WHERE' clause of the query that returns the post array.
  • posts_join_paged - Alters SQL paging for posts using 'JOIN' clause of the query that returns the post array.
  • posts_where_paged - Alters SQL paging for posts using 'WHERE' clause of the query that returns the post array.
  • posts_clauses - Alters all the SQL clauses above in one go. It gives you an array of elements that are easy to alter (available with Version 3.1).

Note, that there are more filters than the mentioned. As it is hard to keep the codex up to date, please inspect the get_posts(); function inside the WP_Query class yourself (/wp-includes/query.php).

Source File

WP_Query() is located in wp-includes/query.php.

External Resources

Related

Articles

Code Documentation

See also index of Class Reference and index of Function Reference.
This article is marked as in need of editing. You can help Codex by editing it.