WP_Queryとは | WordPressカスタマイズ事典

WP_Query

WP_Query は、データベースに保存されている投稿や固定ページ、カスタム投稿を取得するためのWordPressの主要な仕組みです。投稿を表示する際は通常必ずこの WP_Query が使用されていて、投稿一覧ページ、個別投稿ページなどでは自動的に実行されています。( have_posts()、the_post()、the_title() などのよくあるコードがすぐに使えるのもWordPressが裏で自動的に WP_Query を動かしているおかげです)

手動での使い方

WordPressが自動で動作させるものとは別に、自分で好きな条件で WP_Query を使用して投稿を取得することができます。

典型的なコードは下記のとおりです。

<?php
// 「テスト」が含まれる投稿を最大5件取得します。array()の部分が条件です(後述)
$q = new WP_Query(array(
	's' => 'テスト',
	'posts_per_page' => 5
));
// 結果が1件でも取得できた場合
if ( $q->have_posts() ) { ?>
	<div class="posts">
		<ul>
			<?php
			// 1件ずつ処理(ループ)
			while ( $q->have_posts() ) {
				$q->the_post();
				// リンクとタイトルを取得して出力します。
			?>
				<li><a href="<?php the_permalink() ?>"><?php the_title() ?></a></li>
			<?php } ?>
		</ul>
	</div>
	<?php
	// 後片付け
	wp_reset_postdata();
	?>
<?php } ?>

<?php

// 「テスト」が含まれる投稿を最大5件取得します。array()の部分が条件です(後述)

$q = new WP_Query(array(

's' => 'テスト',

'posts_per_page' => 5

));

// 結果が1件でも取得できた場合

if ( $q->have_posts() ) { ?>

<ul>

<?php

// 1件ずつ処理(ループ)

while ( $q->have_posts() ) {

$q->the_post();

// リンクとタイトルを取得して出力します。

<?php } ?>

</ul>

</div>

<?php

// 後片付け

wp_reset_postdata();

<?php } ?>

主な条件

WP_Query のすべての条件(検索条件)は Codex ( 日本語版 ) に記載されています。ここでは必要な部分をコピーして使えるように、主な条件を早見表(チートシート)のような形で紹介します。

※ 同じキー(post_typeなど)を一度に使用することはできません。下記をすべて貼り付けても動きませんので、必要な条件のみコピーしてください。
※ 投稿ステータスの一部などの使用頻度が少なそうなもの、nopaging などの役割が他のものと被っているものは省いています。(使用頻度が少なくても書き方が特殊なものは掲載しています)

