wordpressのWP_Queryクラスが取る引数をまとめてみた

目次(クリックするとジャンプします）

1:WP_Queryクラスのコンストラクタ引数
2:パラメータまとめ表
3:補足説明
3.1:パラメータの多さ
3.2:良く分からないパラメータ
4:まとめ

関連するこちらの記事もオススメ

WP_Queryクラスのコンストラクタ引数

wordpressカスタマイズにおいてWP_Queryクラスをnewしてインスタンスを得る場合があるかとおもいますが、コンストラクタが取る引数のパラメータが膨大で、値の設定に苦労されている人も多いのではないかと思います。＠MINOがまさにその状態です。

今回奮起してパラメータを調べてみようと思い、WP_Queryクラスが定義されているwp-includes内にあるquery.phpを覗いてみました。＠MINOの力量だとソースを読むのはなかなか骨が折れますが、一応パラメータリストを作る事は出来きました。

ただ＠MINOの英語力も最悪なのでうまく訳せていない箇所もあるし、そのパラメータがどのように動作するかが判らなかったものもあります。その為完全なリストとは全く言えません。

参考程度にはなるかと思うのであまり期待しないで閲覧してもらえると幸いです。

パラメータまとめ表

パラメータはアルファベット順にしてあります。

クエリ	意味	値の型	初期値	許可される値
attachment_id	添付ファイルのポストID	int
author	著者ID、または著者IDのカンマ区切りのリスト	int\|string
author_name	著者のニックネーム	string
author__in	著者IDの配列	array
author__not_in	著者IDの配列（NOT）	array
cache_results	投稿情報をキャッシュするかどうか	bool	ture
cat	カテゴリIDまたはIDのカンマ区切りのリスト（または子カテゴリ）	int\|string
category__and	カテゴリIDの配列（AND）	array
category__in	カテゴリIDの配列（OR 子カテゴリなし	array
category__not_in	カテゴリIDの配列（NOT）	array
category_name	カテゴリスラッグ	string
comments_per_page	ページごとのコメント数	int
comments_popup	クエリは、コメントのポップアップ内にあるかどうか？	int\|string	empty
date_query	WP_Date_Query用の引数の連想配列	array
day	日	int	empty	1～31
exact	正確なキーワードで検索するか	bool	ture
fields	フィールド一つで返すか配列で返す	string\|array	all fields	ids’, ‘id=>parent’.
hour	時間	int		0～23
ignore_sticky_posts	「この投稿を先頭に固定表示」を無視するか(false)	bool	0\|false.	1\|true, 0\|false.
m	任意の4桁の年と月を受け入れ	int	empty	西暦4桁+1～12
meta_compare	「meta_value」をテストするための比較演算子	string
meta_key	カスタムフィールドキー	string
meta_query	WP_Meta_Query用の引数(連想配列)	array
meta_value	カスタムフィールドの値	string
meta_value_num	カスタムフィールド値番号？	int
menu_order	投稿のメニューの順番？	int
monthnum	月	int	empty	1～12
name	投稿のスラッグ	string
nopaging	すべての投稿を表示か(ture)、ページ分割するか(false)	bool	false
no_found_rows	カウントをスキップする？tureでパフォーマンスが向上する可能性がある？	bool	false
offset	オフセット	int
order	結果表示のソート昇順または降順指定	string	DESC’	‘ASC’, ‘DESC’.
orderby	結果表示のソート複数のオプションが可能	string	date’	‘none’, ‘name’, ‘author’, ‘date’, ‘title’, ‘modified’,’menu_order’, ‘parent’, ‘ID’, ‘rand’, ‘comment_count’
p	投稿のID	int
page	静的なフロントページのページXに表示される投稿数を表示	int
paged	現在のページの数	int
page_id	固定ページのID	int
pagename	固定ページのスラッグ	string
perm	ユーザーの権限による投稿表示抑制	string
post__in	取得する投稿IDの配列、スティッキーポストを含む	array
post_mime_type	投稿のMIMEタイプ	string
post__not_in	除外する投稿IDの配列(カンマで区切りは無効)	array
post_parent	子ページを取得するためのページID　トップレベルの取得には0を指定	int
post_parent__in	子ページを照会する親ページIDを含む配列	array
post_parent__not_in	除外する子ページ、親ページのIDを含む配列	array
post_type	投稿タイプのスラッグ（文字列）または投稿タイプのスラッグの配列	string
post_status	投稿の状態（文字列）または状態の配列	string		publish’,’pending’,’draft’,’auto-draft’,’future’,’private’,’inherit’,’trash’,’any’
posts_per_page	照会する投稿の数。 -1指定ですべての投稿を取得する	int
posts_per_archive_page	検索ページまたはアーカイブページにおいて照会する投稿の数	int
s	検索キーワード	string
second	分	int		0～60
search_terms	タームの配列	array
sentence	語句で検索するか	bool	false
suppress_filters	フィルターを非表示にするかどうか	bool	false
tag	タグスラッグ。カンマ区切り（いずれか）、プラスで区切られた（すべて）	string
tag__and	タグIDの配列（AND）	array
tag__in	タグIDの配列（OR）	array
tag__not_in	タグIDの配列（NOT）	array
tag_id	タグIDまたはIDのカンマ区切りのリスト	int
tag_slug__and	タグスラッグの配列（AND）	array
tag_slug__in	タグスラッグの配列（OR）(カンマ区切り無効) 「ignore_sticky_posts」しない限り、真実である？	array
tax_query	WP_Tax_Query用の引数(連想配列)	array
update_post_meta_cache	投稿メタキャッシュを更新するかどうか	bool	ture
update_post_term_cache	投稿タームキャッシュを更新するかどうか	bool	ture
w	週	int		0～53
year	年	int		西暦４桁

補足説明

パラメータの多さ

パラメータはなんと66個もあります。これを使いこなせたら相当複雑なクエリを発行することが可能になりますね。機能の設定パラメータも複数あるので、検索値として使えるのは66個よりは少なくなりますが、それでも組み合わせは膨大です。

例えば2014年中に公開、’パソコン’カテゴリに属していて、著者のニックネームが’物書き’の投稿というSQLで書くにはすこし複雑な条件でも

array( 'year' => 2014, 'cat' => 'パソコン', 'author_name' => '物書き' )

で照会することができます。

表示順もデフォルトでは公開日時の降順になっていますが、ID順、コメント数順、タイトル順(辞書順だと思われる)、更新日順、スラッグ順(辞書順だと思われる)、著者順、ランダム順などなど(それぞれの降順、昇順)多彩に設定できる。

良く分からないパラメータ

良く分からなかった、うまく訳せなかったパラメータは「？」を付けています。該当するのはcomments_popup、meta_value_num、menu_order、no_found_rows、tag_slug__inの5つです。

comments_popupはコメントをホップアップさせる機能と関連していると思うのですが、このパラメータの説明である原文「Whether the query is within the comments popup」の意味が分かりませんでした。訳すと「クエリがcomments_popupの中にあるかどうか」といったような意味になると思うのですが、何のことなのかさっぱり。

meta_value_numはおそらくカスタムフィールドに関係すると思います。カスタムフィールドはwp_postmetaというテーブルに格納されており、meta_idという値を持っています。このmeta_idがmeta_value_numのことなんじゃないかと思ったのですが、違うみたいです。指定する値の型はintなので数字になるはずですが…。

menu_orderはおそらく固定ページの表示順の設置に関していると思います(未検証)。

no_found_rowsは英語原文の説明を見る限り、データベースに問い合わせする際の挙動の設定のようです。照会されたrowに対してカウントを行わない的な内容が書かれているのですが、なんのカウントなのかが判らなかったです。またこの設定をtureにするとパフォーマンスが向上する可能性があるとも書かれていました。

tag_slug__inはタグのスラッグの事を指しているのはわかるのですが、英語原文の「unless ‘ignore_sticky_posts’ is　true」の注釈の意味が良く分かりませんでした。なぜ’ignore_sticky_posts’と関係あるのでしょう？

以上はあまり使わなさそうなパラメータだが、判らず釈然としません。申し訳ないです。

まとめ

WP_Queryクラスはとても便利。データベースに問い合わせする仕組みとして、wordpressでは$wpdbインスタンスを用意してくれているが、これはガチのSQLクエリが必要になるので慣れていない人は大変だろうと思います。

WP_Queryクラスなら、適切にパラメータを設定してあげるだけで、インスタンスを得ることができます。

$wpdbインスタンスは最後の手段としておいて、WP_Queryクラスを使いこなせるようになるのが良いのではないかと思います。

ともすれば$wpdbインスタンスで何とかしようとするのは、＠MINOの悪い癖です。