WP_Query パラメーターtax_query

tax_query を使うと、「カテゴリーがニュースの記事」「タグが WordPress の記事」「カスタムタクソノミーのジャンルがイベントの記事」のように、分類を条件にして投稿を絞り込めます。

初心者がつまずきやすいのは、tax_query の中にさらに配列を書く点です。taxonomy、field、terms、operator など複数の項目が出てくるため、最初はそれぞれの役割を分けて見ることが大切です。

tax_query は何を指定する引数か

tax_query は、タクソノミーとタームを使って投稿を絞り込むための WP_Query 引数です。WordPress では、カテゴリーやタグもタクソノミーとして扱われます。

カスタム投稿タイプと一緒に使われるカスタムタクソノミーも、tax_query の対象になります。たとえば、イベント投稿タイプに「開催地域」や「イベント種別」のような分類を付けている場合、その分類で一覧を絞り込む時に使います。

ここで大事なのは、taxonomy は分類の種類、terms はその中の具体的な項目だということです。カテゴリーで絞るなら taxonomy は category、タグで絞るなら post_tag、独自分類ならその登録名を指定します。

field は、terms に入れた値をどう解釈するかを決めます。terms にスラッグを入れるなら field は slug、タームIDを入れるなら field は term_id にします。

taxonomy、field、terms の考え方

tax_query では、taxonomy、field、terms の3つをまず理解すると書きやすくなります。この3つで「どの分類の、どの値を見るか」が決まります。

taxonomy は分類の名前です。カテゴリーなら category、タグなら post_tag、カスタムタクソノミーなら登録されたタクソノミー名を指定します。

field は、terms の値をスラッグとして扱うのか、IDとして扱うのかを決めます。人間が読みやすいコードにしたい場合は slug が分かりやすいことがありますが、IDで管理したい場合は term_id を使います。

terms は配列で書くことが多いです。1つだけでも配列にしておくと、後から複数条件へ広げやすくなります。

Builder での扱い

WP Query Builder では、tax_query は分類条件のグループとして扱う想定です。初心者向けには、いきなり配列を見せるより、「分類の種類」「指定方法」「ターム」「含む / 含まない」「条件のつなぎ方」に分けて入力できると理解しやすくなります。

たとえば、画面上では「タクソノミー: カテゴリー」「指定方法: スラッグ」「ターム: news」「条件: 含む」のように選ばせ、内部で tax_query の配列へ変換する形です。

複数条件を扱う場合は、relation の説明が重要です。「すべて満たす」と「どれかを満たす」を言葉で選ばせ、それを AND / OR に対応させると分かりやすくなります。

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

カテゴリー、タグ、カスタムタクソノミーを複数条件や除外を含めて絞り込む時に使います。

カスタムフィールド値や投稿日を条件にする用途へ流用せず、単純な1カテゴリーなら短縮引数も検討します。

taxonomy・field・terms・operator・relation の役割が一つでもずれると、0件または広すぎる結果になります。

カテゴリー名で探すのかタームIDで探すのかを先に決めると、field と terms の取り違えを防げます。

ターム付与状態が異なる投稿を用意し、条件を一つずつ追加して期待する投稿IDと実際の投稿IDを集合で比較します。

実践記事で確認tax_queryでカテゴリー・タグ・タクソノミーを絞り込む

tax_query を最小条件から組み、AND・ORや除外へ広げる実践例を確認できます。

記事を読む →

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

公式資料では、WP_Query の tax_query は Taxonomy Parameters の中で確認できます。taxonomy、field、terms、operator、relation などの構造を確認したい時は、WP_Query と WP_Tax_Query の公式リファレンスを合わせて見ます。

カスタムタクソノミーの登録名や設定を確認したい場合は、register_taxonomy() の公式リファレンスも確認します。tax_query は登録済みのタクソノミーを条件に使うため、登録名を間違えると取得できません。

tax_query は、カテゴリー、タグ、カスタムタクソノミーなどの分類で投稿を絞り込むための引数です。分類条件を扱う時は、taxonomy、field、terms、operator、relation の役割を分けて確認します。

迷った時は、まず1つのタクソノミーと1つのタームだけで最小構成を作ります。取得できることを確認してから、複数ターム、複数タクソノミー、AND / OR 条件へ広げると安全です。