赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください（詳細）。
WordPressのPHP・MySQL 4 対応終了予定が発表されました（詳細）。
英語版Codexとフォーラム等のログイン情報が統合されました（詳細）。

テンプレートタグ/query posts

出典: WordPress Codex 日本語版

< テンプレートタグ

移動: ナビゲーション, 検索

説明

query_posts は WordPress ループで表示される投稿を変更するために使います。この関数は URL で使われるのと同じ書式の各種引数（例：p=4 なら投稿ID が 4 の記事のみを表示します）を受け取ります。

URL から得られたクエリを変更することはトラブルの元になります。条件分岐タグのようなページの判定を組み合わせることで、URL を一切変えることなくブログの見せ方をカスタマイズすることができます。

よくある利用例：

フロントページに任意の記事を表示する（管理画面の設定 > 表示設定で固定ページを指定することもできます）。
指定した期間の投稿すべてを表示する。
フロントページに最新の投稿（だけ）を表示する。
投稿の表示順序を変更する。
特定のカテゴリーに含まれる記事だけを表示する。
1つまたは複数のカテゴリーに含まれる記事を除く。

重要事項

query_posts 関数はメインの WordPress ループだけを変更するためのものです。新たなループを作るためのものではありません。メインループの他にループが必要な場合は、別の WP_Query オブジェクトを作ってください。メインループの他で query_posts を使用すると、メインループが不正な状態になり期待する結果が得られません。

query_posts 関数はページのメインクエリを上書きし、置き換えます。他の目的で使用してはいけません。

使い方

<?php

//The Query
query_posts('posts_per_page=5');

//The Loop
if ( have_posts() ) : 
  while ( have_posts() ) : 
    the_post();
      ..
  endwhile; 
else:
  ..
endif;

//Reset Query
wp_reset_query();

?>

注意事項

query_posts() はテンプレートファイル内で WordPress ループが始まる前に記述します。wp_query オブジェクトは与えられた引数から新しい SQL クエリを作ります。このとき、WordPress は（ページ番号やカテゴリーのような）URL から得られた引数を無視します。もしその情報が必要なら、query_posts() の引数としてグローバル変数の $query_string を与えます。

例えば、他のクエリ引数に影響を与えずに投稿の表示順序だけを指定したいなら WordPress ループの前に以下のように記述します:

global $query_string;
query_posts($query_string . "&order=ASC");

この形式で query_posts を使う場合は、二重引用符で囲んだ引数をアンド記号（&）で始めてください。

引数

ここでの記述例がすべてではありません。引数を組み合わせることで、より実用的なクエリが可能になります。

カテゴリー引数

指定したカテゴリーに分類された投稿を取得する。

cat （整数）- カテゴリーIDを指定。コンマ区切りにした複数IDの文字列も指定可能。
category_name （文字列）- カテゴリー名を指定（日本語も可）。
category__and（配列）- カテゴリーIDの配列。指定した複数のカテゴリーすべてに含まれる投稿のみを取得。
category__in（配列）- カテゴリーIDの配列。指定した複数のカテゴリーいずれかに含まれる投稿のみを取得。
category__not_in（配列）- カテゴリーIDの配列。指定した複数のカテゴリーのいずれにもに含まれない投稿のみを取得。

IDでカテゴリーを指定

IDで指定したカテゴリー（とその子孫カテゴリー）に含まれる投稿のみを取得します：

query_posts('cat=4');

名前でカテゴリーを指定

名前で指定したカテゴリーに含まれる投稿のみを取得します：

query_posts('category_name=Staff Home');

IDで複数のカテゴリーを指定

IDで指定した複数のカテゴリーのいずれかに含まれる投稿を取得します：

query_posts('cat=2,6,17,38');

IDで指定したカテゴリーを除く

'-'（マイナス）記号を前につけたカテゴリーID 以外の投稿を取得します：

query_posts('cat=-3');

これはカテゴリーID 3 に含まれる投稿をすべて除きます。

複数カテゴリーの指定方法

IDで指定した複数のカテゴリーすべてに含まれるカテゴリーを取得します。以下はカテゴリーID 2 と 6 の両方に含まれる投稿を取得:

query_posts(array('category__and' => array(2,6)));

