WP_Query パラメーターs

s は、WordPress の検索に関係する基本的な引数です。通常の検索結果ページだけでなく、独自の検索フォームや、特定の投稿タイプだけを対象にした検索一覧を作る時にも使います。

ただし、s は「何を探すか」を指定する引数です。どの投稿タイプを対象にするか、公開済みだけにするか、タイトルだけを検索するか、といった条件は別の引数と組み合わせて指定します。

s は何を指定する引数か

s は、WP_Query の検索キーワードを指定する引数です。ユーザーが検索フォームに入力した語句や、コード側で指定した語句をもとに投稿を検索します。

たとえば、s に WordPress を指定すると、WordPress という語句に一致する投稿を探します。検索対象は通常、投稿タイトルや本文などですが、必要に応じて search_columns で対象カラムを調整します。

ここで大事なのは、s は検索語そのものを入れる場所だということです。検索対象をタイトルだけにする、本文も含める、特定の投稿タイプだけにする、といった調整は別の引数で行います。

そのため、検索結果がおかしい時は s だけを見ても原因が分からないことがあります。検索語、検索対象、投稿タイプ、公開状態を順番に確認します。

s と search_columns の違い

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

つまり、s が「何を探すか」、search_columns が「どこから探すか」です。この2つを分けて考えると、検索クエリの意味が分かりやすくなります。

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

検索結果が多すぎる時は、検索語を変えるだけでなく、検索対象を狭めることも検討します。逆に、検索結果が少なすぎる時は、本文や抜粋も検索対象に含めるか確認します。

Builder での扱い

WP Query Builder では、s は検索語入力欄として扱う想定です。初心者向けには、s という引数名だけを見せるより、「検索キーワード」と表示したほうが分かりやすくなります。

検索機能を作る場合は、s だけでなく、検索対象の投稿タイプ、公開状態、検索対象カラムも一緒に設定できると実務に近くなります。

また、検索フォームと組み合わせる場合は、ユーザーが入力した値をそのまま固定文字列として扱うのではなく、入力値を受け取って s に渡す流れになります。実装時は、入力値の扱いと出力時のエスケープも別途確認します。

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

タイトル・抜粋・本文などWordPress標準検索の対象からキーワード一致する投稿を探す時に使います。

カスタムフィールドやタクソノミーまで同じ検索語で探せると仮定したり、未加工の外部入力をそのまま渡したりしません。

語句、記号、除外語、プラグインのフィルターで結果が変わるため、検索語と対象カラムを記録します。

標準検索が見る範囲と、利用者が期待するサイト内検索の範囲は同じとは限りません。

タイトル・抜粋・本文の各所だけに語を置いた投稿を用意し、検索語、取得できた投稿ID、SQLの検索条件を比較します。

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

検索条件を追加して0件になった時に、語句とほかの $args を最小構成から切り分けられます。

記事を読む →

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

公式資料では、WP_Query の s は Search Parameters の中で確認できます。検索対象カラムを調整する search_columns も、検索に関係する引数として一緒に確認します。

また、検索結果ページで現在の検索語を取得して表示したい場合は、get_search_query() の公式リファレンスも確認します。これは WP_Query の引数そのものではありませんが、検索語を画面に出す時に関係します。

s は、WP_Query で検索キーワードを指定するための引数です。検索語そのものを指定する引数であり、検索対象カラムや投稿タイプまで決める引数ではありません。

迷った時は、まず post_type、post_status、posts_per_page、s だけの最小構成で確認します。期待した結果が出ることを確認してから、search_columns や分類条件を追加すると、原因を切り分けやすくなります。