WP_Queryのmeta_queryとは？カスタムフィールドで絞り込む方法

meta_queryは何のために指定するのか

WordPressの投稿には、タイトルや本文、公開日、カテゴリーのような基本情報があります。それとは別に、投稿ごとに追加情報を保存できる仕組みがカスタムフィールドです。商品価格、イベント日、難易度、表示フラグ、外部URLなど、サイトごとに自由な情報を持たせたいときに使われます。

meta_queryは、投稿に紐づいたカスタムフィールドの値を見て「どの投稿を取得するか」を決めるWP_Query引数です。投稿本文や画面上のラベルではなく、保存されたmeta keyと値を比較します。

meta_queryを使う場面

ACFの日付フィールドを扱う場合や、条件を書いても結果が合わない場合は、画面上の表示ではなく、まず保存値から確認します。

あわせて読みたいACFの日付絞り込み記事を読む

あわせて読みたいmeta_queryのチェックリスト記事を読む

ACFはカスタムフィールドを管理しやすくするプラグインですが、WP_Queryが比較するのは画面上の表示ではなく、データベースに保存されたpost metaです。ACFとWordPress標準のカスタムフィールドの関係は、基礎記事が公開された後に次の案内から確認できます。

meta_queryは、カテゴリーやタグでは表現しにくい条件で投稿を選びたいときに使います。「価格」「点数」「開催日」「在庫状態」「チェックボックスのON/OFF」のような投稿ごとの値が代表例です。

一方で、何でも meta_query にすればよいわけではありません。分類として管理したい情報はタクソノミー、投稿ごとに違う値を持つ情報はカスタムフィールド、と考えると判断しやすくなります。たとえば「商品ジャンル」はタクソノミー向きですが、「価格」はカスタムフィールド向きです。

カテゴリー、タグ、カスタムタクソノミーで選ぶ要件なら、tax_queryの基本を使います。どちらを選ぶか迷ったら、同じ値を複数投稿の分類として管理したいのか、投稿ごとに固有の値を保存したいのかで判断します。

分類なのか投稿ごとの値なのかを先に決めると、tax_queryとmeta_queryを選び分けられます。

meta_queryの基本構造

meta_query は、WP_Queryに渡す $args の中に書きます。基本形は、meta_query というキーの中に、さらに条件の配列を入れる形です。条件が1つだけでも、内側に配列を入れる構造になる点が初心者には少し分かりにくいところです。

$args、new WP_Query()、ループの位置関係がまだ曖昧な場合は、先にWP_Queryの基本構文で全体の形を確認してください。この記事では、その$argsへmeta_queryを加える部分に絞ります。

公式リファレンスでも、meta_query は「配列の中に条件配列を入れる」形で説明されています。これは複数のカスタムフィールド条件を扱えるようにするためです。最初は少し入れ子が多く見えますが、key、value、compare、type の4つを順番に読むと理解しやすくなります。

おすすめフラグが付いた投稿だけ取得する例

次の例は、チェックをONにすると文字列1が保存される設計を前提に、カスタムフィールドis_featuredの値が1の投稿だけを取得します。実際の保存値がtrue、配列、空文字などの場合は、その値に合わせて条件を変えてください。

$args = [   'post_type'      => 'post',   'posts_per_page' => 5,   'meta_query'     => [      [         'key'     => 'is_featured',         'value'   => '1',         'compare' => '=',      ],   ],]; $featured_posts = new WP_Query( $args ); if ( $featured_posts->have_posts() ) {   echo '<ul>';    while ( $featured_posts->have_posts() ) {      $featured_posts->the_post();       echo '<li><a href="' . esc_url( get_permalink() ) . '">';      echo esc_html( get_the_title() );      echo '</a></li>';   }    echo '</ul>';} wp_reset_postdata();

このコードの読みどころは、meta_query の中にさらに1つの条件配列が入っている点です。key はカスタムフィールド名、value は比較したい値、compare は比較方法です。この例では「is_featured が 1 と等しい投稿」を取得しています。

もうひとつ大切なのは、最後にwp_reset_postdata()を入れていることです。WP_Queryでthe_post()を使った場合は、ループ後にメインクエリの現在の投稿データへ戻し、後続のテンプレートタグが別投稿を参照するのを防ぎます。

key・value・compare・typeの意味

meta_query を読むときは、いきなり全体を見ようとせず、各キーの意味を分けて見ると理解しやすくなります。特に compare と type は、最初のうちは省略されることもありますが、数値や日付で絞り込むときに重要になります。

key は対象にするカスタムフィールド名です。value は比較したい値です。compare は「等しい」「以上」「含む」「範囲内」などの比較方法です。type は、値を文字列として見るのか、数値として見るのか、日付として見るのかを指定するために使います。

compareを省略した場合は基本的に=、typeを省略した場合はCHARとして扱われます。価格が入っているカスタムフィールドを数値として比較するなら、valueだけでなくtypeも確認してください。

数値で絞り込むときはtypeに注意する

meta_query で特につまずきやすいのが数値比較です。カスタムフィールドの値は保存上は文字列として扱われることが多く、価格や点数のような値でも、そのまま比較すると意図しない結果になることがあります。

たとえば「価格が1000以下の商品」を取得したい場合、compare に <= を指定するだけでなく、type に NUMERIC を指定した方が意図が明確になります。これは、WordPressに「この値は数値として比較したい」と伝えるためです。