$q = new WP_Query(array(
	// 投稿タイプ
	'post_type' => 'post', // 投稿(通常投稿)のみ
	'post_type' => 'page', // 固定ページのみ
	'post_type' => 'attachment', // 添付のみ
	'post_type' => array( 'post', 'page', 'attachment' ), // 投稿、固定ページ、添付のみ

	// 投稿ステータス
	'post_status' => 'publish', // 公開のみ
	'post_status' => 'pending', // レビュー待ちのみ
	'post_status' => 'draft', // 下書きのみ
	'post_status' => 'future', //  予約投稿のみ
	'post_status' => 'private', // 非公開のみ
	'post_status' => array( 'publish', 'pending', 'draft', 'future', 'private' ), // 公開、レビュー待ち、下書き、予約投稿、非公開

	// スラッグ(投稿名)・投稿データ
	'name' => 'hello-world', // 指定されたスラッグを持つデータのみ
	'post__in' => array( 1, 2, 3 ), // 指定されたIDを持つデータのみ取得
	'post__not_in' => array( 1, 2, 3 ), // 指定されたIDを持つデータ「以外」を取得

	// 検索
	's' => 'テスト', // 検索キーワードが含まれるデータのみ

	// 日付(作成日が指定した年月日)
	'year' => 2011,
	'monthnum' => 1,
	'day' => 1,

	// 日付(作成日が指定した年月日かそれ以前のデータのみ)
	'date_query' => array(
		array(
			'before' => array(
				'year'  => 2016,
				'month' => 7,
				'day'   => 1,
			),
			'inclusive' => true, // 上記の日付(2016年7月1日)のデータも結果に含める
		),
	),

	// カテゴリー
	'cat' => 4, // 指定されたIDのカテゴリーに属するデータのみ
	'category_name' => 'staff', // 指定されたスラッグ(内部名)のカテゴリーに属するデータのみ
	'category__and' => array( 1, 2, 3 ), // 指定されたIDのカテゴリーすべてに属するデータのみ
	'category__in' => array( 1, 2, 3 ), // 指定されたIDのカテゴリーのいずれかに属するデータのみ
	'category__not_in' => array( 1, 2, 3 ), // 指定されたIDのカテゴリーのどれにも属さないデータのみ

	// タグ
	'tag_id' => 4, // 指定されたIDのタグに属するデータのみ
	'tag' => 'cooking', // 指定されたスラッグ(内部名)のタグに属するデータのみ
	'category__and' => array( 1, 2, 3 ), // 指定されたIDのタグすべてに属するデータのみ
	'category__in' => array( 1, 2, 3 ), // 指定されたIDのタグのいずれかに属するデータのみ
	'category__not_in' => array( 1, 2, 3 ), // 指定されたIDのタグのどれにも属さないデータのみ

	// タクソノミー (カテゴリー、タグも含む)
	'tax_query' => array(
		// 例: staffというスラッグ(内部名)のカテゴリーに属するデータ ('category_name' => 'staff'と同じ)
		array(
			'taxonomy' => 'category', // カテゴリー。タグの場合は 'tag'、他のタクソノミーの場合はタクソノミーのスラッグ(内部名)
			'field'    => 'slug', // スラッグ
			'terms'    => 'staff', // スラッグが「staff」
		),
	),

	// カスタムフィールド(下記2つセット。例: color=blueがあるデータのみ)
	'meta_key'   => 'color', // colorという名前のフィールド
	'meta_value' => 'blue' // 値が「blue」

	// カスタムフィールド(下記3つセット。例: colorにblueという文字が含まれるデータのみ)
	'meta_key'   => 'color', // colorという名前のフィールド
	'meta_value' => 'blue' // 値が「blue」
	'meta_compare' => 'LIKE' // 含まれる

	// カスタムフィールド(複数条件が必要な場合などの別の書き方)
	'meta_query' => array(
		// colorにblueが含まれない
		array(
			'key' => 'color', // colorという名前のフィールド
			'value' => 'blue', // 値が「blue」
			'compare' => 'NOT LIKE' // 「含まれない」
		),
		// price(数値)が20〜100
		array(
			'key' => 'price', // priceという名前のフィールド
			'value'   => array( 20, 100 ), // 20〜100
			'type'    => 'numeric', // 数値として扱う
			'compare' => 'BETWEEN', // 「値(value)の間」
		),
		// 「上記どちらかでも一致すればOK」とする
		// (relationを省略したり'AND'にした場合は「条件すべて満たせばOK」
		'relation' => 'OR',
	),

	// 件数
	'posts_per_page' => -1, // 条件に当てはまる投稿すべてを取得
	'posts_per_page' => 5, // 条件に当てはまる投稿を最大5件取得
	'paged' => 2, // 2ページ目を取得 (posts_per_pageが5の場合6〜10件目)

	// 並び順
	'orderby' => 'ID', // ID順
	'orderby' => 'title', // タイトル順
	'orderby' => 'date', // 日付(日時)順
	'orderby' => 'modified', // 更新日(日時)順
	'orderby' => 'menu_order', // 「ページ属性」の「順序」順
	'orderby' => 'rand', // ランダム
	'orderby' => array( 'date', 'ID' ), // 日付(日時)順、同じ日付(日時)のデータはID順
	'orderby' => 'date ID', // 上記と同じ

	// 並び順(昇順、降順)
	'order' => 'ASC', // 昇順
	'order' => 'DESC', // 降順

	// 複雑な並び順
	'orderby' => array( 'date' => 'DESC', 'ID' => 'ASC' ), // 日付(日時)の降順、同じ日付(日時)のデータはIDの昇順

	// カスタムフィールドの並び順(下記3つ指定)
	'meta_key'   => 'age', // ageという名前のフィールド
	'orderby'    => 'meta_value_num', // カスタムフィールドを数値として並び替え
	'order'      => 'ASC', // 昇順
));

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

