関数リファレンス/WP Query

このページ「関数リファレンス/WP Query」は変更履歴節以降が未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています。

説明

WP_Query は wp-includes/class-wp-query.php に定義されているクラスで、WordPress ブログへの複雑な投稿やページのリクエストを取り扱います。 wp-blog-header.php (バージョン 2.0 では WP クラス) が $wp_query オブジェクトに現在のリクエストを定義する情報を与えることで、$wp_query はどのタイプのクエリを扱っているのか (カテゴリーアーカイブ、年月別アーカイブ、フィード、検索など) を確定し、要求された投稿を取り出します。$wp_query はリクエスト上の情報を多く保持していて、後からでも利用することができます。

WP_Query を使う場面

ほとんどの場合、クラスの内部やグローバル変数を使わなくても欲しい情報は手に入れられるでしょう。どこからでも欲しい情報を手に入れるために、とてもたくさんの関数があるのですから。

WP_Query を使いたくなるかもしれないケースが二つあります。一つは WordPress が今扱っているリクエストがどんなものかを知るためです。$is_* プロパティはこの情報を持つよう設計されています: これを利用するには条件分岐タグを使ってください。これはプラグイン作者によくあるケースです（二番目のケースはテーマ作者に）。

二つ目はループの中です。WP_Query はループ内においてよくある要望を実現するための数多くの関数を備えています。手始めに、$wp_query->have_posts() を呼び出す have_posts() は、表示すべき投稿があるかどうかを判断するために使います。while ループの開始時に have_posts() を条件として指定すれば、このループは表示すべき投稿がある限り反復されます。反復処理の中では毎回、$wp_query->the_post() を呼び出す the_post() を使います。これは $wp_query の内部変数とグローバル変数 $post（テンプレートタグはこれに依存します）を設定します。これは上で見た通りです。ループを必要とするテーマファイルを作る時に使うべき関数はたくさんあります。詳しくはループと The Loop in Action をご覧ください。

参考: 自分のクエリで the_post() を使うのなら、そのクエリの後に wp_reset_postdata() を実行する必要があります。これはテンプレートタグがメインクエリの現在の投稿を再び使えるようにするためです。

参考: Ticket #18408 管理画面内で投稿をクエリする場合、wp_reset_postdata() が期待どおり動かないかもしれないので get_posts() を利用するとよいでしょう。

使い方

ふつうのループ

<?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>';
	/* Restore original Post Data */
	wp_reset_postdata();
} else {
	// no posts found
}

ふつうのループ（別の書き方）

<?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 esc_html_e( 'Sorry, no posts matched your criteria.' ); ?></p>
<?php endif; ?>

複数のループ

クエリが複数あるなら、複数のループを実行する必要があります。このように…

<?php

// クエリ
$query1 = new WP_Query( $args );

if ( $query1->have_posts() ) {
	// ループ
	while ( $query1->have_posts() ) {
		$query1->the_post();
		echo '<li>' . get_the_title() . '</li>';
	}

	/* オリジナルの投稿データを復元
	 * 注意: WP_Query を使っているのでオリジナルの $wp_query を壊すことは
	 * なく、wp_reset_query() によってリセットする必要はありません。
	 * 投稿データを wp_reset_postdata() で復元することだけが必要です。
	 */
	wp_reset_postdata();
}

/* 2つ目のクエリ (グローバル変数を使わない) */
$query2 = new WP_Query( $args2 );

if ( $query2->have_posts() ) {
	// 2つ目のループ
	while ( $query2->have_posts() ) {
		$query2->the_post();
		echo '<li>' . get_the_title( $query2->post->ID ) . '</li>';
	}

	// 元の投稿データを復元
	wp_reset_postdata();
}

?>

メソッドとプロパティ

これはWP_Queryの公式な文書です。プロパティを直接書き換えるべきではありません。その代わりにメソッドを使って操作することができます。クラスのメンバとグローバル変数がめちゃくちゃになることを避ける便利な関数がありますので、WP_Queryに働きかけるを参考にしてください。

プロパティ

$query

$wp_query オブジェクトに WP クラスによって渡されたクエリストリングを含む。

$query_vars

解析された $query を保持する連想配列。クエリ変数と対応する値の配列。

$queried_object

リクエストがカテゴリー、作者ページ、パーマリンク、投稿または固定ページだった場合に適用される。リクエストされたクエリの情報を含む。

$queried_object_id

リクエストがカテゴリー、作者ページ、パーマリンク、投稿または固定ページだった場合、対応する ID を含む。

$posts

要求された投稿をデータベースから取得したもの。

$post_count

表示される投稿の数。

$found_posts

現在のクエリ変数に一致する投稿の合計数。

$max_num_pages

ページの合計数。$found_posts を $posts_per_page で割った結果。

$current_post

(ループ内でのみ使用可能) 表示されようとしている投稿の数。

$post

(ループ内でのみ使用可能) 現在表示されている投稿。

$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

リクエストがどのタイプなのかを判断するためのブーリアン値。最初の3つの例で言えば、「これはパーマリンクか？」「これは固定ページか？」「これは何らかのアーカイブページか？」となる。こちらもお読みください: 条件分岐タグ

メソッド

(メソッド名の前にあるアンパサンド「&」はそれが参照渡しであることを示します。)

init()

オブジェクトを初期化して、すべてのプロパティをnull、ゼロ、falseにセットする。

parse_query($query)

リクエストを定義するクエリ文字列を受け取り、それを解析して$posts、$post_count、$post、$current_post以外のすべてのプロパティを返す。

parse_query_vars()

古いクエリ文字列をもう一度解析する。

get($query_var)

指定されたクエリ変数を取得する。

set($query_var, $value)

指定されたクエリ変数を任意の値に設定する。

&get_posts()

要求された投稿をデータベースから取得して返す。さらに $posts と $post_count に値を入れる。参考: これは WP_Query を引数付きで生成するとき呼び出される。これに冪等性(idempotent)はないので、同じクエリオブジェクトについて2回以上呼び出してはいけない。もし行うとクエリが壊れる可能性がある。

