WP Query Builderとは？できること・できないことと使いどころ

WP Query Builderは条件から$argsを作るツール

WP_Queryを書くときは、投稿タイプ、件数、絞り込み、並び順などをPHPの配列へ正しく並べる必要があります。この取得条件をまとめた配列が$argsです。WP Query Builderは、画面で選んだ内容を$argsへ変換し、コードと日本語の説明を同時に表示します。

コードを作るだけでなく、自分が設定したクエリが「どんな投稿を取得する条件なのか」を文章で理解するためにも使えます。 思い描いた一覧と日本語の説明を見比べ、違っていたら入力を調整する。そうして必要なパラメーターを、PHPの配列として組み立てられるのが特徴です。

PCでは左側で条件を選び、右側でコードと「クエリの説明」を読み比べられます。スマートフォンでは画面下の「コード」から生成結果を開きます。パラメーター名を覚えていなくても使い始められますが、生成された内容が自分の目的と合っているかは確かめましょう。

次の画面は、詳細設定で投稿タイプをpost、公開状態をpublish、取得件数を3にした例です。入力と出力を見比べやすいように「自動高速化」はオフにしています。

同じ入力から、post_type・post_status・posts_per_pageの3項目を持つ$argsが生成されます。コードの下には、日本語で条件を説明する欄があります。

日本語の説明でも「通常投稿」「公開済み」「3件」が一致しています。入力を変えたときは、コードとあわせてこちらも読み直してみましょう。

ちなみに、「このクエリの物語」を「遊び」に切り替えると、クエリの説明がちょっと詩的な物語になります。投稿を探すはずが、夜番の観測員が記録を探す旅に出ることも（笑）。ひと息つく楽しみとして試してみてください。条件が正しいかの確認には「通常」を使いましょう。

生成した条件は、表示処理と組み合わせ、本番と分けたWordPress環境で試します。公開サイトの複製を使う「ステージング」も検証環境の一つです。サーバー上に用意する場合も、本番のファイルやDBと分離し、変更前へ戻せるようにしておきましょう。

生成した条件を試すWordPress環境をサーバー上へ用意するなら、Xserverも候補です。本番と分離し、PHP対応やバックアップ条件を確認してから選んでください。

WP Query Builderでできること

現行版は、基本的な投稿一覧だけでなく、複数の絞り込みや高速化に関わる項目まで扱えます。まずは、自分が作りたい一覧が次のどこに当てはまるかを確認してください。

目的別プリセットには、ブログ一覧、カスタム投稿一覧、検索結果、関連記事、IDだけの高速取得などがあります。候補を選ぶだけでは入力は変わらず、「プリセットを適用」で反映されます。自分の目的に近いものを土台にし、適用後の件数や絞り込みを確認してください。

詳細設定では、Tax Query、Meta Query、Date Queryを複数追加し、同じ種類の条件をANDまたはORでつなげられます。「自動高速化」を有効にすると、手動で指定していない項目に、総件数の計算・先頭固定投稿の扱い・データの先読みに関する値が補われます。たとえばno_found_rowsをfalseと明示した場合、その値は保持されます。ただし、ページ送りに総ページ数を使うか、カスタムフィールドやカテゴリーを表示するかによって適切な値は変わります。生成後は、補われた項目と日本語の説明も確認してください。

WP Query Builderだけでは完了しないこと

WP Query Builderが作るのは、WP_Queryへ渡す条件の土台です。WordPressサイトへ接続して投稿を検索しているわけではないため、入力した投稿タイプ、ID、スラッグ、メタキーが実際に存在するかまでは判定できません。

現在の役割外、または専用UIがないものは次のとおりです。

UIにない指定が必要でも、WP_Query自体で使えないとは限りません。WP Query Builderで作った$argsを土台に公式リファレンスを確認し、必要な条件をコードへ追加します。反対に、複雑な入れ子条件や独自処理が中心なら、最初からコードで組んだほうが意図を追いやすい場合があります。

作りたい一覧に必要な条件が分かったら、WP Query Builderで入力してみましょう。生成後は、表示ループを用意して検証環境で動かします。

専門用語より、やりたいことから調べる

