WP_Queryガイド｜やりたいこと・困りごと・Builderから探す

目的から1本選べば始められます

WP_Queryは、パラメーターを順に覚えるより、作りたい一覧や困っている症状に合う記事から始めてみましょう。

まず「関連記事などの一覧を足したい」「今ある一覧ページを変えたい」「表示がおかしい」のどれに近いかを考えてみてください。エディターの設定だけで実現できるならQuery Loopが候補になります。PHPで一覧を追加するならWP_Queryを使い、取得条件を作るときにWP Query Builderを利用できます。実装は検証環境で試し、本番へ反映する前に戻し方も確認しましょう。

今の目的から入口を選ぶ

最初から、どの機能やパラメーターを組み合わせるかまで考えなくても大丈夫です。「関連記事を載せたい」「2ページ目が表示されない」など、今の目的に近い入口を1つ選びましょう。表の「次に進む場所」から、このページ内の案内へ移動できます。

今の状況	最初に確認すること	次に進む場所
WP_Queryが何か分からない	役割と通常のループとの違い	基礎記事
投稿一覧を自分で作りたい	取得条件と最小構文	基本構文またはBuilder
カテゴリーやカスタムフィールドで絞りたい	保存値と絞り込み条件	用途別の実装記事
投稿が出ない・件数や順番が合わない	条件を減らして症状を切り分ける	トラブル記事
カテゴリーや検索など既存の一覧を変えたい	メインクエリか追加一覧かを判断する	pre_get_postsの判断記事
本番を壊さず試したい	検証環境、設置場所、戻し方を確認する	安全実装の記事
表示が重い	推測せず取得量とクエリを計測する	性能記事

「そもそもWP_Queryが必要？」と迷ったら、まず使い分けを確認しましょう。記事の下に関連記事を足す場合と、カテゴリー一覧そのものを変える場合では、使う方法が違います。

方法選びに迷ったらWP_Queryを使う場面と、ほかの方法で十分な場面

WP_Query、get_posts()、pre_get_posts、Query Loopの4つを、作りたい一覧に合わせて選べます。

記事を読む

仕組みと最小構文から理解する

初めてWP_Queryを見る場合は、クラスの全パラメーターを読む必要はありません。まず「条件を作る」「投稿を取得する」「ループで表示する」「投稿データを戻す」という流れを押さえます。

役割がまだ曖昧ならWP_Queryの基礎から、すでに投稿一覧を作りたい目的が決まっているなら基本構文から始めてください。取得対象が投稿、固定ページ、カスタム投稿のどれかで迷う場合は、post_typeの解説もご覧ください。

まず役割を知りたいWP_Queryとは？

投稿を取得する仕組みと、WordPressが用意する通常のループとの関係を確認できます。

記事を読む最小コードを書きたいWP_Queryの基本構文と$argsの書き方

条件の配列から投稿取得、ループでの表示までの基本形を確認できます。

記事を読む取得する投稿の種類を決めたいWP_Queryのpost_type指定方法

通常の投稿、固定ページ、カスタム投稿を取得するときの指定方法を確認できます。

記事を読むループ後の処理を理解したいwp_reset_postdata()が必要な理由

関連記事などのループを終えた後に、表示中の投稿データを戻す理由を確認できます。

記事を読む

ここで大切なのは、WP_Queryが見た目を作る仕組みではないことです。WP_Queryは表示対象を選び、テンプレートやブロックがタイトル、画像、抜粋などの見た目を作ります。

やりたい投稿一覧から条件を選ぶ

基本構文を理解したら、作りたい一覧に必要な条件だけを足します。「何を取得するか」「どう絞るか」「どう並べるか」「何件表示するか」に分けると、複雑な$argsも整理しやすくなります。

カテゴリーやタグならtax_query、カスタムフィールドならmeta_query、並び順ならorderbyとorderが主な確認先です。複数の条件を一度に追加せず、1条件ずつ結果を確認すると原因を追いやすくなります。

カテゴリーやタグで絞りたいtax_queryの使い方

複数の分類条件を組み合わせたり、独自のタクソノミーで絞ったりする方法を確認できます。

記事を読む価格や日付などの保存値で絞りたいmeta_queryの使い方

カスタムフィールドのキーと値、比較方法を指定して投稿を取得する方法を確認できます。

記事を読む新しい順などに並べたいorderbyとorderで記事の順番を変える

並べる基準と昇順・降順の組み合わせを確認できます。

記事を読む表示中の記事を一覧から外したい現在の記事を除外して一覧を作る

現在の記事IDを取得し、post__not_inで除外する方法を確認できます。

表示中の記事のカテゴリーを使って、関連記事の取得条件を作る方法を確認できます。

