WP_Query パラメーターterms

terms は、カテゴリー、タグ、カスタムタクソノミーなどの分類条件で使います。たとえば「カテゴリーが news の投稿」「タグが wordpress の投稿」「ジャンルが event の投稿」のように、分類の中の具体的な項目を指定します。

初心者がつまずきやすいのは、taxonomy と terms の違いです。taxonomy は分類の種類で、terms はその分類の中の具体的な項目です。カテゴリーでいえば、category が taxonomy、news が terms に入る値です。

terms は何を指定する項目か

terms は、tax_query の中で条件にするタームを指定する項目です。タームとは、カテゴリーやタグ、カスタムタクソノミーの中にある具体的な項目です。

たとえば、カテゴリーという分類の中に「ニュース」「お知らせ」「コラム」があります。この「ニュース」や「お知らせ」がタームです。WP_Query では、これらを terms に指定して絞り込みます。

ここで大事なのは、terms には分類名ではなく、分類の中の値を入れることです。category は taxonomy に入れる値であり、terms に入れる値ではありません。

terms に何を入れるかは、field によって変わります。field が slug ならスラッグ、term_id ならID、name ならターム名を指定します。

taxonomy、field、terms の関係

terms は、taxonomy と field とセットで読む必要があります。taxonomy はどの分類を見るか、field はタームを何で指定するか、terms は実際の条件値です。

この3つを分けて見ると、tax_query はかなり読みやすくなります。分類名、指定方法、具体的なタームを順番に確認します。

field と terms の種類がずれると、投稿が取得できない原因になります。field => ‘slug’ なのに terms にIDを入れる、field => ‘term_id’ なのにスラッグを入れる、といったミスに注意します。

また、terms は1つだけでも配列で書くことが多いです。後から複数タームへ広げやすくなり、条件の見た目もそろえやすくなります。

Builder での扱い

WP Query Builder では、terms は分類条件の具体的な値を入力・選択する項目として扱う想定です。初心者向けには、terms という英語だけを見せるより、「分類項目」「ターム」「カテゴリー項目」のように説明すると理解しやすくなります。

Builder では、先に taxonomy を選ばせ、その taxonomy に属するタームを terms として選ばせる流れが自然です。field がスラッグならスラッグ、IDならIDを内部的に渡します。

複数タームを選べるようにする場合は、operator の選択も必要です。「どれかに一致」なのか「すべて必要」なのかを選べるようにすると、生成されるクエリの意図がはっきりします。

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

tax_query で対象にするタームIDやスラッグなど、具体的な分類値を指定する時に使います。

field を確認せず数値と文字列を混ぜたり、タクソノミー自体の名前を terms へ渡したりしません。

単数・配列、存在しない値、削除済みタームで結果が変わるため、入力の正規化と空配列を処理します。

同じ値でも field が term_id なら数値、slug なら文字列として渡す必要があります。

指定した各タームのID・スラッグ・タクソノミーと投稿への付与を取得し、terms 配列と取得できた投稿IDを一対一で照合します。

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

field に合う terms の渡し方と、複数タームの operator を実装例で確認できます。

記事を読む →

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

公式資料では、WP_Query の Taxonomy Parameters と WP_Tax_Query のリファレンスで、terms、taxonomy、field、operator などの構造を確認できます。

terms は単独ではなく、taxonomy、field、operator と組み合わせて意味を持ちます。公式資料を見る時も、このまとまりで確認すると理解しやすくなります。

terms は、tax_query の中で条件にする具体的なタームを指定する項目です。taxonomy が分類の種類、field が指定方法、terms が具体的な値です。

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