WP_Query 実装用語is_main_query()

WordPress では、1つのページ内に複数のクエリが存在することがあります。ページ本体を表示する main query、関連記事を出す custom query、サイドバーの最新記事クエリなどです。

is_main_query() は、その中で「これはページ本体の main query なのか」を確認するために使います。とくに pre_get_posts のようにクエリ条件へ影響するフックでは、対象を絞るために重要です。

is_main_query() は何を判定するか

is_main_query() は、現在のクエリが main query かどうかを判定します。main query は、WordPress が現在のページを表示するために自動で用意する主要なクエリです。

たとえば、カテゴリーアーカイブではそのカテゴリーの記事一覧、検索結果では検索語に一致する記事一覧、投稿詳細ではその投稿1件を表示するためのクエリが main query になります。

ここで大事なのは、is_main_query() は「投稿があるかどうか」を確認するものではないことです。投稿の有無は have_posts()、main query かどうかは is_main_query() で確認します。

また、is_main_query() は表示処理そのものではありません。主に、どのクエリに対して処理を適用するかを判定するために使います。

add_action( 'pre_get_posts', function( $query ) {   if ( is_admin() || ! $query->is_main_query() ) {      return;   }    if ( $query->is_search() ) {      $query->set( 'posts_per_page', 10 );   }} );

is_main_query() と $query->is_main_query() の違い

is_main_query() には、関数として使う形と、WP_Query オブジェクトのメソッドとして使う形があります。通常のテンプレート内では is_main_query() を見ることがありますが、pre_get_posts では渡された $query に対して $query->is_main_query() を使う形を優先します。

pre_get_posts では、フックに渡された $query が「今変更しようとしている対象」です。その対象が main query かを確認するために、$query->is_main_query() と書きます。

初心者は、pre_get_posts では $query->is_main_query() と覚えると安全です。対象のクエリオブジェクトを明示して判定できるからです。

関数版とメソッド版を混同すると、意図したクエリを判定できていない可能性があります。どの場所で、どのクエリを見ているのかを意識します。

Builder での扱い

WP Query Builder では、is_main_query() は通常の独自 WP_Query 生成ではなく、main query 調整モードで扱う想定です。特に pre_get_posts のコードを生成する場合に重要になります。

Builder では、「既存一覧を調整する」場合に、is_admin() と $query->is_main_query() を含む安全な雛形を出すとよいです。対象を絞らないコードは、初心者には危険です。

生成コードでは、検索結果だけ、アーカイブだけ、特定の投稿タイプだけ、など対象ページをさらに絞る選択肢も必要になります。is_main_query() だけでは、ページ種別までは限定できません。

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

フック内で変更対象をサイトのメインクエリだけへ限定したい時に判定します。

独自に作った WP_Query オブジェクトの一般的な存在確認として呼ぶのは避けます。

管理画面判定や対象ページ条件と組み合わせずに使うと、意図しない一覧やREST処理まで変更する可能性があります。

is_main_query() だけでは対象画面を絞り切れないため、管理画面か、どの一覧かという条件も必ず組み合わせます。

フック内で画面種別、is_main_query()、変更前後のクエリ変数を記録し、対象URLと非対象URLを対にして確認します。

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

query_posts() を避け、pre_get_posts と is_main_query() で対象を限定する実践設計を確認できます。

記事を読む →

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

公式資料では、関数版の is_main_query() と、WP_Query メソッドの is_main_query() を確認できます。pre_get_posts と組み合わせる場合は、メソッド版の使い方を特に確認します。

また、pre_get_posts の公式リファレンスも合わせて確認すると、なぜ対象を絞る必要があるのかを理解しやすくなります。

is_main_query() は、現在扱っているクエリが main query かどうかを判定するためのものです。pre_get_posts では、渡された $query に対して $query->is_main_query() を使う形が基本です。

迷った時は、main query を変えたいのか、custom query を作りたいのかを先に分けます。既存一覧の調整なら main query、追加一覧なら独自 WP_Query を検討します。