WordPressで特定の条件に一致する投稿を取得する際に不可欠なのがWP_Queryクラスです。このクラスは非常に多くのパラメータ（引数）を受け付けるため、その全てを記憶するのは大変です。この記事では、WP_Queryでよく使われる主要なパラメータをチートシートとしてまとめ、それぞれの利用頻度や簡単なサンプルコードを交えて解説します。
WP_Queryをマスターすることは、WordPressテーマやプラグイン開発において、より柔軟で強力なコンテンツ表示を実現するための鍵となります。
WP_Queryの基本的な使い方
WP_Queryを使用する基本的な流れは以下のようになります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
<?php // パラメータ（引数）の配列を定義 $args = array( // ここに様々なパラメータを指定します 'post_type' => 'post', 'posts_per_page' => 5, ); // WP_Queryオブジェクトを生成 $the_query = new WP_Query( $args ); // ループの開始 if ( $the_query->have_posts() ) : while ( $the_query->have_posts() ) : $the_query->the_post(); // ループ内の処理（投稿タイトルや内容の表示など） the_title( '<h3>', '</h3>' ); the_excerpt(); endwhile; // ページネーションなどの処理（必要な場合） // 例: a_custom_pagination_function(); // ループ後のクリーンアップ（重要） wp_reset_postdata(); else : // 投稿が見つからなかった場合の処理 echo '<p>該当する投稿は見つかりませんでした。</p>'; endif; ?> |
この$args配列に指定できるパラメータが今回のチートシートの主役です。
主要パラメータ一覧
以下に、WP_Queryで使用できる主要なパラメータを機能別に分類しました。各パラメータの説明の冒頭には、その利用頻度や重要度を星の5段階評価で示しています。星の数の目安は以下の通りです。
★★★★★：ほぼ全ての開発で頻繁に利用され、基本かつ非常に重要なパラメータ
★★★★☆：高頻度で利用され、多くの一般的なカスタマイズで役立つ重要なパラメータ
★★★☆☆：中程度の頻度で利用され、特定の機能を実現する際に便利なパラメータ
★★☆☆☆：利用頻度はやや低めですが、特定の要件や細かな制御を行いたい場合に役立つパラメータ
★☆☆☆☆：利用頻度は低く、非常に限定的な状況や高度なカスタマイズでのみ使用されるパラメータ
| カテゴリ | パラメータ名 | 説明 | 一般的な値の例 |
|---|---|---|---|
| 投稿タイプ関連 | post_type |
★★★★★ 取得する投稿タイプを指定します。 |
'post', 'page', 'my_custom_post_type', array('post', 'page') |
post_status |
★★★☆☆ 取得する投稿のステータスを指定します。 |
'publish', 'pending', 'draft', 'future', 'private', array('publish', 'future') |
|
any |
★★☆☆☆post_typeに指定すると、全ての投稿タイプ（一部システム内部のものを除く）を取得します。 |
'any' |
|
| 投稿数・順序関連 | posts_per_page |
★★★★★ 1ページあたりに表示する投稿数を指定します。 -1を指定すると全件取得します。 |
10, 5, -1 |
nopaging |
★★☆☆☆trueに設定すると、ページネーションを無視して全ての投稿を取得します (posts_per_page = -1 と同様の効果)。 |
true, false (デフォルト) |
|
orderby |
★★★★★ 投稿の並び順の基準を指定します。 |
'date', 'title', 'modified', 'ID', 'rand', 'comment_count', 'menu_order', 'meta_value', 'meta_value_num' |
|
order |
★★★★★ 投稿の並び順（昇順・降順）を指定します。 orderbyとセットで使います。 |
'ASC' (昇順), 'DESC' (降順) |
|
meta_key |
★★★☆☆orderbyで'meta_value'または'meta_value_num'を指定した場合に、並び替えの基準となるカスタムフィールドのキーを指定します。 |
'price', 'event_date' |
|
offset |
★★☆☆☆ 指定した数だけ投稿をスキップして取得します。ページネーションとは別に使います。 |
3 (最初の3件をスキップ) |
|
paged |
★★★☆☆ ページネーションで現在のページ番号を指定します。 |
get_query_var('paged'), get_query_var('page') |
|
| タクソノミー関連 | cat |
★★★☆☆ カテゴリーIDを指定して、そのカテゴリーに属する投稿を取得します。 |
5, -5 (ID:5を除外) |
category_name |
★★★☆☆ カテゴリースラッグを指定します。 |
'news', 'event/featured' |
|
tag |
★★★☆☆ タグスラッグを指定します。 |
'wordpress', 'php' |
|
tag_id |
★★☆☆☆ タグIDを指定します。 |
12 |
|
tax_query |
★★★★★ 複数のタクソノミー条件を組み合わせて指定します。非常に強力です。 |
下記サンプルコード参照 | |
relation |
★★★☆☆tax_query内で複数のタクソノミー条件を指定した場合の関係性（ANDまたはOR）を指定します。 |
'AND', 'OR' (デフォルトは’AND’) |
|
| カスタムフィールド関連 | meta_key |
★★★☆☆ 特定のカスタムフィールドキーを持つ投稿を取得します。値の指定は meta_valueで行います。 |
'product_color' |
meta_value |
★★★☆☆meta_keyで指定したカスタムフィールドの値を指定します。 |
'red' |
|
meta_value_num |
★★☆☆☆meta_keyで指定したカスタムフィールドの値を数値として比較する場合に使います。 |
100 |
|
meta_compare |
★★★☆☆ カスタムフィールドの値の比較方法を指定します。 |
'=', '!=', '>', '<', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'EXISTS', 'NOT EXISTS' |
|
meta_query |
★★★★★ 複数のカスタムフィールド条件を組み合わせて指定します。 tax_queryと同様に強力です。 |
下記サンプルコード参照 | |
| 投稿ID・スラッグ関連 | p |
★★★☆☆ 投稿IDを指定して、単一の投稿を取得します。 |
123 |
name |
★★★☆☆ 投稿スラッグを指定して、単一の投稿を取得します。 |
'hello-world' |
|
post__in |
★★★☆☆ 指定した投稿IDの配列に一致する投稿のみを取得します。 |
array(2, 4, 6) |
|
post__not_in |
★★★☆☆ 指定した投稿IDの配列を除外して投稿を取得します。 |
array(1, 3, 5) |
|
| 日付関連 | year |
★★☆☆☆ 年を指定します (例: 2025)。 |
2025 |
monthnum |
★★☆☆☆ 月を数値で指定します (1-12)。 |
12 (12月) |
|
date_query |
★★★☆☆ より複雑な日付条件（期間指定など）を指定します。 |
下記サンプルコード参照 | |
| 著者関連 | author |
★★★☆☆ 著者IDを指定します。 |
1 |
author_name |
★★☆☆☆ 著者名（user_nicename）を指定します。 |
'admin' |
|
| 検索関連 | s |
★★★☆☆ 検索キーワードを指定します。 |
'WordPress astra' |
exact |
★☆☆☆☆sパラメータでの検索時に完全一致検索を行うか (true)、部分一致検索を行うか (false、デフォルト) を指定します。 |
true |
|
sentence |
★☆☆☆☆sパラメータでの検索時に、フレーズ全体として検索するか (true)、各単語で検索するか (false、デフォルト) を指定します。 |
true |
|
| キャッシュ関連 | cache_results |
★★☆☆☆ クエリ結果をキャッシュするかどうかを指定します。デフォルトは true。 |
true, false |
update_post_meta_cache / update_post_term_cache |
★★☆☆☆ 投稿メタデータやタームメタデータをキャッシュするかどうか。デフォルトは true。大量の投稿を処理する際にfalseにするとパフォーマンス改善が見込める場合があります。 |
true, false |
サンプルコード集
いくつかの一般的なユースケースに対応するサンプルコードを紹介します。
1. 特定のカスタム投稿タイプから最新5件の記事を取得
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
<?php $args_news = array( 'post_type' => 'news', // カスタム投稿タイプ 'news' 'posts_per_page' => 5, 'orderby' => 'date', 'order' => 'DESC', ); $news_query = new WP_Query( $args_news ); if ( $news_query->have_posts() ) : while ( $news_query->have_posts() ) : $news_query->the_post(); // 表示処理 the_title('<h4>', '</h4>'); endwhile; wp_reset_postdata(); else : echo '<p>お知らせはありません。</p>'; endif; ?>; |
2. 複数のタクソノミー条件（カテゴリーとタグ）で絞り込み
「イベント」カテゴリーに属し、かつ「注目」タグが付いている投稿を取得します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
<?php $args_event_featured = array( 'post_type' => 'post', 'posts_per_page' => 3, 'tax_query' => array( 'relation' => 'AND', // AND条件 (両方に一致) array( 'taxonomy' => 'category', 'field' => 'slug', 'terms' => 'event', // カテゴリースラッグ 'event' ), array( 'taxonomy' => 'post_tag', 'field' => 'slug', 'terms' => 'featured', // タグスラッグ 'featured' ), ), ); $event_query = new WP_Query( $args_event_featured ); // ループ処理は上記と同様 ?>; |
3. カスタムフィールドの値で絞り込み
カスタムフィールド「event_date」が今日以降の日付である投稿を、日付順（昇順）で取得します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
<?php $today = date('Ymd'); // 今日の日付をYYYYMMDD 形式で取得 $args_upcoming_events = array( 'post_type' => 'event_cpt', // カスタム投稿タイプ 'event_cpt' 'posts_per_page' => 10, 'meta_key' => 'event_date', // カスタムフィールドのキー 'orderby' => 'meta_value', // カスタムフィールドの値で並び替え 'order' => 'ASC', // 昇順 (古い日付から) 'meta_query' => array( array( 'key' => 'event_date', 'value' => $today, 'compare' => '>=', // 今日以降 (以上) 'type' => 'DATE', // 値を日付として比較 ), ), ); $upcoming_events_query = new WP_Query( $args_upcoming_events ); // ループ処理は上記と同様 ?>; |
meta_query の type パラメータには 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED' が指定できます。
4. 複雑な日付条件で絞り込み (date_query)
2024年12月中に公開された投稿を取得します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<?php $args_december_posts = array( 'post_type' => 'post', 'date_query' => array( array( 'year' => 2024, 'month' => 12, ), ), ); $december_posts_query = new WP_Query( $args_december_posts ); // ループ処理は上記と同様 ?>; |
date_query では、year, month, day, week, hour, minute, second や、compare ('=', '>=' など), relation ('AND', 'OR') を使ってより詳細な期間指定が可能です。
よくある質問 (FAQ)
- Q1:
WP_Queryとget_posts()の違いは何ですか？ - A1:
get_posts()は内部的にWP_Queryを使用していますが、よりシンプルな引数で投稿の配列を直接返します。一方、WP_Queryはオブジェクトを返し、ループ内で投稿データをセットアップする機能（the_post()など）やページネーション情報を保持します。複雑なクエリやメインループとは別のサブループを扱う場合はWP_Queryが適しています。簡単なリスト取得ならget_posts()が手軽です。 - Q2:
wp_reset_postdata()はなぜ必要なのですか？ - A2:
WP_Queryを使ってカスタムループを実行すると、グローバルな$postオブジェクトがそのループ内の投稿データで上書きされます。ループの後にwp_reset_postdata()を呼び出すことで、$postオブジェクトをメインクエリの現在の投稿データに復元します。これを怠ると、後続の処理や他のループ、テンプレートタグが予期せぬ動作をする可能性があります。 - Q3: パフォーマンスを考慮する上で気をつけることは？
- A3:
posts_per_page => -1(全件取得) の使用は、投稿数が多い場合にメモリを大量に消費する可能性があるため慎重に検討してください。複雑な
meta_queryやtax_queryもパフォーマンスに影響を与えることがあります。必要なデータだけを取得し、適切なインデックスがデータベースに設定されているか確認することも重要です。また、cache_results => falseやupdate_post_meta_cache => falseなどのキャッシュ関連パラメータは、特定の状況下でのパフォーマンス改善に役立つことがありますが、通常はデフォルトのtrueのままで問題ありません。
まとめ
WP_Query はWordPressで動的なコンテンツ表示を行う上で非常に強力なツールです。この記事で紹介したパラメータはほんの一部ですが、これらを組み合わせることで、ほぼあらゆる条件で投稿データを取得し、表示することができるようになります。ぜひこのチートシートを活用して、WordPress開発の効率を上げてください。
私たちの活動拠点である埼玉県川越市を中心に、WordPressサイトのテクニカルサポート、カスタマイズ、トラブルシューティングのご相談を承っております。もちろん、川越に限らず、日本全国どちらからでもお気軽にご連絡ください。
WordPressカスタマイズ・プラグイン開発を気軽にご相談くださいね。もし、ご自身でWordPressの技術力をさらに高めたい、あるいはプロジェクトの技術的な壁打ち相手が必要だとお感じでしたら、WordPress顧問エンジニアサービスもご検討いただければ幸いです。