最初からtax_queryやmeta_queryという名前で探すと、自分に必要な条件かどうかを判断しにくくなります。先に「どの投稿を・何で絞り・どう並べ・何件出すか」を日本語で1行にします。

たとえば「eventというカスタム投稿を、開催日が今日以降のものだけ、近い順に6件表示する」と書ければ、調べる項目を次のように分けられます。これは条件を考える例で、上の画像にある通常投稿3件の設定とは別です。

開催日のメタキーと保存形式は、実際の投稿データに合わせます。ここでは、開催日をevent_dateへ20260909のような8桁の年月日で保存している場合を例にします。

「今日以降」にしたいときは、生成後に日付を差し替える

Builderの値欄へ20260909と入力すると、「2026年9月9日以降」という固定の条件になります。翌日に同じコードを使っても、基準日は9月9日のままです。毎日「今日以降」を取得したい場合は、Builderで条件の形を作った後、WordPress側でその日の値に差し替えます。

まず詳細設定で投稿タイプをカスタムのevent、公開状態をpublish、取得件数を6にします。並び順はmeta_value_num、昇順のASCを選び、自動高速化はオフにします。Meta Queryへ次の1条件を入力してください。この例では開催日で並べるためのmeta_keyも生成結果に補われます。

この入力から生成された、未編集の$argsが次のコードです。ここではまだ基準日が固定されています。

$args = array(    'post_type' => 'event',    'post_status' => 'publish',    'posts_per_page' => 6,    'order' => 'ASC',    'orderby' => 'meta_value_num',    'meta_query' => array(        array(            'key' => 'event_date',            'compare' => '>=',            'type' => 'NUMERIC',            'value' => 20260909        )    ),    'meta_key' => 'event_date');

次の1行はBuilderの出力ではなく、WordPressで使うために自分で追加する処理です。上の$argsの直後、new WP_Query($args)で取得を始める前に置きます。

$args['meta_query'][0]['value'] = (int) current_time('Ymd');

current_time(‘Ymd’)は、WordPressに設定したタイムゾーンで、その日の日付を8桁の年月日として取得します。(int)はその値を整数へ変換する指定です。[0]は「最初のMeta Query条件」を指すので、条件を増やしたり順番を変えたりした場合は、開催日の条件を差し替えているか確認してください。

これらはWordPressが読み込まれたPHPファイル内で使う断片です。新しいPHPファイルなら先頭に<?phpが必要ですが、すでにPHPの中なら開始タグを重ねません。固定ページの本文へ貼るコードではありません。表示ループや0件時の案内も含む設置例は、ACFの日付で今日以降のイベントを絞り込む方法で確認できます。

保存形式が2026-09-09やタイムスタンプの場合、この8桁の例をそのまま使うことはできません。また、ページをキャッシュしている場合はPHPが毎回実行されるとは限らないため、日付が変わった後にキャッシュも更新されるか確認しましょう。

画面の詳しい操作はWP Query Builderの公式チュートリアルにまとめています。初めて操作する方は、実際の画面に沿って進められるチュートリアルをご覧ください。

生成後は設置・差し替え・表示を確認する

コードをコピーしたら、設置場所・値・表示結果の3つを確認しましょう。ここを飛ばすと、正しい$argsでも「どこへ貼るのか分からない」「何も表示されない」という状態になりやすいです。

クラシックテーマで新着一覧のPHPパーツを追加するなら、子テーマへ保存し、表示したいテンプレートからget_template_part()で呼び出します。$argsだけを固定ページの本文へ貼っても、一覧は表示されません。functions.phpへ表示コードを丸ごと置く方法とも区別しましょう。

$argsから取得・ループ・リセットまでの形は、WP_Queryの基本構文と$argsの書き方で確認できます。結果が0件ならWP_Queryで投稿が表示されないときの確認順、件数だけが合わないならWP_Queryの表示件数が合わない原因へ進むと、生成条件とWordPress側の問題を分けて調べられます。

WP Query Builderにない取得条件を調べる公式資料

WP Query Builderの画面は、WordPress公式のWP_Queryパラメーターを使いやすい形に整理したものです。UIにない条件を足すときや、Tax / Meta / Date Queryの比較方法を深く確認するときは、生成コードだけで判断せず公式リファレンスへ戻ります。