next_post()

(ループ内でのみ使用可能) $posts で次の投稿に進む。$current_post を1つ増やし、$post を (新規の) 現在の投稿オブジェクトに設定する (注: グローバル $post 変数を設定はせず、WP_Query オブジェクトのインスタンス変数のみに適用される) 。現在の投稿オブジェクトを返す。(注意: これは非推奨です。next_post_link() を使ってください。)

the_post()

(ループ内でのみ使用可能)次の投稿に進み、グローバル変数$postを設定する。

have_posts()

(ループ内か、ループの前でのみ使用可能) 表示する投稿が残っているかを示す。残りの投稿がなければ内部で rewind_posts() を呼び出してから false を返す。rewind_posts() の影響により、have_posts() が連続して false を返すとは限りません。have_posts() の参考セクションをご覧ください。

rewind_posts()

$current_postと$postをリセットする。

&query($query)

parse_query()とget_posts()を呼び出し、get_posts()の結果を返す。

get_queried_object()

$queried_objectを設定し、それがまだ設定されていなければ、返す。

get_queried_object_id()

$queried_object_idを設定し、それがまだ設定されていなければ返す。

WP_Query($query = '') (コンストラクタ)

クエリ文字列を与えれば、それを使ってquery()を呼び出す。

パラメータ

投稿者パラメータ

ある投稿者に関連付けられた投稿を表示する。

• author (整数|文字列) - ユーザー ID またはそのコンマ区切りリスト。
• author_name (文字列) - 'user_nicename' （姓・名・ニックネームではなく）。
• author__in (配列) - ユーザーID (バージョン 3.7 以降で利用可能)。
• author__not_in (配列) - ユーザーID (バージョン 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' );

ある投稿者による投稿を除外する

'-'（マイナス）記号をユーザー ID の頭につけることで、あるひとり(singular)の投稿者による投稿を除いて、すべての記事を表示できます：

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

複数の投稿者を扱う

複数の投稿者の投稿を表示する：

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

以下の方法で複数の投稿者を除外することもできます：

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

カテゴリーのパラメータ

あるカテゴリーに関連付けられた投稿を表示する。

• cat (整数) - カテゴリー ID を使用します。
• category_name (文字列) - カテゴリーのスラッグ（カテゴリ名ではありません）を使用します。
• category__and (配列) - カテゴリー ID を使用します。
• category__in (配列) - カテゴリー ID を使用します。
• category__not_in (配列) - カテゴリー ID を使用します。

1つのカテゴリーの記事を表示

カテゴリーIDを使用して、そのカテゴリー（さらにそのカテゴリーの子カテゴリー）に属する記事を表示：

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

カテゴリースラッグを使用して、そのカテゴリー（さらにそのカテゴリーの子カテゴリー）に属する記事を表示：

$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' );

カテゴリースラッグを使用して、それらのカテゴリーに属する記事を表示：

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

それらのカテゴリーの "全て" に属する記事を表示:

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

カテゴリーに属する記事を除外

ID に '-'（マイナス記号）が付いたカテゴリーの記事を除くすべての記事を表示：

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

複数カテゴリーの扱い

複数のカテゴリーに属する記事を表示。下記はカテゴリー ID が2と6の両方に属する記事を表示します：

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

カテゴリー ID が2または6の記事を表示するには、前述の cat か、または category__in（これらのカテゴリーの子カテゴリーの記事は表示されないことに注意してください）を使うことで実現します：

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

下記の方法で、複数のカテゴリーの記事を除外することもできます：

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

タグのパラメータ

あるタグに関連付けられた投稿を表示する。

• tag (文字列) - タグのスラッグを指定。
• tag_id (整数) - タグ ID を指定。
• tag__and (配列) - タグ ID を指定。
• tag__in (配列) - タグ ID を指定。
• tag__not_in (配列) - タグ ID を指定。
• tag_slug__and (配列) - タグのスラッグを指定。
• tag_slug__in (配列) - タグのスラッグを指定。

１つのタグの記事を表示

タグのスラッグを使って、このタグを持つ記事を表示：

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

タグのIDを使って、このタグを持つ記事を表示：

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

複数のタグから記事を表示

これらのいずれかのタグを持つ記事を表示：

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

これらのすべてのタグを持つ記事を表示：

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

複数タグの扱い

タグID 37 と 47 の両方にタグ付けられた記事を表示：

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

タグID 37 と 47 いずれかの記事を表示するには、前述の tag か、もしくは tag__in を使って明示的に特定することで実現します：

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

タグID 37 と 47 、２つのタグのいずれも持たない記事を表示：

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

tag_slug__in と tag_slug__and は、タグのスラッグを対象とすることを除いて、それぞれ tag__in と tag__and とほぼ同様に動作します。

タクソノミーのパラメータ

あるタクソノミーに関連付けられた投稿を表示する。

• {tax} (文字列) - タクソノミーのスラッグを使用します。注：バージョン3.1以降は非推奨になりましたので、代わりに 'tax_query' を使用してください。
• tax_query (配列) - タクソノミーパラメータを使用（バージョン3.1から利用可能）。

• • relation (文字列) - 2つ以上のタクソノミー検索条件（内側の配列）が含まれる場合に、それらの論理的な関係を指定します。有効な値は 'AND' または 'OR' です。1つしかタクソノミー検索条件を含まない場合は指定しないでください。デフォルトは 'AND' です。
  • taxonomy (文字列) - タクソノミー。
  • field (文字列) - タクソノミータームの種類を選択します。有効な値は 'term_id'（デフォルト）、'name'、'slug' または 'term_taxonomy_id' です。
  • terms (整数/文字列/配列) - タクソノミーターム。
  • include_children (真偽値) - 階層を持つタクソノミーの場合に子孫タクソノミーを含めるかどうか。デフォルトは true（含める）です。
  • operator (文字列) - 演算子。使用可能な値は 'IN'(デフォルト), 'NOT IN', 'AND', 'EXISTS' (4.1.0以降) と 'NOT EXISTS'(4.1.0以降) です。

重要な参考ポイント: tax_query は、タクソノミー検索条件（配列）の配列 をパラメータにします（つまり配列の配列です）。 下記の2番目の例を見るとわかりやすいでしょう。この構造によって、複数のタクソノミーを検索できますが、その時は最初の（外側の）配列の relation パラメータによって複数のタクソノミー検索の関係を指定します。

シンプルなカスタム分類のクエリ:

カスタム分類 people の bob に関連付けられた投稿（post）を表示します :

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

複数のカスタム分類の取り扱い:

いくつかのカスタム分類から投稿を表示します:

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

カテゴリー quotes に所属するか投稿フォーマットが quote の投稿（post）を表示します:

$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 );

