WP Query Builderの入力項目とWP_Queryパラメーターの対応表
｜目的から探せる

最初は、やりたいことから入力欄を探す

WP_Queryを使い始めたばかりなら、「何の記事を出すか」「どう絞るか」「何件出すか」から、近い行を探してみましょう。 そこで入力欄を見つけてから、post_typeやtax_queryというコード側の名前と見比べると、役割もつかみやすくなります。

たとえば「WordPressで特定カテゴリーの記事だけ出したい」と調べ、解説でcategory__inやtax_queryを知ったら、この表からWP Query Builderの入力場所を確認します。逆にWP Query Builderで見慣れない項目を見つけたときは、生成コードに出たパラメーター名をWordPress公式資料で確認します。

入力した値がコードへ入る形を知る

画面には読みやすい日本語のラベルが付いていますが、コードではWordPressが受け取るパラメーター名を使います。たとえば「取得件数」とposts_per_pageは、同じ設定を画面とコードで別の名前で表しています。

違いは名前だけではありません。1つの欄に入れた「10,11」が数値の配列になったり、分類名・比較方法・値という複数の欄が、1つのtax_queryにまとめられたりします。次の表では、入力を変えたときにコードのどこが変わるかを整理しています。

シンプル設定と詳細設定は、同じクエリの入力欄を切り替えています。 シンプル設定のカテゴリーはcategory__in、タグはtag_slug__in、検索キーワードはsへ同期され、詳細設定へ切り替えても同じ条件が生成コードに残ります。

基本設定と検索の対応

まずは、何を何件取得するかと、キーワード検索の設定です。左列の日本語ラベルを画面で探し、中央列のパラメーターが生成コードへ入ることを確認します。シンプル設定にあるカテゴリーとタグの欄も、ここで対応を確認できます。

基本の3項目は、そのまま3つのパラメーターになる

「投稿タイプ」をpost、「公開状態」をpublish、「取得件数」を3にした例です。対応を見やすくするため、自動高速化はオフにしています。以下の4例は、公開中のWP Query Builderから取得した未編集の生成コードです。

$args = array(    'post_type' => 'post',    'post_status' => 'publish',    'posts_per_page' => 3);

画面の3つの入力が、同じ順で3つの行になっています。posts_per_page=3だけでは先頭固定の優先を無効にしないため、先頭固定の記事があるサイトでは、その扱いも別に確認します。

この$argsだけでは記事は表示されません。 子テーマのテンプレートパーツなどで、new WP_Query( $args )へ渡す直前に置く取得条件です。記事を出すループ、HTML、wp_reset_postdata()、呼び出し元は別に必要です。既存の$argsへ例を継ぎ足さず、試す例に置き換えて使います。設置場所と表示処理は、次の手順で確認できます。

あわせて読みたい生成コードを安全に貼る方法記事を読む

生成した取得条件は、本番と分けたWordPress環境で、表示処理と組み合わせて試します。検証や公開に使うサーバーをこれから用意する場合は、XserverのPHP対応やバックアップ条件も確認できます。

ページング・並び順・ショートカットの対応

よく使う絞り込みは入力欄が直接用意されています。投稿者、カテゴリー、タグ、単体取得は、1つの値欄を共有し、選んだモードによって生成されるパラメーター名と値の型が変わります。

ページング・並び順・投稿指定

ページ番号、読み飛ばす件数、並び順、特定の記事の指定は、それぞれ別の条件です。たとえば「2ページ目を取得する」と「先頭から2件飛ばす」は同じではないため、目的に合う欄を選びます。

orderby=post__in、post_name__in、post_parent__inを選ぶ場合は、対応する指定欄が必要です。orderby=meta_valueまたはmeta_value_numでは、Meta Queryの最初のkeyをmeta_keyとして補います。使えるkeyがなければ、WP Query Builderはコード生成を止めます。

モードでパラメーター名が変わる入力

投稿者やカテゴリーは、先に「IDで指定する」「スラッグで指定する」「複数を除外する」などの方法を選び、その下の値欄へ入力します。見た目が同じ値欄でも、選択した方法によって受け付ける値が変わります。

モードを使う入力では、欄の見た目が同じでも、選んだ指定方法によって値の意味が変わります。 category_nameはカテゴリースラッグ、author_nameは表示名ではなくuser_nicename、titleは部分一致ではなく完全一致です。パラメーター名だけでなく、入力する値の種類も確認してください。

カテゴリーIDを2つ入れると、整数の配列になる

基本の3項目はそのままに、「カテゴリーの指定方法」をcategory__inへ切り替え、「カテゴリーの値」に10,11を入れます。10と11は説明用のIDなので、自分のサイトのカテゴリーIDへ置き換えてください。

生成コードでは、入力した2つのIDがcategory__inの配列へ入ります。

$args = array(    'post_type' => 'post',    'post_status' => 'publish',    'posts_per_page' => 3,    'category__in' => array(    10,    11));

入力した10,11は1つの文字列ではなく、2つの整数を持つ配列になりました。この指定はカテゴリー10または11に属する記事が対象です。両方に属する記事だけを探すcategory__andとは区別します。

カテゴリーの入力が配列になるところまで分かったら、WP Query Builderを横に開いて、自分のサイトのIDで照合してみましょう。指定方法を1つ変え、生成コードの名前と値を見比べます。

パスワード・権限・添付ファイルの対応

公開状態だけでは決められない条件や、添付ファイルを取得する条件はこちらです。非公開の情報を扱うときは、ログイン状態や権限によって結果が変わることも検証してください。

Tax・Meta・Date Queryは配列へまとめられる

Tax Query、Meta Query、Date Queryでは、入力した条件ブロックを配列へまとめます。条件を2件以上追加したときだけrelationが表示され、ANDまたはORでつなぎます。