$q = new WP_Query(array(

// 投稿タイプ

'post_type' => 'post', // 投稿(通常投稿)のみ

'post_type' => 'page', // 固定ページのみ

'post_type' => 'attachment', // 添付のみ

'post_type' => array( 'post', 'page', 'attachment' ), // 投稿、固定ページ、添付のみ

// 投稿ステータス

'post_status' => 'publish', // 公開のみ

'post_status' => 'pending', // レビュー待ちのみ

'post_status' => 'draft', // 下書きのみ

'post_status' => 'future', // 予約投稿のみ

'post_status' => 'private', // 非公開のみ

'post_status' => array( 'publish', 'pending', 'draft', 'future', 'private' ), // 公開、レビュー待ち、下書き、予約投稿、非公開

// スラッグ(投稿名)・投稿データ

'name' => 'hello-world', // 指定されたスラッグを持つデータのみ

'post__in' => array( 1, 2, 3 ), // 指定されたIDを持つデータのみ取得

'post__not_in' => array( 1, 2, 3 ), // 指定されたIDを持つデータ「以外」を取得

// 検索

's' => 'テスト', // 検索キーワードが含まれるデータのみ

// 日付(作成日が指定した年月日)

'year' => 2011,

'monthnum' => 1,

'day' => 1,

// 日付(作成日が指定した年月日かそれ以前のデータのみ)

'date_query' => array(

array(

'before' => array(

'year' => 2016,

'month' => 7,

'day' => 1,

'inclusive' => true, // 上記の日付(2016年7月1日)のデータも結果に含める

// カテゴリー

'cat' => 4, // 指定されたIDのカテゴリーに属するデータのみ

'category_name' => 'staff', // 指定されたスラッグ(内部名)のカテゴリーに属するデータのみ

'category__and' => array( 1, 2, 3 ), // 指定されたIDのカテゴリーすべてに属するデータのみ

'category__in' => array( 1, 2, 3 ), // 指定されたIDのカテゴリーのいずれかに属するデータのみ

'category__not_in' => array( 1, 2, 3 ), // 指定されたIDのカテゴリーのどれにも属さないデータのみ

// タグ

'tag_id' => 4, // 指定されたIDのタグに属するデータのみ

'tag' => 'cooking', // 指定されたスラッグ(内部名)のタグに属するデータのみ

'category__and' => array( 1, 2, 3 ), // 指定されたIDのタグすべてに属するデータのみ

'category__in' => array( 1, 2, 3 ), // 指定されたIDのタグのいずれかに属するデータのみ

'category__not_in' => array( 1, 2, 3 ), // 指定されたIDのタグのどれにも属さないデータのみ

// タクソノミー (カテゴリー、タグも含む)

'tax_query' => array(

// 例: staffというスラッグ(内部名)のカテゴリーに属するデータ ('category_name' => 'staff'と同じ)

array(

'taxonomy' => 'category', // カテゴリー。タグの場合は 'tag'、他のタクソノミーの場合はタクソノミーのスラッグ(内部名)

'field' => 'slug', // スラッグ

'terms' => 'staff', // スラッグが「staff」

// カスタムフィールド(下記2つセット。例: color=blueがあるデータのみ)

'meta_key' => 'color', // colorという名前のフィールド

'meta_value' => 'blue' // 値が「blue」

// カスタムフィールド(下記3つセット。例: colorにblueという文字が含まれるデータのみ)

'meta_key' => 'color', // colorという名前のフィールド

'meta_value' => 'blue' // 値が「blue」

'meta_compare' => 'LIKE' // 含まれる

// カスタムフィールド(複数条件が必要な場合などの別の書き方)

'meta_query' => array(

// colorにblueが含まれない

array(

'key' => 'color', // colorという名前のフィールド

'value' => 'blue', // 値が「blue」

'compare' => 'NOT LIKE' // 「含まれない」

// price(数値)が20〜100

array(

'key' => 'price', // priceという名前のフィールド

'value' => array( 20, 100 ), // 20〜100

'type' => 'numeric', // 数値として扱う

'compare' => 'BETWEEN', // 「値(value)の間」

// 「上記どちらかでも一致すればOK」とする

// (relationを省略したり'AND'にした場合は「条件すべて満たせばOK」

'relation' => 'OR',

// 件数

'posts_per_page' => -1, // 条件に当てはまる投稿すべてを取得

'posts_per_page' => 5, // 条件に当てはまる投稿を最大5件取得

'paged' => 2, // 2ページ目を取得 (posts_per_pageが5の場合6〜10件目)

// 並び順

'orderby' => 'ID', // ID順

'orderby' => 'title', // タイトル順

'orderby' => 'date', // 日付(日時)順

'orderby' => 'modified', // 更新日(日時)順

'orderby' => 'menu_order', // 「ページ属性」の「順序」順

'orderby' => 'rand', // ランダム

'orderby' => array( 'date', 'ID' ), // 日付(日時)順、同じ日付(日時)のデータはID順

'orderby' => 'date ID', // 上記と同じ

// 並び順(昇順、降順)

'order' => 'ASC', // 昇順

'order' => 'DESC', // 降順

// 複雑な並び順

'orderby' => array( 'date' => 'DESC', 'ID' => 'ASC' ), // 日付(日時)の降順、同じ日付(日時)のデータはIDの昇順

// カスタムフィールドの並び順(下記3つ指定)

'meta_key' => 'age', // ageという名前のフィールド

'orderby' => 'meta_value_num', // カスタムフィールドを数値として並び替え

'order' => 'ASC', // 昇順

));

あ	い	う	え	お
か	き	く	け	こ
さ	し	す	せ	そ
た	ち	つ	て	と
な	に	ぬ	ね	の
は	ひ	ふ	へ	ほ
ま	み	む	め	も
や		ゆ		よ
ら	り	る	れ	ろ
わ

あ	い	う	え	お
か	き	く	け	こ
さ	し	す	せ	そ
た	ち	つ	て	と
な	に	ぬ	ね	の
は	ひ	ふ	へ	ほ
ま	み	む	め	も
や		ゆ		よ
ら	り	る	れ	ろ
わ

あ	い	う	え	お
か	き	く	け	こ
さ	し	す	せ	そ
た	ち	つ	て	と
な	に	ぬ	ね	の
は	ひ	ふ	へ	ほ
ま	み	む	め	も
や		ゆ		よ
ら	り	る	れ	ろ
わ