記事を読む

使うパラメーターが決まったら、次は取得した投稿をどこに、どんな形で表示するかを考えます。タイトルだけの一覧にするのか、画像付きのカードにするのかによって、表示用のコードは変わります。

使いたいパラメーターが分かったら、WP Query Builderの画面で条件を選んでみましょう。生成後は、このページの後半で紹介する検証環境に取得・表示のコードを設置して確かめます。

選んだ条件でWP_Queryのコードを作る

まずは通常の投稿を新しい順に3件。少ない条件で$argsを生成し、確認しながら絞り込みを足していきましょう。

WP Query Builderでクエリを作る

困りごとは症状から切り分ける

コードが動かない時は、最初からすべてを書き直すより、画面に起きている症状に合う確認順を使います。「0件」「絞り込みが効かない」「件数が合わない」「同じ記事が出る」「2ページ目がおかしい」は、似て見えても確認する場所が異なります。

まず取得条件を最小にし、対象の投稿が公開されているか、post_typeやID・slug・保存値が合っているかを確認します。ページネーションの症状では、1ページ目だけで判断せず、2ページ目以降のURLと取得結果も見ます。

投稿が1件も出ない投稿が表示されない時のチェックリスト

公開状態や取得条件から順に、0件になる原因を切り分けられます。

記事を読むカスタム投稿だけ出ないカスタム投稿が出ない原因

投稿タイプの登録名や取得条件など、カスタム投稿で確認したい点を調べられます。

記事を読む指定したカテゴリーに絞れないカテゴリー絞り込みが効かない原因

カテゴリーIDやスラッグの指定と、使っているパラメーターの対応を確認できます。

記事を読むカスタムフィールドの条件が効かないmeta_queryが効かない時のチェックリスト

実際の保存値と、キー・型・比較方法の食い違いを確認できます。

記事を読む指定した件数と合わない表示件数が合わない原因

取得件数と表示件数を分け、絞り込みやページ送りの影響を調べられます。

記事を読む同じ記事が繰り返し出る同じ記事が重複表示される原因

ループや取得条件を確認し、同じ記事を繰り返し表示している箇所を探せます。

記事を読む 2ページ目以降がおかしいページネーションが動かない原因

現在ページの値、取得結果、リンク先のURLを順に確認できます。

記事を読む

症状記事で原因を見つけた後は、対応する基礎記事へ戻り、動作する条件と基本コードを確認します。応急処置だけを追加すると、別のページや投稿件数が変わったときに同じ問題が起きやすくなります。

既存一覧を変えるか、追加一覧を作るかを分ける

カテゴリーアーカイブや検索結果などで、現在のURLに合わせてWordPressが投稿を取得する中心の処理をメインクエリと呼びます。その一覧の件数や対象を変えたいのに、テンプレートへ新しいWP_Queryを書いても、元の一覧の取得条件は変わりません。別の投稿取得の処理が増えることになります。

既存の一覧を変える場合は、対象を限定したpre_get_postsが候補になります。一方、記事下の関連記事、トップページの別枠、新着情報など、ブラウザで開いている記事や一覧とは別の投稿を追加する場合はWP_Queryが候補です。ここでいうサブクエリは、WordPressがURLに合わせて用意した一覧とは別に、ページ内で追加して実行する投稿取得のことです。

「一覧ページそのものを変える」のか、「一覧ページの中へ別の一覧を足す」のかを先に言葉にしてください。

古いコードでquery_posts()を見つけた時も、そのまま流用せず、メインクエリを変えたいのかサブクエリを作りたいのかを判断してから置き換えます。

既存一覧と関連記事の違いを知りたいメインクエリとサブクエリの違い

WordPressがURLに応じて用意する取得処理と、自分で追加する取得処理を区別できます。

記事を読む既存の一覧を変更したいpre_get_postsとWP_Queryの使い分け

カテゴリー一覧の変更と関連記事の追加を例に、どちらで実装するかを判断できます。

記事を読む古いコードにquery_posts()があるquery_postsを使わないほうがいい理由

既存コードの問題点を確認し、目的に合う方法へ置き換える際の考え方を整理できます。

記事を読む

WP Query Builderで取得条件を作る

WP Query Builderでは、画面で投稿タイプ、絞り込み条件、並び順、表示件数を選び、WP_Queryに渡す$argsのコードを生成できます。最初は「通常の投稿を新しい順に3件」のような少ない条件で試し、設定を変えるとコードのどこが変わるかを見てみましょう。

初めて使う方は、設定の入力からコードのコピーまでを説明した使い方ページをご覧ください。

操作方法を確認するWP Query Builderの使い方