カスタム分類の取扱いを入れ子で指定:

バージョン 4.1 以降、より複雑なクエリを作成するために 'tax_query' 句を入れ子にすることができます。

例: カテゴリー quotes に所属する、もしくは投稿フォーマットが quote かつカテゴリー wisdom に所属する投稿を表示:

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

検索パラメータ

キーワード検索によって投稿を表示します。

• s (文字列) - 検索するキーワード。

キーワード検索によって投稿を表示

「キーワード」という検索語にマッチする投稿を表示します：

$query = new WP_Query( array( 's' => 'キーワード' ) );

ハイフンを前置した言葉を与えると、その言葉にマッチした投稿を除外します。例えば 'pillow -sofa' は 'pillow' を含むが 'sofa' を含まない投稿を返します（バージョン4.4以降）。

投稿と固定ページのパラメータ

投稿および固定ページに基づいてコンテンツを表示する。

• p (整数) - 投稿の ID を使用する。デフォルトの投稿タイプは post です。
• name (文字列) - 投稿のスラッグを使用する。
• title (文字列) - 投稿のタイトルを使用する。（バージョン4.4以降）
• page_id (整数) - 固定ページの ID を使用する。
• pagename (文字列) - 固定ページのスラッグを使用する。
• post_parent (整数) - 固定ページの ID を使用する。子ページを返す。
• post_parent__in (配列) - 投稿の ID を使用する。親の ID が配列内にある投稿を返す。（バージョン3.6以降）
• post_parent__not_in (配列) - 投稿の ID を使用する。親の ID が配列内にない投稿を返す。（バージョン3.6以降）
• post__in (配列) - 投稿の ID を使用する。取得するために投稿を指定する。注意: 先頭固定表示の投稿がある場合、欲しいかどうかに関係なくその投稿も取得されます（先頭に!）。この動作を避けるには ignore_sticky_posts を使ってください。
• post__not_in (配列) - 投稿の ID を使用する。指定された投稿は取得されない。同じクエリで post__in と共に使うと、これは無視される。
• post_name__in (配列) - 投稿のスラッグを使う。（バージョン4.4以降）

参考: Ticket #28099 post__in に空の配列を渡すと、has_posts() が true になります（すべての投稿が返されます）。post__in へ渡す配列が空のとき WP_Query を使う必要があるかどうかの判定処理を導入すると良いでしょう。

IDで投稿/ページを表示

投稿のIDを指定して表示する:

$query = new WP_Query( array( 'p' => 7 ) );
// 固定ページなら:	'page_id'=>7

参考: ID = 0 でも結果が返されるので注意しましょう。

スラッグで投稿/ページを表示

投稿のスラッグを指定して表示する:

$query = new WP_Query( 'name=about-my-life' );
// 固定ページなら:	'pagename'=>'about-my-life'

子投稿/子ページを表示

スラッシュで区切られた親ページと子ページのスラッグを使って子ページを表示する（例: 'parent_slug/child_slug'）:

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

親ページの ID を使って子ページを表示する:

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

子ページは除外し、トップレベルのページのみ表示する:

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

配列中の ID で示されたページを親に持つ投稿を表示する:

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

複数の投稿/ページを操作

指定された投稿のみ表示:

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

指定された以外の全ての投稿を表示:

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

注意: 同じクエリ内で 'post__in' と 'post__not_in' を同時に使うことは出来ません。

またこのとき、コンマで区切られたリストを含む文字列では正常に動かないことにも注意してください。

'post__not_in' => array( '1,2,3' )  // <--- これは動きません

パスワードのパラメータ

パスワードのパラメータを指定した場合、投稿と固定ページのパラメータで選ばれた投稿や固定ページが対象になります。デフォルトの post_type は投稿であり固定ページではないことを覚えておきましょう。

• has_password (真偽値) - パスワードで保護された投稿を表示するには true、保護されてない投稿を表示するには false を指定します。またパスワードの有無に関わらず表示したい場合は null を指定します（デフォルト）。（バージョン 3.9 から使用可能）
• post_password (文字列) - 特定のパスワードで保護されている投稿を表示します。（バージョン 3.9 から使用可能）

パスワード保護の有無に応じて表示する

パスワード保護された投稿のみ表示する:

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

パスワード保護されていない投稿のみ表示する:

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

パスワード保護の有無に関わらず投稿を表示する:

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

特定のパスワードで保護されている記事を表示

'zxcvbn' というパスワードを持つ投稿を表示する:

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

投稿タイプのパラメータ

ある投稿タイプに関連付けられた投稿を表示します。

