WP_Query パラメーターsearch_columns

search_columns は、検索結果を細かく調整したい時に使う引数です。通常のキーワード検索では、タイトルや本文などが検索対象になりますが、実装によっては「タイトルだけ検索したい」「本文までは検索したくない」といった要件があります。

そのような時に、s と search_columns を組み合わせます。s が「何を探すか」を指定する引数で、search_columns が「どこから探すか」を指定する引数です。

search_columns は何を指定する引数か

search_columns は、WP_Query の検索で対象にする投稿カラムを指定する引数です。検索キーワードそのものを指定する引数ではありません。

たとえば、投稿タイトルだけを検索対象にしたい場合は、s に検索語を入れたうえで、search_columns に post_title を指定します。本文も対象にしたい場合は、post_content を含めます。

ここで大事なのは、search_columns は s と一緒に使う前提で考えることです。search_columns だけを指定しても、検索語がなければ何を検索するのかが決まりません。

また、search_columns は検索対象の範囲を調整するための引数です。検索結果の件数、投稿タイプ、公開状態、並び順を変えたい場合は、posts_per_page、post_type、post_status、orderby など別の引数も確認します。

s と search_columns の違い

search_columns と混同しやすいのが s です。s は検索キーワードを指定する引数です。search_columns は、そのキーワードをどのカラムから探すかを指定します。

この違いを分けておくと、検索クエリを読みやすくなります。s が検索語、search_columns が検索対象です。

たとえば「タイトルだけから WordPress を探す」なら、s に WordPress を入れ、search_columns に post_title を指定します。「タイトルと本文から探す」なら、post_title と post_content を指定します。

検索結果が多すぎる時に、s の値だけを変えても解決しないことがあります。その場合は、検索対象をどこまで広げるかも確認します。

Builder での扱い

WP Query Builder では、search_columns は検索条件の詳細設定として扱う想定です。初心者向けには、post_title などのカラム名だけで見せるより、「タイトル」「抜粋」「本文」のような表示にすると分かりやすくなります。

Builder では、まず検索語を入力する欄を s に対応させ、その後に「検索対象」を選ぶ項目として search_columns を用意する流れが自然です。

検索対象を複数選べるようにする場合は、最初は「タイトルのみ」など小さな範囲で確認するのがおすすめです。その後で、本文や抜粋を追加すると、検索結果がどう変わるかを追いやすくなります。

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

s の検索対象をタイトル、抜粋、本文の必要なカラムだけへ絞りたい時に使います。

検索語がない状態や、カスタムフィールドを検索対象へ加える目的では使いません。

WordPress 6.2以降という前提と、指定可能なカラム名を確認し、古い環境で同じ結果になると想定しません。

検索対象を狭めるほど意図しない一致は減りますが、本文にしかない語も見つからなくなる点を説明します。

同じ語をタイトルだけ・抜粋だけ・本文だけへ置き、各カラム指定で取得できた投稿IDを対応表にします。

実践記事で確認WP_Queryで投稿が表示されない時に見るチェックリスト

標準検索で投稿が出ない時に、検索語と対象範囲を順番に戻す確認方法を使えます。

記事を読む →

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

公式資料では、WP_Query の search_columns は Search Parameters の中で確認できます。検索キーワードを指定する s と合わせて見ると、検索条件の役割を理解しやすくなります。

search_columns で指定できる対象は限られているため、実装で迷った時は公式資料に戻って確認します。カスタムフィールドやタクソノミーまで検索したい場合は、search_columns だけで解決しようとせず、別の条件や実装方針も検討します。

search_columns は、WP_Query の検索で、タイトル、抜粋、本文のどこを検索対象にするかを指定する引数です。検索語を指定する s とは役割が違います。

迷った時は、まずタイトルだけを対象にした最小構成で確認します。期待した結果が出ることを確認してから、抜粋や本文へ検索対象を広げると、検索結果の変化を追いやすくなります。