入力する場所や生成コードの確認方法に迷ったときに、操作の流れを確認できます。

記事を読む

コードを生成できたら、検証用のWordPressへ設置して動かしてみましょう。たとえばクラシックテーマの記事下に関連記事を出す場合は、子テーマのsingle.phpや、そこから呼び出すテンプレートパーツに取得・表示の処理を置きます。

Builderで作った条件の配列だけでは一覧は表示されません。投稿を取得し、ループで表示する処理も必要です。パーツを使う場合は、ファイルの保存だけでなく、表示したい位置から呼び出すところまで確認します。

記事IDなどの値が自分のサイトに合っているか、タイトルやURLを安全に出力しているか、the_post()を使った後にwp_reset_postdata()で投稿データを戻しているかを確認してください。ブロックテーマでは設置方法が異なるため、PHPを投稿エディターへそのまま貼り付けないでください。

コードの設置先を決めるWP_Queryのコードはどこに書く？

テーマの種類と表示したい場所から、編集するファイルや実装方法を確認できます。

記事を読む

実装前に検証環境と戻し方を用意する

WP_Queryの条件が正しくても、貼り付けるファイルや位置を間違えると、ページ全体が表示されなくなることがあります。本番サイトを直接編集せず、バックアップを取ってから検証環境で試してください。

ローカル環境は、自分のパソコン上で動かす検証用のWordPressです。ステージング環境は、本番サイトとは別に用意した、本番に近い構成の確認用サイトを指します。レンタルサーバーにWordPressを作っただけで本番と同じ条件になるわけではないため、PHPのバージョン、テーマ、プラグイン、データ、キャッシュ設定の違いも確認します。

検証では、対象件数が0件・1件・複数件の場合、ログイン中とログアウト中、PCとスマートフォンを確認します。ページ送りを使うなら2ページ目以降、サブループでthe_post()を使うなら後続のタイトルやURLも確認します。

実装から公開までの基本順

1
作りたい一覧と期待する結果を決める
2
バックアップと戻し方を用意し、検証環境を準備する
3
WP Query Builderまたは最小コードで取得条件を作る
4
検証環境の適切なファイルに取得・表示の処理を置く
5
0件・1件・複数件の表示やページ送りを確認する
6
確認した変更を本番へ反映し、表示・リンク・エラーを再確認する

検証環境の準備や表示コードの書き方に迷ったら、次の記事で確認できます。

検証環境をまだ用意していないWP_Queryを試す検証環境の選び方

ローカル環境とサーバー上の検証環境の違いを確認し、試す場所を選べます。

記事を読む

取得から表示までのコードは上の「仕組みと最小構文から理解する」で紹介した基本構文の記事、ループ後の処理はwp_reset_postdata()の記事で確認できます。

サーバー上に検証用のWordPressや公開サイトを用意したい方は、Xserverも候補になります。検証用サイトは本番と分け、契約前に必要な機能や料金を確認してください。

重い時は条件を変える前に計測する

表示が遅い時、原因がWP_Queryとは限りません。画像、外部通信、プラグイン、PHP処理、データベース、キャッシュなどを分け、同じ条件で計測します。

まずは検証環境でQuery Monitorを有効にし、管理者として遅いページを開きます。管理バーからQuery Monitorを開くと、今回のリクエストのページ生成時間とデータベース処理時間、SQLの実行件数を確認できます。過去のアクセスや、画像を含むブラウザー全体の読み込み時間を示す数値ではありません。

データベース処理に時間がかかっているなら、クエリの一覧で遅いSQLと呼び出し元を確認します。同じURL・データ・キャッシュ条件で数回測り、条件を1つ変えた後も同じ方法で比較してください。SQLの件数が多いという理由だけで、遅さの原因とは判断しないでください。

計測の手順を詳しく見るWP_Queryが重い原因を調べる方法

Query Monitorで見る数値、遅いSQLと呼び出し元の探し方、変更前後の比較方法を確認できます。

記事を読む

WP_Queryの処理が原因だと分かったら、取得件数、全件取得、複雑なmeta_query、ランダム順、不要なページ数計算などを見直します。変更後は速度だけでなく、必要な投稿やページ送りが失われていないかも確かめましょう。

計測結果をもとに改善したいWP_Queryを高速化する方法

必要な機能を保ちながら、取得条件や処理量を見直す方法を確認できます。

記事を読む投稿を全件取得しているposts_per_page=-1が重くなる理由

件数が増えたときの負荷と、取得件数を制限する考え方を確認できます。

記事を読むランダム順で取得しているランダム表示の注意点

ランダムな並び順による負荷や、ページ送りでの注意点を確認できます。

記事を読む