カテゴリーID 2 または 6 に含まれる投稿を取得するには、前述の cat か category__in（こちらは子孫カテゴリーを含みません）を使います：

query_posts(array('category__in' => array(2,6)));

以下の指定では複数のカテゴリーのいずれかに含まれる投稿を除くことができます：

query_posts(array('category__not_in' => array(2,6)));

タグ引数

指定したタグがつけられた投稿を取得する。

tag （文字列）- タグスラッグを指定。
tag_id （整数）- タグ ID を指定。コンマ区切りにした複数IDの文字列も指定可能。
tag__and （配列）- タグ ID の配列。指定した複数のタグのすべてを含む投稿のみを取得。
tag__in （配列）- タグ ID の配列。指定した複数のタグのいずれかを含む投稿のみを取得。
tag__not_in （配列）- タグ ID の配列。指定した複数のタグのいずれも含まない投稿のみを取得。
tag_slug__and （配列）- タグスラッグの配列。指定した複数のタグすべてを含む投稿のみを取得。
tag_slug__in （配列）- タグスラッグの配列。指定した複数のタグのいずれかを含む投稿のみを取得。

指定した1つのタグを含む投稿を取得

query_posts('tag=cooking');

指定したタグのいずれかを含む投稿を取得

query_posts('tag=bread,baking');

指定した3つのタグすべてを含む投稿を取得

query_posts('tag=bread+baking+recipe');

複数タグの指定方法

タグID 37 と 47 の両方を含む投稿を取得します：