• post_type (文字列 / 配列) - 投稿を[[投稿タイプ]によって取得する。デフォルト値は 'post'。'tax_query' がクエリーにセットされている場合、デフォルト値は 'any' になります。
  • 'post' - 投稿。
  • 'page' - 固定ページ。
  • 'revision' - 履歴 (リビジョン) 。
  • 'attachment' - 添付ファイル。WP_Query のデフォルトでは 'post_status' が 'published' ですが、添付ファイルはデフォルトで 'post_status' が 'inherit' になっています。そのため 'post_status' を明示的に 'inherit' か 'any' にしなければ、どの添付ファイルも取得できません。（後に出てくる ステータスのパラメータ を見てください）
  • 'nav_menu_item' - ナビゲーションメニュー項目。
  • 'any' - リビジョンと 'exclude_from_search' が true にセットされたものを除き、すべてのタイプを含める。
  • カスタム投稿タイプ (例えば movies)

投稿タイプによる投稿の表示

固定ページのみ表示:

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

'any'（すべての）投稿タイプを表示（リビジョンと 'exclude_from_search' が TRUE になっている投稿タイプを除くすべての投稿タイプが含まれます）:

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

カスタムポストタイプを含む複数のポストタイプを表示:

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

ステータスのパラメータ

ある投稿ステータスに関連付けられた投稿を表示します。

• post_status (文字列 / 配列) - 投稿ステータスを指定します。 デフォルト値は 'publish' です。しかしユーザーがログイン中なら、'private' が追加されます。公開された (Public) カスタムステータスもデフォルトで含まれます。さらに管理画面のコンテキストでクエリが動作中なら（管理画面または AJAX 呼び出し）、保護状態のステータスも追加されます。デフォルトでは保護状態のステータスは 'future', 'draft' と 'pending' です。
  • 'publish' - 公開された投稿もしくは固定ページ
  • 'pending' - レビュー待ちの投稿
  • 'draft' - 下書きの投稿
  • 'auto-draft' - コンテンツのない、新規作成された投稿
  • 'future' - 予約公開設定された投稿
  • 'private' - ログインしていないユーザーから見えない設定
  • 'inherit' - リビジョン。 get_childrenを見てください。
  • 'trash' - ゴミ箱に入った投稿。 (Version 2.9 以降で利用可能)。
  • 'any' - 'exclude_from_search' が true にセットされているもの（つまり trash と auto-draft）を除き、すべてのステータスの投稿を取得する。

ステータスによる投稿の表示

下書きのみ表示:

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

複数の投稿のステータスを表示:

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

すべての添付ファイルを表示:

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

コメントパラメータ

バージョン4.9以降、comment_count パラメータを導入しました。

• comment_count (整数) - 投稿のコメント数（比較演算子は '=' が使われる）
• comment_count (配列) -
  • value (整数) - 投稿のコメント数と比較する数。
  • compare (文字列) - 比較演算子。可能な値は '=', '!=', '>', '>=', '<', '<=' です。デフォルトは '=' です。

簡単なコメント数のクエリ:

コメント数が20の投稿を表示する:

$args = array(
	'post_type' => 'post',
	'comment_count' => 20,
	)
);
$query = new WP_Query( $args );

高度なコメント数のクエリ:

コメント数が25以上の投稿を表示する:

$args = array(
	'post_type' => 'post',
	'comment_count' => array(
		array(
			'value' => 25,
			'compare' => '>=',
		),
	)
);
$query = new WP_Query( $args );

ページ送りパラメータ

• nopaging (真偽値) - すべての投稿を含めるか、ページ送りに対応させます。デフォルト値は false で、ページ送りに対応します。
• posts_per_page (整数) - 1ページに含める投稿数（バージョン 2.1 以降で使えます。非推奨になった showposts パラメータを置き換えます）。'posts_per_page'=>-1 を使用するとすべての投稿を含めます（このとき 'offset' パラメータは無視されます）。ページ送りを使用するにはこのパラメータと一緒に 'paged' パラメータを指定してください。参考：フィードでのクエリの場合、WordPress はオプション 'posts_per_rss'（RSS/Atom フィードで表示する最新の投稿数）の値でこのパラメータを上書きします。それでも投稿数を設定するには 'post_limits' フィルターを使うか、'pre_option_posts_per_rss' フィルターで -1 を返してください。
• posts_per_archive_page (整数) - 1ページに含める投稿数ですが、アーカイブページ専用です。is_archive() か is_search() が true になるページでは、posts_per_page と showposts の値を上書きします。
• offset (整数) - ずらす（または読み飛ばす）投稿の数。注意：offset パラメータをセットすると paged パラメータを無視します。そのためページ送りされません（ワークアラウンドを見るにはここをクリック /en）。反対に 'offset' パラメータは 'posts_per_page'=>-1 が使われると（すべての投稿を表示）無視されます。
• paged (整数) - ページ番号。「前の投稿」リンクを使った場合にふつうページ X に表示されるであろう投稿を含めます。
• page (整数) - 静的フロントページ用のページ番号。静的フロントページのページ X に表示されるであろう投稿を表示します。
• ignore_sticky_posts (真偽値) - 先頭固定表示の投稿を無視します（バージョン 3.1 以降で使えます。非推奨になった caller_get_posts パラメータを置き換えます）。デフォルトは false で、無視しません（先頭に含めます）。true にすると無視します。なお、先頭固定表示の投稿を無視（除外）しても先頭に出てこないだけで、投稿リストにそれらの投稿が本来並ぶべき位置には出てきます。

ページあたり x 件の投稿を表示

$query = new WP_Query( array( 'posts_per_page' => 3 ) );	// ページあたり3件の投稿を表示

$query = new WP_Query( array( 'posts_per_page' => -1 ) );	// 1つのページに全ての投稿を表示

ページネーションを無効にして全ての投稿を表示する:

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

投稿を読み飛ばす

4番目の投稿から表示する:

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

最新から3つを飛ばして5件の投稿を表示:

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

xページから投稿を表示

$query = new WP_Query( array( 'paged' => 6 ) );	// ページ番号6の記事を表示

現在のページから投稿を表示

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

現在のページから投稿を表示するが、もしクエリ変数がセットされていなければ（先頭ページなら）'page' パラメータに 1 をセットする。

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

ページネーションの参考：静的フロントページに指定したページテンプレートにおいて、クエリをページ送りに対応させるには get_query_var( 'page' ); を使ってください。さらにクエリ変数 'page' は、<!--nextpage--> クイックタグ をコンテンツに含んでおりページ分割された単一の投稿または固定ページについて、ページ番号を保持します。

