【WordPress】WP_Queryを徹底解説 使い方・パラメータ・応用例まで

WordPressでカスタムクエリを扱うとき、最も重要なクラスが WP_Query です。

カスタム投稿タイプ、タクソノミー、カスタムフィールドなど、WordPressの柔軟性を引き出すには WP_Query の正しい理解が不可欠です。

この記事では、WP_Query の基本から応用までをわかりやすく解説します。

「とにかく使いこなせるようになりたい！」という方はぜひチェックしてください。

WP_Queryとは？

WP_Query は WordPress の投稿データを取得するためのクラスです。

WordPress が内部的に投稿を表示するときにもこのクラスを使っています。

開発者はこれを使って、カスタムな条件で投稿を取得し、独自のループを構築できます。

なぜ WP_Query を使うのか？

get_posts() などのシンプルな関数では対応できないような、複雑な条件で投稿を取得したいときに使います。

以下のような用途にぴったりです。

• カスタム投稿タイプやタクソノミーでの絞り込み
• カスタムフィールドによる検索
• ページネーションを含む投稿一覧
• 結果のソート順や表示形式の制御

WP_Queryの基本構文

$args = array(
  'post_type' => 'post',
  'posts_per_page' => 5
);
$query = new WP_Query($args);

if ($query->have_posts()) {
  while ($query->have_posts()) {
    $query->the_post();
    the_title();
  }
}
wp_reset_postdata();

この例では、通常の投稿（post）を5件取得し、タイトルをループで表示しています。

よく使うパラメータ

post_type

取得する投稿タイプを指定します。

'post_type' => 'post' // 投稿
'post_type' => 'page' // 固定ページ
'post_type' => 'custom_post' // カスタム投稿タイプ

posts_per_page

1ページあたりに取得する投稿数です。

'posts_per_page' => 10

-1 を指定すると全件取得になります。

order / orderby

表示順の指定ができます。

'orderby' => 'date',
'order' => 'DESC'

日付の他に 'title', 'meta_value', 'rand' などが使えます。

category / tag

カテゴリーやタグで絞り込みます。

'category_name' => 'news'
'tag' => 'featured'

カスタムフィールドで絞り込む（meta_query）

カスタムフィールドで検索するには、meta_query を使います。

$args = array(
  'post_type' => 'product',
  'meta_query' => array(
    array(
      'key' => 'price',
      'value' => 1000,
      'compare' => '>=',
      'type' => 'NUMERIC'
    )
  )
);

複数条件を組み合わせたい場合は 'relation' => 'AND' や 'OR' を指定します。

タクソノミーで絞り込む（tax_query）

カスタム分類で絞り込む場合はこちら。

$args = array(
  'post_type' => 'book',
  'tax_query' => array(
    array(
      'taxonomy' => 'genre',
      'field' => 'slug',
      'terms' => array('sci-fi', 'fantasy')
    )
  )
);

こちらも relation を指定することで複数の分類条件を組み合わせられます。

ページネーションの実装方法

WP_Query はページネーションと相性がよく、テンプレートタグ paginate_links() と併用できます。

$paged = get_query_var('paged') ? get_query_var('paged') : 1;
$args = array(
  'post_type' => 'post',
  'posts_per_page' => 5,
  'paged' => $paged
);
$query = new WP_Query($args);

if ($query->have_posts()) {
  while ($query->have_posts()) {
    $query->the_post();
    the_title();
  }

  echo paginate_links(array(
    'total' => $query->max_num_pages
  ));
}
wp_reset_postdata();

paged を渡さないとページネーションが動作しないので注意が必要です。

注意点：メインクエリとの混同に注意

WP_Query は新しいクエリを発行しますが、WordPressが最初に生成するメインクエリとは異なります。
テンプレートの中で使うときには wp_reset_postdata() を忘れずに。

もしメインクエリ自体を変更したい場合は pre_get_posts フィルターを使いましょう。

以下は、**「メインクエリとサブクエリの違い」**を補足として追加する文章です。先ほどの記事の末尾、あるいは WP_Query の注意点の直後などに自然に挿入できます。

---

メインクエリとサブクエリの違いとは？

WordPressには「メインクエリ（main query）」と「サブクエリ（custom query）」という概念があります。

メインクエリは、WordPress がリクエストに応じて自動的に生成する投稿クエリで、テーマファイル（例：index.php や single.php）内で最初に実行される投稿ループです。テンプレート階層に基づいて表示されるコンテンツはすべてこのクエリが担っています。

一方、サブクエリ（またはカスタムクエリ）は、開発者が WP_Query や get_posts() を使って任意に追加するループです。ウィジェットやカスタムセクション、特定の条件で絞った投稿一覧などが該当します。

主な違い：

項目	メインクエリ	サブクエリ
自動で実行されるか	はい	いいえ（手動）
is_home() などの条件タグに影響	あり	なし
書き換え可能か	pre_get_posts で可能	各自で定義
使用場所	テンプレートのメインループ	任意の位置

例えば、functions.php 内の pre_get_posts フィルターでクエリを操作する場合はメインクエリのみが対象になります。

意図せずサブクエリに影響しないように、is_main_query() を併用するのがベストプラクティスです。

add_action('pre_get_posts', function($query) {
  if ($query->is_main_query() && !is_admin()) {
    $query->set('posts_per_page', 5);
  }
});

この違いを理解しておくと、ループの挙動やクエリの制御で混乱しにくくなります。特にカスタム投稿タイプやアーカイブページを扱う際に役立ちます。

WP_Queryを使うときのベストプラクティス

• クエリ後は必ず wp_reset_postdata() を使う
• 投稿数が多い場合は posts_per_page に注意（性能問題に繋がる）
• 高度なフィルター条件では meta_query / tax_query を正しく構成する
• キャッシュ戦略を併用する（トランジェントや object cache）

wp_reset_postdata() の役割と重要性

WP_Query を使ってループを作成した後は、必ず wp_reset_postdata() を実行しましょう。これは、グローバル変数 $post を元に戻し、テンプレートタグ（the_title() や the_permalink() など）が本来の投稿を参照するように修正するために必要です。

この関数を実行しないと、WP_Query のループ終了後に表示される投稿情報が意図せず上書きされてしまう可能性があります。

使用例：

$query = new WP_Query($args);
if ($query->have_posts()) {
  while ($query->have_posts()) {
    $query->the_post();
    the_title(); // クエリ内の投稿
  }
}
wp_reset_postdata(); // グローバル$postを元に戻す

この処理を忘れると、例えばサイドバーやフッターに表示される投稿リンクやタイトルが崩れてしまう原因になります。複数のループを扱うテンプレートでは特に注意しましょう。

よくあるミスと対処法

the_post() を使わずにテンプレートタグが機能しない

the_post() を通さないと WordPress の内部グローバル $post が設定されません。

the_title() や the_permalink() を使う前には必ず the_post() を呼びましょう。

paged を指定しないままページネーションが動かない

→ paged パラメータがないと、2ページ目以降に進めません。忘れず指定しましょう。

WP_Queryのドキュメントと参考リンク

• WP_Query – WordPress Developer Reference
• Query Parameters – WP Codex

まとめ

WP_Query は WordPress テーマやプラグイン開発において、欠かせない存在です。
最初は覚えることが多く感じられるかもしれませんが、基本の構文と使い方を押さえれば、複雑な表示やデータ処理も思いのままになります。

ループを自由に制御し、ユーザー体験を向上させるために、ぜひ積極的に使いこなしてみてください。