WP_Query パラメーターmeta_key

meta_key は、カスタムフィールドに関係する WP_Query の基本引数です。たとえば、price というメタキーに保存された価格で並べたい場合、どのメタキーを見るのかを meta_key で指定します。

初心者が迷いやすいのは、meta_key と meta_query の違いです。meta_key は「どのメタキーを見るか」を指定する引数です。一方、meta_query は「メタキーの値が何であるか」「いくら以上か」など、複数条件を含めた絞り込みを作るための引数です。

meta_key は何を指定する引数か

meta_key は、投稿メタ、つまりカスタムフィールドのキー名を指定するための WP_Query 引数です。WordPress の投稿には、タイトルや本文とは別に、任意のキーと値を保存できます。

たとえば、価格を保存する price、おすすめフラグを保存する featured、イベント日を保存する event_date のようなメタキーがある場合、そのキー名を meta_key に指定します。

ここで大事なのは、meta_key に入れるのは表示ラベルではなく、実際のメタキー名だということです。管理画面では「価格」と表示されていても、保存されているキー名が price なら、コードでは price を使います。

ACF などでフィールドを作っている場合も、画面上のラベルとフィールド名が違うことがあります。WP_Query に指定するのは、実際に保存されるフィールド名またはメタキー名です。

meta_key と meta_query の違い

meta_key と混同しやすいのが meta_query です。meta_key は、対象にするメタキー名を指定する引数です。meta_query は、カスタムフィールドの値で絞り込み条件を作るための引数です。

たとえば「score の数値が大きい順に並べる」なら、meta_key と orderby の組み合わせが重要になります。一方、「score が80以上の投稿だけ取得する」なら、meta_query を検討します。

meta_key だけを書いても、複雑な条件を表現できるわけではありません。特定の値と一致する、数値が以上、値が存在する、複数条件を組み合わせる、といった場合は meta_query のほうが向いています。

反対に、値で絞り込むのではなく、値を基準に並び替えたいだけなら、meta_key と orderby の組み合わせで整理できます。

Builder での扱い

WP Query Builder では、meta_key はカスタムフィールド関連の補助項目として扱う想定です。特に、カスタムフィールド値で並び替える時に、orderby と一緒に入力させると分かりやすくなります。

たとえば Builder では、「並び替えの基準: カスタムフィールドの数値」「メタキー: price」「並び順: 小さい順」のように見せ、内部で meta_key => ‘price’、orderby => ‘meta_value_num’、order => ‘ASC’ に変換します。

絞り込み条件として使う場合は、meta_query の入力欄の中で key として扱うほうが自然です。並び替え条件として使う場合は、meta_key と orderby をセットで扱います。

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

どのカスタムフィールドを絞り込み・並び替えの対象にするか、保存キーを指定する時に使います。

管理画面に見えるフィールドラベルを、そのままメタキーだと推測して指定しません。

表記ゆれや先頭アンダースコアを含む別キーが存在するため、対象投稿に保存された実キーを確認します。

ラベルが「価格」でも保存キーが price とは限らないため、実投稿に保存されたキーを正本として扱います。

対象・未設定・似たキーを持つ投稿で get_post_meta() のキー一覧と生値を取り、取得できた投稿IDと照合します。

実践記事で確認meta_queryでカスタムフィールドを絞り込む

実際の保存キーを meta_query の条件へ置く流れと、未設定値の扱いを確認できます。

記事を読む →

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

公式資料では、WP_Query の Custom Field Parameters の中で meta_key や meta_value、meta_query などを確認できます。カスタムフィールド関連の引数は、まとめて見ると役割を理解しやすくなります。

また、投稿に保存されているメタ値を確認したい場合は、get_post_meta() の公式リファレンスも役に立ちます。meta_key が効かない時は、まず保存されているキーと値を確認します。

meta_key は、WP_Query で対象にするカスタムフィールドのキー名を指定する引数です。カスタムフィールド値で並び替える時は、orderby と order も一緒に確認します。

値で絞り込みたい場合は、meta_key だけでなく meta_query を検討します。迷った時は、「並び替えたいのか」「絞り込みたいのか」を先に分けると整理しやすくなります。