Tax Query：分類名・値・比較方法を1つの条件にする

Tax Queryは、カテゴリーやタグ、カスタムタクソノミーで絞り込む設定です。次の各項目はtax_query内の1条件に入り、条件を追加したときだけ「条件のつなぎ方」でANDまたはORを選びます。

Meta Query：保存したキー・値・型を組み合わせる

Meta Queryでは、管理画面上の表示名ではなく、保存されているメタキーと値を指定します。条件ブロックの詳細項目では、キー自体の比較方法と型も指定できます。

数値の比較では、入力欄の見た目が文字でも、生成コードの値は数値になる場合があります。今回のtype=NUMERICの検証では、20260901や60000が引用符なしの数値として生成されました。保存形式に合う型を選び、生成後の値も確認しましょう。

開催日で絞り、同じメタキーで並べる例

投稿タイプworksに、開催日をevent_dateというメタキーで20260901のような8桁の数字として保存している想定です。投稿タイプとメタキーは事前にサイト側で用意します。Meta Queryへ次の条件を入れ、並べ替えの基準をmeta_value_num、並び方向をASCにします。

この入力を生成すると、絞り込み用のmeta_queryと、並べ替えに使う指定が次のようにまとまります。

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

4つの入力はmeta_query内の1条件へまとまりました。さらに、数値順で並べるためのmeta_keyが、最初の条件のkeyから自動で補われています。取得できるかどうかは、worksの登録と実際の保存値次第です。ここでは入力と出力の対応を示しており、サンプルの投稿が自動で作られるわけではありません。

Date Query：投稿日・更新日を絞り込む

Date Queryが調べるのは投稿日や更新日時で、カスタムフィールドの開催日ではありません。 開催日のメタ値を使う場合は、前のMeta Queryで条件を作ります。

「Date条件の組み方」で直接指定の欄を表示すると、次のパラメーターを$argsの直下へ入れられます。複合条件と名前が少し違う月・週に注意してください。

Dateでは、$args直下の月・週がmonthnum・wなのに対し、date_query内の各条件ではmonth・weekです。「Date条件の組み方」は見せ方だけの切り替えではありません。top-level だけ使うへ変えると、入力済みのdate_queryは生成コードから外れ、両方を表示するへ戻すと再び入ります。切り替えた後は、必要な日付条件がコードに残っているか確認しましょう。

9月の投稿日を、開始日と終了日で指定する例

基本の3項目から始め、Date Queryの開始日へ2026-09-01、終了日へ2026-09-30を入れます。「境界日を含める」はtrue、対象の日付は既定のpost_dateです。

生成されたdate_queryには、開始日・終了日と、境界日を含める指定が入っています。

$args = array(    'post_type' => 'post',    'post_status' => 'publish',    'posts_per_page' => 3,    'date_query' => array(        array(            'after' => '2026-09-01',            'before' => '2026-09-30',            'inclusive' => true        )    ));

日付の3項目がdate_queryの1条件へ入りました。既定のcolumn=post_dateはこの生成コードでは省略されています。投稿日と更新日、サイトの時刻とGMTのどれを使うかも、対象の日付欄で合わせて確認します。

性能設定と補助機能をパラメーターと混同しない

「取得結果・高速化」の個別欄はWP_Queryのパラメーターへ対応します。一方、「高速化プリセット」と「自動高速化」は複数の項目をまとめて設定する補助機能です。どちらを使っても、生成された各行を確認します。

自動高速化が有効でposts_per_pageが1以上の場合、未指定のno_found_rowsとignore_sticky_postsをtrue、update_post_meta_cache・update_post_term_cache・lazy_load_term_metaをfalseで補います。手動で選んだ値は上書きしません。全件取得の-1では、この補完を行わないことも公開画面で確認しました。

自動高速化では先頭固定の優先や総件数の計算も変わります。数字のページ送りが必要なら、no_found_rowsをfalseへ変更してください。 一覧でメタ情報やカテゴリー情報を使う場合も、先読みの設定を用途に合わせて見直しましょう。

高速化プリセットは、次の組み合わせを入力欄へ反映します。プリセット名そのものが$argsへ入るわけではありません。

WP_Queryパラメーターを直接作らない画面項目

画面の操作が、すべて同じ名前のパラメーターになるわけではありません。説明を開く操作やコードのコピーは取得条件を変えず、プリセットは複数の入力欄をまとめて変えます。生成コードに操作名を探す必要はありません。

対応していることと、未対応を見分ける

この記事はWordPress公式にある全パラメーターの辞典ではなく、公開中のWP Query Builderの入力と生成コードの対応表です。画面の入力欄と選択肢を確認した上で、指定方法を切り替えてコードを生成し、パラメーター名と値の形を照合しています。

「WP Query Builderで選べる」と「WordPressで正しい結果になる」は別です。投稿タイプ、タクソノミー、カスタムフィールド、保存値、権限、他のフックはサイトごとに違います。生成できたコードも、ローカルまたはステージングで実データを使って確認します。

生成する範囲と、表示HTMLや実データなどWordPress側で用意するものを分けて確認したい場合は、次の記事へ進めます。

あわせて読みたいWP Query Builderのできること・できないこと記事を読む

WP_Queryのパラメーターと値の型を確認する公式資料

WP Query Builderはパラメーターを組み立てやすくする入口です。パラメーターの既定値、使える値、WordPress版による違い、複雑な配列の仕様は、WordPress公式資料で確認します。

入力項目とパラメーターの対応が分かったら、生成コードを安全に設置する手順も確認しておきましょう。

あわせて読みたい生成コードを安全に貼るためのチェックリスト記事を読む

入力項目とWP_Queryパラメーターのよくある質問

ここまでの内容で迷いやすい点を、質問と回答に分けて整理します。