静的フロントページの現在のページから投稿を表示する：

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

先頭固定表示の投稿を含める

先頭固定表示の投稿のうち最初のひとつを取得します：

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

最初の先頭固定表示の投稿を取得しますが、もしなければ最新の投稿を取得します：

$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...
}

先頭固定表示の投稿を無視する

クエリからすべての先頭固定表示の投稿を除外します：

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

カテゴリー内のすべての投稿を取得しますが、先頭固定表示の投稿を先頭に入れません（ignore）。ただし本来出てくるべき位置（例：日付順）には先頭固定表示の投稿が含まれます:

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

あるカテゴリーから先頭固定表示の投稿を無視して取得します。カテゴリー内の投稿を取得しますが、先頭固定表示の投稿を完全に除外します。さらにページングに対応させます：

$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' パラメータについて昇順か降順かを指定します。デフォルトは 'DESC'（降順）です。複数の order/orderby の組を配列で指定することもできます。
  • 'ASC' - 最低から最高へ昇順 (1, 2, 3; a, b, c).
  • 'DESC' - 最高から最低へ降順 (3, 2, 1; c, b, a).

• orderby (文字列 | 配列) - パラメータで指定した項目の値で投稿をソートする。デフォルトは 'date' (post_date) です。2つ以上のオプションを含めることもできます。
  • 'none' - 順序をつけない（バージョン 2.8 以降で使用可能）。
  • 'ID' - 投稿 ID で並び替える。大文字に注意。
  • 'author' - 著者で並び替える。('post_author' でも良い。)
  • 'title' - タイトルで並び替える。('post_title' でも良い。)
  • 'name' - スラッグで並び替える。('post_name' でも良い。)
  • 'type' - 投稿タイプで並び替える。('post_type' でも良い。)
  • 'date' - 日付で並び替える。('post_date' でも良い。)
  • 'modified' - 更新日で並び替える。('post_modified' でも良い。)
  • 'parent' - 投稿/固定ページの親 ID 順。('post_parent' でも良い。)
  • 'rand' - ランダムで並び替える。'RAND(x)' も使えます（'x' はシードになる整数）。
  • 'comment_count' - コメント数で並び替える（バージョン 2.9 以降で使用可能）。
  • 'relevance' - 文字列検索のとき次の順で並び替える: 1. 文字列全体がマッチ。 2. すべての単語がタイトルに含まれる。 3. いずれかの単語がタイトルに現れる。 4. 文字列全体が post_content に現れる。
  • 'menu_order' - 固定ページの表示順で並び替える。固定ページ（固定ページ編集画面のページ属性ボックス）と添付ファイル（ギャラリー内のメディアの順番に相当）で使うことが最も多いでしょう。しかしバラバラの値が入った 'menu_order' を持つ任意の投稿タイプに対して使うことができます（デフォルト値は 0）。
  • 'meta_value' - カスタムフィールドで並び替える。'meta_key=keyname' がクエリに存在しなければいけません。また、ソート順は文字列順になることに注意して下さい。数値だと予想外の挙動をします（通常、1, 3, 4, 6, 34, 56となると思うところが、1, 3, 34, 4, 56, 6となります）。数値なら代わりに 'meta_value_num' を使ってください。カスタムフィールドの値を特定の型にキャストしたければ 'meta_type' を指定できます。有効な値は 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED' です（'meta_query' と同じ）。'meta_type' を使うとき、それに応じて 'meta_value_*' も使えます。例えば 'meta_type' に DATETIME を指定するとき、ソート順の定義に 'meta_value_datetime' を使えます。
  • 'meta_value_num' - カスタムフィールドの値を数値として並び替える。（バージョン 2.8 以降で使用可能）。これもまた、'meta_key=keyname'がクエリに存在しなければならないことに注意して下さい。こちらは 'meta_value' 示したような数値での並べ替えを可能にします。
  • 'post__in' - post__in パラメータの配列に並んだ投稿 ID の順になります（バージョン 3.5 以降で利用可能）。
  • 'post_name__in' - 'post_name__in' パラメータの配列に並んだ投稿スラッグの順になります（バージョン 4.6 以降で利用可能）。参考: このとき order パラメータの値はソート順を変えません。
  • 'post_parent__in' - 'post_parent__in' パラメータの配列に並んだ親投稿 ID の順になります（バージョン 4.6 以降で利用可能）。参考: このとき order パラメータの値はソート順を変えません。

タイトルで投稿をソート表示、降順

投稿をその 'title' で降順に並べ替えて表示します:

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

投稿を 'menu_order' の降順でソートして表示します。同じ値なら投稿の 'title' の順にします:

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

ランダムに投稿を表示

ランダムに投稿を1件表示する:

$args = array(
	'orderby'        => 'rand',
	'posts_per_page' => '1',

);
$query = new WP_Query( $args );

人気の投稿を表示

投稿をコメント数の順に表示する:

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

値段順にソートした商品を表示

'Product' 投稿タイプをカスタムフィールド 'Price' で並び替えて表示:

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

複数の値を 'orderby' に指定

固定ページを 'title' と 'menu_order' で並び替えて表示（タイトルが優先）:

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

配列を使って複数の値を 'orderby' に指定

別々の表示順（昇順/降順）の 'title' と 'menu_order' で並べ替えた固定ページを表示（バージョン 4.0 から利用可能）:

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

• 参考：A more powerful ORDER BY in WordPress 4.0

複数の orderby とソート項目のペア

$args = array(
	'orderby'  => array( 'meta_value_num' => 'DESC', 'title' => 'ASC' ),
	'meta_key' => 'age'
);
$query = new WP_Query( $args );

カスタムフィールドとカスタム投稿タイプを 'orderby' に指定

投稿タイプが 'my_custom_post_type' で 'age' 順、そして 'age' が3か4のものだけを表示（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 );

複数の meta_key を伴う orderby の指定

