WP_Query 用語main query

WordPress は、アクセスされた URL に応じて「このページでは何を表示するか」を判断します。カテゴリーアーカイブならそのカテゴリーの投稿、検索結果なら検索語に一致する投稿、投稿詳細ならその1件の投稿を対象にします。この時に中心になるのが main query です。

初心者が迷いやすいのは、main query と new WP_Query() で作る独自クエリの違いです。main query はページ本体の表示対象を決めるクエリで、独自クエリは関連記事やサイドバー、トップページの一部など、追加の一覧を作るために使うクエリです。

main query は何を指す言葉か

main query は、WordPress が現在のリクエストを処理するために用意する主要なクエリです。URL、テンプレート階層、クエリ変数などに応じて、表示する投稿やページが決まります。

たとえば、カテゴリーアーカイブでは、そのカテゴリーに属する投稿を取得するクエリが main query になります。検索結果ページでは、検索語に一致する投稿を取得するクエリが main query になります。

main query は、WordPress が自動で作るクエリです。そのため、通常のテンプレートでは have_posts() や the_post() を使って、その結果を The Loop で表示します。

独自に new WP_Query() を作らなくても、すでに main query の結果が用意されている場面があります。まず「今見ている一覧は main query なのか、追加で作った独自クエリなのか」を分けて考えます。

main query と独自 WP_Query の違い

main query は、現在のページ本体の表示対象を決めるクエリです。独自 WP_Query は、開発者が追加で作る別のクエリです。

たとえば、検索結果ページの検索結果一覧は main query です。一方、検索結果ページの下に「おすすめ記事」を追加で3件出す場合、そのおすすめ記事一覧は独自 WP_Query で作ることがあります。

既存のカテゴリーアーカイブの件数や並び順を変えたい時に、新しい WP_Query で作り直すと、ページネーションやテンプレートの文脈がずれやすくなることがあります。その場合は main query の調整を検討します。

一方、ページ本体とは別に小さな一覧を追加したいだけなら、独自 WP_Query が向いています。何を変えたいのかが、main query なのかサブ一覧なのかを先に決めます。

Builder での扱い

WP Query Builder では、main query は通常のコード生成対象というより、既存一覧の調整対象として扱う想定です。独自の一覧を作るなら WP_Query のコードを生成し、既存アーカイブや検索結果を変えるなら main query の調整方針を案内します。

初心者向けには、「追加の一覧を作る」と「今ある一覧を変える」を最初に分ける UI が分かりやすくなります。前者は独自 WP_Query、後者は pre_get_posts と main query の話になります。

main query の調整コードを出す場合は、is_admin() と is_main_query() のチェックを省略しないことが重要です。安全な初期形を出し、条件分岐を少しずつ追加する流れが向いています。

使いどころ・避けどころと実践確認

WordPressが現在のURLを解釈して用意した、ページ本体の投稿集合を指す時に使う概念です。

サイドバーや関連記事の独自クエリまでメインクエリと呼ばず、役割を分けます。

メインクエリをテンプレート内で作り直すとページネーションや条件分岐がずれるため、変更時点をフックへ寄せます。

URLに応じてWordPressが用意した一覧は作り直すより、実行前に必要な条件だけ変える方がページ送りを保ちやすくなります。

対象URLでクエリ変数、条件分岐、表示された投稿ID、ページ総数を変更前後に記録し、本体のクエリだけが変わったか確かめます。

実践記事で確認query_postsを使わないほうがいい理由

query_posts() で置き換える問題と、pre_get_posts で既存条件を変える方法を対比できます。

記事を読む →

WordPressの仕様で確認するポイント

公式資料では、WP_Query Class でクエリの基本構造を確認できます。main query を実行前に調整する場合は、pre_get_posts フックと is_main_query() のリファレンスを合わせて確認します。

また、main query の結果を表示する流れは The Loop と関係します。取得対象と表示処理を分けて読むと理解しやすくなります。

main query は、WordPress が現在のページを表示するために自動で用意する主要なクエリです。アーカイブや検索結果など、ページ本体の一覧条件を変えたい時に関係します。

迷った時は、追加の一覧を作りたいのか、既存の一覧を変えたいのかを先に分けます。既存一覧なら main query、追加一覧なら独自 WP_Query という切り分けから確認します。