WP_Query 用語custom query

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

custom query は、それとは別に追加で作るクエリです。たとえば、記事本文の下に関連記事を出す、トップページの一部にお知らせを出す、サイドバーに最新記事を出す、といった場面で使います。

custom query は何を指す言葉か

custom query は、開発者が独自に条件を指定して作る投稿取得クエリです。WordPress の公式関数名そのものというより、main query とは別に作る独自の WP_Query を指す説明語として使われることが多い言葉です。

実装では、new WP_Query( $args ) の形で作ります。$args には、投稿タイプ、件数、投稿ステータス、カテゴリー条件、カスタムフィールド条件、日付条件などを指定します。

ここで大事なのは、custom query は「追加の一覧」を作るために使うことが多いという点です。ページ本体のアーカイブ一覧そのものを変えたい場合は、main query の調整も検討します。

つまり、「今ある一覧を変えたい」のか「別の一覧を追加したい」のかを先に分けます。前者は main query、後者は custom query が候補になります。

main query との違い

main query は、WordPress が現在のページ本体を表示するために自動で用意するクエリです。custom query は、開発者が追加で作る別のクエリです。

たとえば、カテゴリーアーカイブで表示される記事一覧は main query です。そのページの下に「おすすめ記事を3件」出す場合、そのおすすめ記事は custom query で作る候補になります。

既存アーカイブの表示件数や並び順を変えたい場合、custom query で作り直すとページネーションがずれやすくなります。そのような場合は、main query を調整する方針を先に確認します。

一方、記事本文の途中やサイドバーに別の一覧を追加する場合は、custom query が分かりやすい選択肢になります。ページ本体とは別のクエリとして管理できるからです。

Builder での扱い

WP Query Builder では、custom query は「新しい投稿一覧を追加する」ための生成コードとして扱う想定です。ユーザーが選んだ条件を $args にまとめ、new WP_Query() と独自ループの形で出力します。

一方、「既存のカテゴリーアーカイブや検索結果を変えたい」という目的では、custom query ではなく main query の調整を案内する必要があります。Builder では、最初に目的を分けると誤用を減らせます。

生成コードでは、wp_reset_postdata() を含めることが重要です。初心者がコピーして使うコードでは、独自クエリ後の戻し処理を省略しないようにします。

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

メインクエリとは別に、関連記事や任意の一覧など独立した投稿集合が必要な時に使います。

現在のアーカイブや検索結果そのものを変えたい場合は、別の WP_Query を増やさずメインクエリの調整を検討します。

the_post() を使う独自ループはグローバル $post を動かすため、後続テンプレートへ戻す処理までを一連の実装として扱います。

ページ本体の一覧を変えるのか、別枠の一覧を足すのかを分けると、メインクエリを壊さずに済みます。

独自ループの前・中・後で投稿IDとタイトルを出力し、リセット後に元のページ文脈へ戻ることを確認します。

実践記事で確認wp_reset_postdata()が必要な理由

独自ループ後にタイトルやテンプレートタグがずれる理由を、wp_reset_postdata() の実例で追えます。

記事を読む →

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

公式資料では、WP_Query Class で取得条件や独自クエリの構造を確認できます。The Loop では、取得した投稿を表示する基本の流れを確認できます。

custom query では、wp_reset_postdata() も重要です。独自ループ後に投稿データを戻す処理として、公式リファレンスを合わせて確認します。

custom query は、WordPress の main query とは別に、開発者が独自に作る投稿取得クエリです。関連記事や最新記事など、追加の一覧を作る時に向いています。

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