投稿メタの異なる2項目を使って並び替えたいとき（例: まず City で次に State）、メタクエリを合体させて orderby へ関連づける必要があります。そのとき「名前付きメタクエリ」を使います。次の例を見てください:

$q = new WP_Query( array(
    'meta_query' => array(
        'relation' => 'AND',
        'state_clause' => array(
            'key' => 'state',
            'value' => 'Wisconsin',
        ),
        'city_clause' => array(
            'key' => 'city',
            'compare' => 'EXISTS',
        ), 
    ),
    'orderby' => array( 
        'city_clause' => 'ASC',
        'state_clause' => 'DESC',
    ),
) );

上のコードは WPSE の cybmeta による この例 から引用しました。

日付パラメータ

ある期間に関連付けられた投稿を表示する。

• year (整数) - 4桁の年 (例: 2011)。
• monthnum (整数) - 月 (1 から 12)。
• w (整数) - 週の番号 (0 から 53)。MySQL の WEEK コマンド を使用。このモードは "start_of_week" オプションに依存します。
• day (整数) - 日 (1 から 31)。
• hour (整数) - 時 (0 から 23)。
• minute (整数) - 分 (0 から 60)。
• second (整数) - 秒 (0 から 60)。
• m (整数) - 年と月 (例えば: 201307)。

• date_query (配列) - 複雑な指定ができる日付パラメータ (バージョン 3.7 から利用可能)。
  • year (整数) - 4桁の年 (例: 2011)。
  • monthnum (整数) - 月 (1 から 12)。
  • w (整数) - 週の番号 (0 から 53)。
  • day (整数) - 日 (1 から 31)。
  • hour (整数) - 時 (0 から 23)。
  • minute (整数) - 分 (0 から 60)。
  • second (整数) - 秒 (0 から 60)。
  • after (文字列/配列) - この日付より後の投稿を取得。strtotime() 互換の文字列、または 'year', 'month', 'day' の値を持つ配列を指定可能:
    • year ('文字列) 4桁の年。デフォルトは空文字列。
    • month (文字列) 月 (1 から 12)。デフォルトは12。
    • day (文字列) 日 (1 から 31)。デフォルトは月の最終日。
  • before (文字列/配列) - この日付より前の投稿を取得。strtotime() 互換の文字列、または 'year', 'month', 'day' の値を持つ配列を指定可能:
    • year (文字列) 4桁の年。デフォルトは空文字列。
    • month (文字列) 月 (1 から 12)。デフォルトは1。
    • day (文字列) 日 (1 から 31)。デフォルトは1。
  • inclusive (真偽値) - after と before について、指定された日付ぴったりを含めるかどうか。
  • compare (文字列) - WP_Date_Query::get_compare() を見てください。
  • column (文字列) - クエリ対象とする（wp_posts テーブルの）カラム。デフォルトは 'post_date'。
  • relation (文字列) - OR または AND。子の配列をどのように結合して比較するか。デフォルトは AND。

2012年12月12日の投稿を返す:

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

または:

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

今日の投稿を返す:

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

または:

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

今週の投稿を返す:

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

または:

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

平日の午前9時から午後5時までの投稿を返す

$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 );

1月1日から2月28日までの投稿を返す

$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 );

注意：before パラメータに strtotime() 互換の文字列として日付だけを指定すると、その日の 00:00:00 に変換されます。この場合、inclusive が true でも、指定した日はクエリ結果に含まれません。before に指定した日を含めたければ、'before' => '2013-02-28 23:59:59' のように時刻も含めるか、または配列形式（inclusive をセットすると自動調整される）を使ってください。

1年より前の投稿で1ヶ月以内に変更されたものを返す

$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 );

'date_query' 句を入れ子にして複雑なクエリを指定できます。構文について詳しくは タクソノミーのパラメータ を見てください。

カスタムフィールドのパラメータ

あるカスタムフィールドに関連付けられた投稿を表示します。

クエリのこの部分は WP_Meta_Query /en でパースされます。ここに示したリストは古くなるかもしれないので WP_Meta_Query の引数の説明 /en も見てください。

• meta_key (文字列) - カスタムフィールドのキー。
• meta_value (文字列) - カスタムフィールドの値（文字列として比較）。
• meta_value_num (数値) - カスタムフィールドの値（数値として比較）。
• meta_compare (文字列) -'meta_value'のテスト演算子。 使える値は '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP' および 'RLIKE' です。デフォルトは '=' です。

• meta_query (配列) - カスタムフィールドの複雑なパラメータ (バージョン 3.1 より利用可能)。
  • relation (文字列) - meta_query の中に2つ以上の配列を入れたときの論理的な関係。使える値は 'AND' と 'OR' です（デフォルト: 'AND'）。ひとつだけ配列を入れるときは使わないでください。

meta_query には次のキーを持った配列をひとつまたは複数入れることができます：