query_posts(array('tag__and' => array(37,47));

タグID 37 または 47 のいずれかを含む投稿を取得するには、前述の tag か tag__in を使います：

query_posts(array('tag__in' => array(37,47));

タグID 37 と 47 のいずれも含まない投稿を取得します：

query_posts(array('tag__not_in' => array(37,47));

tag_slug__in と tag_slug__and はタグスラッグを指定する他は上記と同様です。

Ryan's discussion of Tag intersections and unions も参照してください。

投稿者引数

指定したIDや名前の投稿者による投稿を取得する。

author=3 （整数）- 取得する投稿者のIDを指定。
author=-3 （整数）- 除外する投稿者のIDを指定。
author_name=Harriet （文字列）- 投稿者のニックネームを指定（日本語も可）。

注意： author_name は user_nicename フィールドの値を指定します。author には ID を指定します。

author=1 のすべての固定ページをタイトル順, 先頭固定表示無しで表示します：

query_posts('caller_get_posts=1&author=1&post_type=page&post_status=publish&orderby=title&order=ASC');

記事・固定ページ引数

指定したIDや名前の記事・固定ページを取得する。

'p' => 27 （整数）- 取得する投稿 ID を指定。
'name' => 'about-my-life' （文字列）- 取得する投稿スラッグを指定。
'page_id' => 7 （整数）- 取得する固定ページ ID を指定。
'pagename' => 'about' （文字列）- 取得する固定ページスラッグを指定。タイトルではありません。
'posts_per_page' => 1 （整数）- 1ページに表示する記事数。'posts_per_page' => 3 なら3件取得。'posts_per_page' => -1 ならすべての投稿を取得。
'showposts' => 1 （整数）- 出力する投稿の数。'showposts' => 3 なら3件取得。'showposts' => -1 ならすべての投稿を取得。posts_per_page の導入により非推奨
'post__in' => array(5,12,2,14,7) （配列）- 取得する投稿の ID を配列で指定。
'post__not_in' => array(6,2,8) （配列）- 取得しない投稿の ID を配列で指定。
'post_type' => 'page' - 取得する投稿タイプを page（固定ページ）、post（投稿）、attachment（添付ファイル）、revision（変更履歴）のいずれかで指定。初期値は post。any はリビジョン以外の投稿タイプを取得します。バージョン 3.0 以降から movie などのカスタム投稿タイプも指定できます。
'post_status' => 'publish' - 取得するステータスを publish（公開済み）、pending（レビュー待ち）、draft（下書き）、future（スケジュール済み）、private（非公開）、trash（ゴミ箱入り）、inherit（get_children/en 参照）のいずれかで指定。trash の値はバージョン 2.9 以降のみ有効。
'post_parent' => 93 （整数）- 取得する固定ページの親ページ ID を指定。

通常の記事とカスタム投稿タイプ movie の両方を取得:

query_posts( array( 'post_type' => array('post', 'movie') ) );

先頭固定投稿引数

投稿の先頭固定表示はバージョン 2.7 から導入。先頭固定と設定された投稿は caller_get_posts=1 を指定しない限り他の投稿よりも先に表示されます。

array('post__in'=>get_option('sticky_posts')) - すべての先頭固定投稿を配列として返す。
caller_get_posts=1 - 先頭固定投稿を通常の順序にする（先頭に固定しない）。

1件目の先頭固定投稿を取得:

$sticky=get_option('sticky_posts') ; 
query_posts('p=' . $sticky[0]);

または

$args = array(
	'posts_per_page' => 1,
	'post__in'  => get_option('sticky_posts'),
	'caller_get_posts' => 1
);
query_posts($args);

注意：2つ目の方法は最新の先頭固定投稿を1件取得します。先頭固定投稿がない場合は最新の投稿を1件取得します。

最新の先頭固定投稿だけを対象にする:

$sticky = get_option('sticky_posts');
$args = array(
	'posts_per_page' => 1,
	'post__in'  => $sticky,
	'caller_get_posts' => 1
);
query_posts($args);
if($sticky[0]) {
   // ここに処理を記述
}

すべての先頭固定投稿を除く:

query_posts(array("post__not_in" =>get_option("sticky_posts")));

指定カテゴリーに含まれるすべての投稿を、先頭固定なしで取得します。先頭固定投稿は通常の順序（例：日付順）になります：

query_posts('caller_get_posts=1&posts_per_page=3&cat=6');

指定カテゴリーに含まれるすべての投稿から、先頭固定投稿を除き、ページングありで取得:

<?php
$paged = (get_query_var('paged')) ? get_query_var('paged') : 1;
$sticky=get_option('sticky_posts');
$args=array(
   'cat'=>3,
   'caller_get_posts'=>1,
   'post__not_in' => $sticky,
   'paged'=>$paged,
   );
query_posts($args);
?>

日時引数

それぞれ、その日時の間に投稿された投稿を取得する。マイナスの値は使えない。

hour= （整数）- 時 (0〜23)
minute= （整数）-分 (0〜59)
second= （整数）- 秒 (0〜59)
day= （整数）- 日 (1〜31)
monthnum= （整数）- 月 (1〜12)
year= （整数）- 4桁の年 (例：2009)
w= （整数）- 0〜53 で年間のうちどの週かを選ぶ。MySQL WEEK command Mode=1 を使っている。

今日の投稿を取得:

$today = getdate();
query_posts('year=' .$today["year"] .'&monthnum=' .$today["mon"] .'&day=' .$today["mday"] );

12月20日の投稿を取得:

query_posts( 'monthnum=12&day=20' );

2009年3月15日の投稿を取得:

<?php
//based on Austin Matzko's code from wp-hackers email list
  function filter_where($where = '') {
    //posts for March 1 to March 15, 2009
    $where .= " AND post_date >= '2009-03-01' AND post_date < '2009-03-16'";
    return $where;
  }
add_filter('posts_where', 'filter_where');
query_posts($query_string);
?>

最近30日間の投稿を取得:

<?php
//based on Austin Matzko's code from wp-hackers email list
  function filter_where($where = '') {
    //posts in the last 30 days
    $where .= " AND post_date > '" . date('Y-m-d', strtotime('-30 days')) . "'";
    return $where;
  }
add_filter('posts_where', 'filter_where');
query_posts($query_string);
?>

30〜60日前の投稿を取得

<?php
//based on Austin Matzko's code from wp-hackers email list
  function filter_where($where = '') {
    //posts  30 to 60 days old
    $where .= " AND post_date >= '" . date('Y-m-d', strtotime('-60 days')) . "'" . " AND post_date <= '" . date('Y-m-d', strtotime('-30 days')) . "'";
    return $where;
  }
add_filter('posts_where', 'filter_where');
query_posts($query_string);
?>

ページング引数

nopaging=true - ページングを無効にする。
posts_per_page=10 （整数）- 1ページに出力する投稿数。-1の場合すべての投稿を出力。
paged=2 （整数）- インデックスや月別・カテゴリー別アーカイブページンなどが複数ページにわたる場合の、表示するページ番号を指定。
order=ASC （ASC/DESC）- 取得したページの並び順。デフォルト値は「DESC」。

オフセット引数

取得される投稿の先頭から指定した件数をスキップします。

offset （整数）- 投稿の先頭からスキップする件数を指定。

以下は、最新の投稿（1件）に続く5件の投稿を取得します:

query_posts('posts_per_page=5&offset=1');

並び替え引数

指定したフィールドで投稿を並び替えて取得する。

orderby=author
orderby=date
orderby=title
orderby=modified
orderby=menu_order 注意: 固定ページのみ有効。
orderby=parent
orderby=ID
orderby=rand
orderby=meta_value 注意: カスタムフィールド引数として meta_key=keyname が指定されていること。
orderby=none - 順番指定なし（バージョン 2.8 以降のみ）
orderby=comment_count - （バージョン 2.9 以降のみ）

並び順引数

並び替え引数の並び順を昇順または降順で指定。

order=ASC - 昇順。小さい値から大きい値の順。
order=DESC - 降順。大きい値から小さい値の順。

カスタムフィールド引数

カスタムフィールドのキーまたは値を元に、投稿（または固定ページ) を取得。

meta_key=
meta_value=
meta_compare= - meta_value で指定された値を比較する演算子。デフォルトは '=' で， '!='、'>'、'>='、'<'、'<=' も使える。

キーが 'color' で値が 'blue' のカスタムフィールドを持つ投稿を取得:

query_posts('meta_key=color&meta_value=blue');

キーが 'color' のカスタムフィールドを持つ投稿を取得（値は問わない）:

query_posts('meta_key=color');

値が 'blue' のカスタムフィールドを持つ投稿を取得（キーは問わない）:

query_posts('meta_value=blue');

値が 'green' のカスタムフィールドを持つ固定ページを取得（キーは問わない）:

query_posts('post_type=page&meta_value=green');

キーが 'color' で値が 'blue' でないカスタムフィールドを持つ記事と固定ページの両方を取得:

query_posts('post_type=any&meta_key=color&meta_compare=!=&meta_value=blue');

キーが 'miles' で値が 22 以下のカスタムフィールドを持つ投稿を取得。注意：値は数値ではなく文字列として扱われているため「99」は「100」より大きくなります。

query_posts('meta_key=miles&meta_compare=<=&meta_value=22');

引数の組み合わせ

引数はアンド記号（&）を使って複数組み合わせて指定することができます:

query_posts('cat=3&year=2004');

「最新の投稿」ページで、カテゴリーID が 13 かつ今月の投稿を取得する:

if (is_home()) {
query_posts($query_string . '&cat=13&monthnum=' . date('n',current_time('timestamp')));
}

バージョン 2.3 では、以下の組み合わせはカテゴリーID 1 と 3 に含まれる投稿を2件、タイトルの降順で取得します:

 query_posts(array('category__and'=>array(1,3),'posts_per_page'=>2,'orderby'=>title,'order'=>DESC));

バージョン 2.3 とバージョン 2.5 では、カテゴリーID が 1 で "apples" を含む投稿を取得することが期待される。

query_posts('cat=1&tag=apples');

バグ：カテゴリーとタグを同時に指定する場合は「+」で同じタグを2つ指定してください。参照 Ticket #5433

query_posts('cat=1&tag=apples+apples');

注意：'cat=1&tag=apples+oranges' は期待する結果にはなりません。

コード記述例

「最新の投稿」ページから指定カテゴリーを除く

index.php ファイルに以下のコードを書くと、カテゴリーID が 3 以外の 投稿を表示します。

<?php
   if (is_home()) {
      query_posts("cat=-3");
   }
?>

複数のカテゴリーID を指定することができます（バージョン 2.1.2 で検証済）。

<?php
   if (is_home()) {
      query_posts("cat=-1,-2,-3");
   }
?>

特定の記事を取得

特定の記事を取得する:

<?php
// 記事ID が 5 の投稿を取得する
query_posts('p=5');      
?>

続きを読む を表示したい場合は、グローバル変数 $more を 0 にします。

<?php
// 記事ID が 5 の投稿を取得する
query_posts('p=5');
      
global $more;
// 投稿の始めの部分のみ表示するため $more を 0 にする
$more = 0; 

// the Loop
while (have_posts()) : the_post(); 
  // 記事の本文
  the_content('Read the full post »'); 
endwhile;
?>

2008年5月に投稿された、カテゴリー ID 1 と 3 の投稿タイトルを1ページに5件ずつ表示する：

<?php if (have_posts()) :  query_posts('posts_per_page=5&cat=1,3&monthnum=5&year=2008');  ?>
  <?php while (have_posts()) : the_post(); ?>
    <h2><?php the_title(); ?></h2>
<?php endwhile; endif; ?>

カテゴリー ID 2 と 6 のいずれにも含まれないすべての投稿のタイトルをリストとして表示する：

<?php if (have_posts()) :  query_posts(array('category__not_in' => array(2,6))); ?>
<ul>
 <?php while (have_posts()) : the_post(); ?>
    <li><?php the_title(); ?></li>
<?php endwhile; endif; ?>
</ul>

特定の固定ページを取得

特定の固定ページを取得する：

<?php
query_posts('page_id=7');      // 投稿ID が 7 の固定ページのみ取得
?>

または

<?php
query_posts('pagename=about'); // 投稿スラッグが about の固定ページのみ取得
?>

子ページの場合は、親ページと子ページの投稿スラッグをスラッシュ（/）で区切って指定します：

<?php
query_posts('pagename=parent/child'); // 「parent」の子ページ「child」を取得
?>

query_posts に変数を与える

query_posts に変数を与える方法は2通りあります。どちらを使用してもかまいません。WordPress ループの前に記述してください:

記述例 1

この例は、query_posts を実行する前にクエリ文字列を連結します。まず変数に値を代入し、変数と文字列を結合して、実行します。ここではカテゴリーID を変数で与えることにします。

 <?php
 $categoryvariable=$cat; // 現在のカテゴリーID を変数に代入
 $query= 'cat=' . $categoryvariable. '&orderby=date&order=ASC'; // クエリを連結
 query_posts($query); // クエリを実行
 ?>

記述例 2

次の例では、二重引用符を使って PHP に式を評価させます。まず、現在の年・月を取得し、query_posts で公開日が現在の年・月に該当する投稿を取得します。投稿の並び順は日付の昇順で、公開日の古い順に取得します。

<?php
$current_month = date('m');
$current_year = date('Y');

query_posts("cat=22&year=$current_year&monthnum=$current_month&order=ASC");
?>
<!-- ここでループ処理 -->

記述例 3

この例では、ページングを使ってすべての投稿を取得する場合を説明します。デフォルトの $query_string を使って query_posts ですべての投稿を取得させることができます。posts_per_page の値には -1 か各ページに表示したい投稿の数を指定します。後者の場合には posts_nav_link() でページを移動する手段を提供しましょう。

<?php 
query_posts($query_string.'&posts_per_page=-1');
while(have_posts()) { the_post();
<!-- ここでループ処理 -->
}
?>

記述例 4

$query_string 変数を使わずに、引数を配列に入れる方法もあります。例えば、記述例 2 のクエリは以下のようになります:

query_posts(array(
 'cat'      => 22, 
 'year'     => $current_year, 
 'monthnum' => $current_month, 
 'order'    => 'ASC',
));

この方法は、変数ごとに1行ずつ記述すると読み易くなります。

オリジナルクエリの保持（ページングなど）

デフォルトでは query_posts を実行すると、引数で指定した変数を除きページング，カテゴリー，日付などの現在のページのクエリ変数はすべて上書きされます。

オリジナルのクエリを保持したい場合は、query_poats の引数にオリジナルクエリの配列をマージしてください:

global $wp_query;
query_posts(
	array_merge(
		array('cat' => 1),
		$wp_query->query
	)
);

使い方のヒント

管理画面の設定 > 表示設定にある "1ページに表示する最大投稿数" パラメータで通常の表示件数を指定できます。これを変更するには 'posts_per_page' 引数を使います:

query_posts('category_name=The Category Name&posts_per_page=-1');  // 指定カテゴリーに含まれるすべての投稿を取得