$args = [   'post_type'      => 'product',   'posts_per_page' => 10,   'meta_query'     => [      [         'key'     => 'price',         'value'   => 1000,         'compare' => '<=',         'type'    => 'NUMERIC',      ],   ],]; $product_query = new WP_Query( $args );

このコードの読みどころは、compare と type を分けて指定している点です。compare は「1000以下」という比較方法を表し、type は price の値を数値として扱うことを表します。数値条件で期待どおりに絞り込めないときは、まず type が適切かを確認してください。

この例は、単位や桁区切りを含まない整数をpriceへ保存する設計が前提です。1,000円のような表示文字列を保存値へ混ぜないでください。小数を正確に扱う必要がある場合は、実際の保存形式を確認したうえでDECIMALを検討します。

複数条件ではrelationを使う

meta_query は、複数のカスタムフィールド条件を組み合わせることもできます。そのときに使うのが relation です。relation には主に AND または OR を指定します。

ANDはすべての条件を満たす投稿、ORはどれか1つの条件を満たす投稿を取得します。複数条件の既定もANDですが、この例では条件同士の関係を読み取れるように明示します。条件が1つだけならrelationは不要です。

おすすめ、かつ価格が1000以下の商品を取得する例

次のコードは、is_featured が 1 で、さらに price が1000以下の商品を取得する例です。両方を満たす必要があるため、relation は AND です。

$args = [   'post_type'      => 'product',   'posts_per_page' => 10,   'meta_query'     => [      'relation' => 'AND',      [         'key'     => 'is_featured',         'value'   => '1',         'compare' => '=',      ],      [         'key'     => 'price',         'value'   => 1000,         'compare' => '<=',         'type'    => 'NUMERIC',      ],   ],]; $product_query = new WP_Query( $args );

このコードの読みどころは、meta_query の先頭付近に relation があり、その下に条件配列が複数並んでいる点です。relation は条件そのものではなく、条件同士をどう結ぶかを示す指定です。

relationは複数条件をまとめる外側の配列に置きます。単一条件では不要で、各clauseの内側には入れません。

compareでよく使う比較方法

compareは、値をどう判定するかを指定します。まず頻出する値とvalueの形式を確認します。

もっとも基本になるのは = です。これは値が一致する投稿を取得します。数値では >、>=、<、<= を使うことがあります。複数の候補に含まれるかを見たい場合は IN、範囲内かを見たい場合は BETWEEN が使われます。

!=だけでは、対象キーが未保存の投稿まで自動では含みません。未保存も含めたい要件では、NOT EXISTSとのOR条件が必要になる場合があります。また、EXISTSは「値が空ではない」ではなく、メタキーの行が存在するかを見る条件です。

LIKEやNOT LIKEもありますが、保存形式を確認せずに使うと意図しない投稿まで拾うことがあります。完全一致や数値比較で要件を表せないかを先に確認してください。

meta_key / meta_value と meta_query の違い

WP_Queryには、meta_queryのほかにmeta_key、meta_value、meta_compareという指定もあります。これは単一条件を$args直下へ書く別形式です。meta_keyは、カスタムフィールド値で並べ替える場合にも使います。

ただし、条件が複数になる場合や、key、value、compare、type を見通しよく整理したい場合は、meta_query の形で書いた方が分かりやすくなります。実務では、あとから条件が増えることも多いため、最初から meta_query に慣れておくと拡張しやすいです。

meta_queryでよくあるつまずき

meta_queryで期待した投稿が出ないときは、コード全体を書き換える前に、次の4点を実データと照合します。

確認する順番は、カスタムフィールド名、保存されている値、比較方法、値の型です。 画面上のラベルや表示形式ではなく、実際のmeta keyと保存値を基準にしてください。

特に多いのは、カスタムフィールド名の打ち間違い、値の保存形式の勘違い、数値比較なのに type を指定していないケースです。また、チェックボックスや真偽値のようなフィールドは、プラグインや実装方法によって保存される値が 1、0、空文字、配列など異なる場合があります。

複数条件のままでは、どのclauseが原因か分かりにくくなります。1つのmeta_queryで投稿が取れるか確認し、その後でrelationや別条件を追加してください。

meta_query以外も含めて投稿が0件になる原因を切り分けたい場合は、WP_Queryで投稿が表示されないときの確認順に沿って最小構成へ戻します。

公式資料で確認したいポイント

meta_queryは使える比較方法や型が多いため、暗記ではなく公式資料で必要な指定を確認します。特にcompareとtypeは、値の保存形式と合わせて判断してください。

公式のWP_Queryリファレンスでは、Custom Field Parametersとして meta_key、meta_value、meta_compare、meta_query が説明されています。また、meta_query の処理は WP_Meta_Query によって解析されるため、より細かく確認したい場合は WP_Meta_Query の公式リファレンスも見ると理解しやすくなります。

meta_queryは小さな条件から試すと理解しやすい

meta_queryでは、入れ子の配列、比較方法、値の型を分けて確認します。最初から複数条件を入れると、どのclauseで投稿が外れたか追いにくくなります。

「このカスタムフィールドが、この値と一致する投稿を取る」という最小例から始めます。そのうえで、数値比較ならtype、複数条件ならrelation、キーの存在を見るならEXISTS / NOT EXISTSを必要に応じて足すと、結果が変わった理由を追えます。