• key (文字列) - カスタムフィールドのキー。
• value (文字列|配列) - カスタムフィールドの値。配列を指定できるのは compare が 'IN', 'NOT IN', 'BETWEEN' または 'NOT BETWEEN' の場合です。WordPress 3.9 以上で compare に 'EXISTS' または 'NOT EXISTS' を指定する場合は value を省略できます。
  (参考: bug #23268 の影響で、バージョン 3.9 より前では NOT EXISTS による比較を正しく動作させるために value が必要です。value パラメータに何らかの文字列を与えなければなりません。空文字列や NULL では動作しません。しかし他のどんな文字列でもトリックが効き、NOT EXISTS を使ったときに SQL に現れません。ピンとこなければ 'bug #23268' を見てみては？）。
• compare (文字列) - テスト演算子。使える値は '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' および 'NOT EXISTS' です。デフォルトは '=' です。
• type (文字列) - カスタムフィールドの値のタイプ。使える値は 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED' です。デフォルトは 'CHAR' です。'DECIMAL' と 'NUMERIC' には有効桁数と小数点以下の桁数を指定できます（例: 'DECIMAL(10,5)' や 'NUMERIC(10)' が有効）。

'type' を DATE、'compare' を BETWEEN にして正しく比較できるのは、日付が YYYY-MM-DD 形式で保存されていて同じ形式の日付と比較する場合のみです。

重要な参考ポイント: meta_query はカスタムフィールド検索条件（配列）の配列 をパラメータにします（つまり配列の配列です）。次の例に出てきます。 この構造によって複数のカスタムフィールドを検索できますが、その時は最初の（外側の）配列の relation パラメータによって複数のカスタムフィールド検索の関係を指定します。使える値は 'AND' と 'OR' です。デフォルト 'AND' です。

簡単なカスタムフィールドクエリ:

カスタムフィールドの値に関係なく、カスタムフィールドのキーが 'color' の投稿を表示します:

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

カスタムフィールドのキーに関係なく、カスタムフィールドの値が 'blue' の投稿を表示します:

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

カスタムフィールドのキーに関係なく、カスタムフィールドの値が 'blue' の固定ページを表示します:

$args = array(
	'meta_value' => 'blue',
	'post_type'  => 'page'
);
$query = new WP_Query( $args );

カスタムフィールドのキーが 'color'、値が 'blue' の投稿を表示します:

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

カスタムフィールドのキーが 'color'、値が 'blue' ではない投稿を表示します:

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

カスタムフィールドの値が数値である投稿を表示する例です。その数値が10未満の投稿だけを表示します。（WP_Query は比較に次の式を使います: $post_meta . $args['meta_compare'] . $args['meta_value'] - ここで '$post_meta' は各投稿に保存されている投稿メタの値です。値を置換した後の実際の式は: $post_meta < 10）

$args = array(
	'post_type' => 'post',
	'meta_key' => 'number',
	'meta_value_num' => 10,
	'meta_compare' => '<',
);
$query = new WP_Query( $args );

イベントの投稿（'event' カスタム投稿タイプ）を表示します。開催日のカスタムフィールドのキーが 'event_date'、値が今日以降とします。

$args = array(
	'post_type'    => 'event',
	'meta_key'     => 'event_date',
	'meta_value'   => date( "Ymd" ), // 'event_date' の保存形式に合わせる
	'meta_compare' => '>',
);
$query = new WP_Query( $args );

製品（'product' カスタム投稿タイプ）のうち、値段（'price' カスタムフィールド）が 22 以下 であるものを表示します。
値を指定するのに 'meta_value' パラメータを使うと 99 が 100 より大きいと判定されます（数値ではなく文字列として保存されているため）。

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

カスタムフィールドのキーに関係なく、値がゼロ (0) のカスタムフィールドを持つ投稿を表示します:

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

単一のカスタムフィールドの取扱い:

1つのカスタムフィールドからの記事を表示します:

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

（meta_query はクエリがひとつだけでも入れ子の配列を指定しなければなりません。）

複数のカスタムフィールドの取扱い:

製品（カスタム投稿タイプ 'product'）について、色（カスタムフィールドのキー 'color'）が青（'blue'）ではない（'NOTE LIKE'）か、または値段（キー 'price'、タイプ 'numeric'）が20と100の間にある（'BETWEEN'）ものを表示します。

$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 );

'meta_query' 句は複雑なクエリが作れるように入れ子にできます。例えば製品（'product'）の中でオレンジ色（'color=orange'）または（'OR'）赤でサイズが小さい（'color=red&size=small'）のものを表示するのは、次のようなクエリに変換できます:

$args = array(
	'post_type'  => 'product',
	'meta_query' => array(
		'relation' => 'OR',
		array(
			'key'     => 'color',
			'value'   => 'orange',
			'compare' => '=',
		),
                array(
                        'relation' => 'AND',
                        array(
                                'key' => 'color',
                                'value' => 'red',
                                'compare' => '=',
                        ),
                        array(
                                'key' => 'size',
                                'value' => 'small',
                                'compare' => '=',
                        ),
		),
	),
);
$query = new WP_Query( $args );

権限パラメータ

• perm (文字列) - ユーザー権限。

ユーザーが適切な権限を持つ場合に投稿を表示

ユーザーが適切な権限を持つ場合に、公開済みと非公開の投稿を表示します:

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

MIME タイプのパラメータ

添付ファイル（attachments）投稿タイプと共に使ってください。

• post_mime_type (文字列/配列) - この MIME タイプに限定。

gif 画像の添付ファイルを取得:

gif 画像を取得します。添付ファイルのデフォルトの投稿ステータスが inherit であることに注意してください。

$args = array(
	'post_type'	 => 'attachment',
	'post_status'	 => 'inherit',
	'post_mime_type' => 'image/gif',
);
$query = new WP_Query( $args );

画像ではない添付ファイルを取得:

特定の MIME タイプを除外するには、まず get_allowed_mime_types() を使ってすべての MIME タイプを取得します。そして array_diff() を使って除外する MIME タイプとの差を求め、それを指定します。

$unsupported_mimes  = array( 'image/jpeg', 'image/gif', 'image/png', 'image/bmp', 'image/tiff', 'image/x-icon' );
$all_mimes          = get_allowed_mime_types();
$accepted_mimes     = array_diff( $all_mimes, $unsupported_mimes );
$args		    = array(
    'post_type'         => 'attachment',
    'post_status'       => 'inherit',
    'post_mime_type'    => $accepted_mimes,
);
$query		    = new WP_Query( $query_args );

キャッシュのパラメータ

取得したデータがキャッシュへ追加されるのを禁止します。

• cache_results (真偽値) - 投稿情報のキャッシュ。
• update_post_meta_cache (真偽値) - 投稿のメタ情報のキャッシュ（カスタムフィールドなど）。
• update_post_term_cache (真偽値) - 投稿のターム情報のキャッシュ（カテゴリーなど）。

投稿情報をキャッシュへ追加せずに投稿を表示

50本の投稿を表示しますが、投稿情報をキャッシュへ追加しません:

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

投稿メタ情報をキャッシュへ追加せずに投稿を表示

50本の投稿を表示しますが、投稿メタ情報をキャッシュへ追加しません:

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

投稿ターム情報をキャッシュへ追加せずに投稿を表示

50本の投稿を表示しますが、投稿ターム情報をキャッシュへ追加しません:

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

一般的な使い方ならキャッシュへ追加するのが普通なので、これらのパラメータを使う必要はないでしょう。しかし特定の状況では役に立ちます。例えば投稿タイトルと URL を表示するために WP_Query を使うけれども、それ以外の情報を使わずタクソノミーとメタデータも不要な場合です。これらの情報を読み込まなければ余分な SQL クエリによる時間を節約できます。

参考: バックエンドに永続的オブジェクトキャッシュ（memcached など）が使われている場合、これらのフラグはデフォルトで false にされます。なぜなら永続的キャッシュがある時はページ読み込み毎にキャッシュを更新する必要がないからです。

戻り値パラメータ

戻り値を設定します。

• fields (文字列) - どのフィールドを返すか。
  • 'ids' - 投稿IDの配列を返します。
  • 'id=>parent' - プロパティに ID（投稿ID）と post_parent（親のID）を持つ stdClass オブジェクトの配列を返します。
  • 他の何かを渡すと、すべてのフィールドを返します。 (デフォルト) - 投稿オブジェクトの配列。

フィルター

以下のフィルターは投稿の配列を返すクエリを対象にします:

• posts_distinct /en - クエリの SQL 'DISTINCTROW' 節を変更。
• posts_groupby /en - クエリの SQL 'GROUP BY' 節を変更。
• posts_join /en - クエリの SQL 'JOIN' 節を変更。
• post_limits /en - クエリの SQL 'LIMIT' 節を変更。
• posts_orderby /en - クエリの SQL 'ORDER BY' 節を変更。
• posts_where /en - クエリの SQL 'WHERE' 節を変更。
• posts_join_paged /en - クエリの中で投稿のページネーションに用いる 'JOIN' 節を変更。
• posts_where_paged /en - クエリの中で投稿のページネーションに用いる 'WHERE' 節を変更。
• posts_fields - クエリの SQL 'SELECT' 節を変更。
• posts_clauses /en - ここまでに挙げた SQL 節のすべてを一度に変更。節を要素とする配列が与えられ、変更が容易（バージョン3.1以降で使用可能）。

参考: これ以外にもフィルターがあります。この codex をいつも最新に保つのは難しいので、WP_Query クラス内の get_posts() メソッドを御自身で見てください（wp-includes/class-wp-query.php にあります）。

変更履歴

• 4.9.0:
  • Introduced the `$comment_count` parameter.
• 4.6.0:
  • Add filter 'posts_pre_query' to filter the posts array before the query takes place.
  • Add 'post_name__in' to '$orderby'.
• 4.5.0:
  • Removed the '$comments_popup' property.

• 4.4.0:
  • Add filter 'old_slug_redirect_url' to filter the old slug redirect URL.
  • Add the ability to pass a post ID to '$post' parameter of 'setup_postdata' method and function.
  • Introduced '$post_name__in' and '$title' parameters.
  • '$s' was updated to support excluded search terms, by prepending a hyphen.

• 4.1.0:
  • Add '$this' parameter to 'the_post' action (The current Query object (passed by reference)).

ソースファイル

WP_Query() は wp-includes/class-wp-query.php にあります。

外部リソース

日本語

• WordPress ループ＆クエリーのモヤモヤを解消しよう！ (wpxtreme)
• WordPress query_posts, get_posts で複数の order 指定に対応する (wpxtreme)

英語

• WordPress WP_Query Generator
• Advanced Taxonomy Queries with Pretty URLs
• Advanced Taxonomy Queries in WordPress 3.1
• Advanced Metadata Queries in WordPress 3.1
• Comprehensive Argument Reference by Mark Luetke
• WordPress custom loop
• An In-Depth Guide to Conquering WP_Query

関連項目

記事

• 記事: ループ - WordPress ループ内でのクエリの使い方に関する基本的な概要。
• 記事: クエリ概要 - どのクエリが WordPress を生成するのかが決定される方法についての説明。
• 記事: フックを使ったクエリのカスタマイズ
• 記事: カスタムセレクトクエリを使った投稿の表示 /en
• 記事: 高度なタクソノミークエリの生成 /en
• 記事: オフセットとページネーションを活用したカスタムクエリ /en

コード・ドキュメンテーション

• クラス: WP_Query - WP_Query クラスの詳細な全容
• クラス: WP_Comment_Query - コメント関連のクエリのためのクラス
• クラス: WP_User_Query - ユーザー関連のクエリのためのクラス
• オブジェクト: $wpdb - $wpdb オブジェクトの使い方全容
• 関数: set_query_var()
• 関数: get_query_var()
• 関数: query_posts() - 追加のカスタムクエリを作成
• 関数: get_post() - 項目の ID を取得しデータベース内にあるその投稿のレコードを返す
• 関数: get_posts() - 投稿の配列を返すことに特化した関数
• 関数: get_pages() - ページの配列を返すことに特化した関数
• 関数: have posts() - クエリが投稿を返すか否かを判断する条件関数
• 関数: the_post() - クエリ後に自動的にループを設定する
• 関数: rewind_posts() - 現状のループをリセットする
• 関数: setup_postdata() - ループ内で個別の結果を得るためのクエリデータを設定する
• 関数: wp_reset_postdata() - 直前のクエリを復元する (通常はループ内の別のループの後に用いられる)
• 関数: wp_reset_query()
• 関数: is_main_query() - 変更されるクエリがメインのクエリであることを確認する
• アクションフック: pre_get_posts - WordPressクエリが実行される前に変更する
• アクションフック: the_post - post クエリの後で post オブジェクトを変更する
• フィルターフック: found_posts - WP_Query オブジェクトの found_posts 値を変更する

クラスリファレンスと関数リファレンスの各インデックスも参照してください。

最新英語版： WordPress Codex » Class Reference/WP Query （最新版との差分）