Function Reference/query posts WordPress Codex

http://codex.wordpress.org/Template_Tags/query_posts

Search the Codex

Go

Home

Showcase

Extend

About

Blog

Forums

Hosting

Codex
Function Reference/query posts
Languages: English () Portugus do Brasil (Add your language)

Codex tools: Log in

Home Page WordPress Lessons Getting Started Working with WordPress

Description
query_posts() is the easiest way to alter the default query that WordPress uses to display posts. Use query_posts() to display different posts than those that would normally show up at a specific URL.

Contents
[hide] 1 Description 2 Caveats 2.1 Alters Main Loop

Design and Layout Advanced Topics Troubleshooting Developer Docs About WordPress

For example, on the homepage, you would normally see the latest 10 posts. If you want to show only 5 posts (and don't care about pagination), you can use query_posts() like so:

2.2 Not for Secondary Loops 2.3 Pagination 2.4 Additional SQL Queries 3 Usage

Codex Resources
Community portal Current events Recent changes Random page Help

query_posts( 'posts_per_page=5' );

3.1 Usage Note 3.2 Combining Parameters

Caveats
query_posts() is only one way amongst many to query the database and generate a list of posts. Before deciding to use query_posts(), be sure to understand the drawbacks.

4 Parameters 5 Examples 5.1 Exclude Categories From Your Home Page 5.2 Retrieve a Particular Post 5.3 All Posts in a Category

Alters Main Loop

query_posts() is meant for altering the main loop. Once you use query_posts(), your post-related global variables and template tags will be altered. Conditional tags that are called after you call query_posts() will also be altered - this may or may not be the intended result.

5.4 Syndication Feeds 5.5 Passing variables to query_posts 5.5.1 Example 1 5.5.2 Example 2 5.5.3 Example 3 5.5.4 Example 4

Not for Secondary Loops

You should not use query_posts() to create secondary listings (for example, a list of related posts at the bottom of the page, or a list of links in a sidebar widget).

5.5.5 Example 5 6 Source File 7 Resources 8 Related

Instead, you should make a new instance of WP_Query or use get_posts().

Pagination
Pagination won't work correctly, unless you use query_posts() in a page template and you set the 'paged' query var appropriately: http://scribu.net/wordpress/wp-pagenavi/right-way-to-use-query_posts.html

Additional SQL Queries

If you use query_posts within a template page, WordPress will have already executed the database query and retrieved the records by the time it gets to your template page (that's how it knew which template page to serve up!). So when you over-ride the default query with query_posts(), you're essentially throwing away the default query and its results and re-executing another query against the database.

This is not necessarily a problem, especially if you're dealing with a smaller blog-based site. Developers of large sites with big databases and heavy visitor traffic may wish to consider alternatives, such as modifying the default request directly (before it's called). The request filter can be used to achieve exactly this.

Usage
<?php

1 de 5

10/10/2011 14:42

Function Reference/query posts WordPress Codex

http://codex.wordpress.org/Template_Tags/query_posts

// The Query query_posts( $args ); // The Loop while ( have_posts() ) : the_post(); echo '<li>'; the_title(); echo '</li>'; endwhile; // Reset Query wp_reset_query(); ?>

Usage Note
Place a call to query_posts() in one of your Template files before The Loop begins. The wp_query object will generate a new SQL query using your parameters. When you do this, WordPress ignores the other parameters it receives via the URL (such as page number or category). If you want to preserve that information, you can use the $query_string global variable in the call to query_posts().

For example, to set the display order of the posts without affecting the rest of the query string, you could place the following before The Loop:

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

When using query_posts() in this way, the quoted portion of the parameter must begin with an ampersand (&).

Or alternatively, you can merge the original query array into your parameter array:

global $wp_query; $args = array_merge( $wp_query>query, array( 'post_type' => 'product' ) ); query_posts( $args );

Combining Parameters
You may have noticed from some of the examples above that you combine parameters with an ampersand (&), like so:

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

Posts for category 13, for the current month on the main page:

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

At 2.3 this combination will return posts belong to both Category 1 AND 3, showing just two (2) posts, in descending order by the title:

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

The following returns all posts that belong to category 1 and are tagged "apples"

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

You can search for several tags using +

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

Parameters
Note: Parameter details can be found in the Parameter section of the WP_Query class article.

2 de 5

10/10/2011 14:42

Function Reference/query posts WordPress Codex

http://codex.wordpress.org/Template_Tags/query_posts

The examples below also work with the WP_Query object.

Examples
Exclude Categories From Your Home Page
Placing this code in index.php file will cause the home page to display posts from all categories except category ID 3.

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

You can also add some more categories to the exclude-list (tested with WP 2.1.2):

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

Retrieve a Particular Post

To retrieve a particular post, you could use the following:

query_posts( 'p=5' );

Note: If the particular post is an attachment, you have to use attachment_id instead of p:

query_posts( 'attachment_id=5' );

If you want to use the Read More functionality with this query, you will need to set the global $more variable to 0.

<?php // retrieve one post with an ID of 5 query_posts( 'p=5' ); // set $more to 0 in order to only get the first part of the post global $more; $more = 0; // the Loop while (have_posts()) : the_post(); the_content( 'Read the full post ' ); endwhile; ?>

All Posts in a Category

The "Blog pages show at most" parameter in Settings > Reading can influence your results. To overcome this, add the 'posts_per_page' parameter. For example:

query_posts( array ( 'category_name' => 'The Category Name', 'posts_per_page' => 1 ) );

This will returns ALL posts from the category.

However, for subcategories (or child categories), 'The Category Name' doesn't always work. Rather use 'category-slug' instead. See Function_Reference/is_category.

if (is_category('categoryslug')): query_posts(array('category_name' => 'categoryslug', 'posts_per_page' => 1 )); endif;

Syndication Feeds
The "Syndication feeds show the most recent" or 'posts_per_rss' parameters in Settings > Reading will overwrite any

3 de 5

10/10/2011 14:42

Function Reference/query posts WordPress Codex

http://codex.wordpress.org/Template_Tags/query_posts

'posts_per_page' parameter in a query used in a feed.

To overcome use (for example in a a custom ics feed, where all matching posts are required), use the "posts_limit" filter as follows:

if ( isset ( $query>query_vars['feed'] ) and ( $query>query_vars['feed'] == 'ics' ) ) add_filter( 'post_limits', 'no_limits_for_feed' ); function no_limits_for_feed( $limits ) { return ''; }

Passing variables to query_posts

You can pass a variable to the query with two methods, depending on your needs. As with other examples, place these above your Loop:

Example 1
In this example, we concatenate the query before running it. First assign the variable, then concatenate and then run it. Here we're pulling in a category variable from elsewhere.

// assign the variable as current category $categoryvariable = $cat; // concatenate the query $args = 'cat=' . $categoryvariable . '&orderby=date&order=ASC'; // run the query query_posts( $args );

Example 2
In this next example, the double quotes tell PHP to treat the enclosed as an expression. For this example, we are getting the current month and the current year, and telling query_posts() to bring us the posts for the current month/year, and in this case, listing in ascending order so we get the oldest post at the top of the page.

$current_year = date('Y'); $current_month = date('m'); query_posts( "cat=22&year=$current_year&monthnum=$current_month&order=ASC" );

Example 3
This example explains how to generate a complete list of posts, dealing with pagination. We can use the default $query_string telling query_posts() to bring us a full posts listing. We can also modify the posts_per_page query parameter from -1 to the number of posts you want to show on each page; in this last case, you'll probably want to use posts_nav_link() to navigate the generated archive.

query_posts( $query_string . '&posts_per_page=1' );

Example 4
If you don't need to use the $query_string variable, another method exists that is more clear and readable, in some more complex cases. This method puts the parameters into an array. The same query as in Example 2 above could be done like this:

$args = array( 'cat' 'year' 'monthnum' 'order' ); query_posts( $args

=> => => => );

22, $current_year, $current_month, 'ASC'

As you can see, with this approach, every variable can be put on its own line, for easier reading.

4 de 5

10/10/2011 14:42

Function Reference/query posts WordPress Codex

http://codex.wordpress.org/Template_Tags/query_posts

Example 5
It is even possible to use the array style (Example 4) to query multiple taxonomies. Simply supply the taxonomy slug with a string of comma-separated values (each value being one term). In the example below, we will get all movie posts starring either Bruce Campbell or Chuck Norris.

$args = array( 'post_type'=> 'movie', 'actor' => 'Bruce Campbell, Chuck Norris', 'order' => 'ASC' ); query_posts( $args );

Source File
query_posts() is located in wpincludes/query.php.

Resources
For more in-depth discussion of how WordPress generates and handles its queries, review these articles: Query Overview and Custom Queries

Related
Query Tags: WP_Query (Class), get_query_var(), query_posts(), have posts(), the_post(), rewind_posts(), wp_reset_postdata(), wp_reset_query()

See also index of Function Reference and index of Template Tags. Category: Template Tags
Privacy | License / GPL See also: WordPress.com | WordPress.TV | WordCamp | WP Jobs | Matt | Fan WP on Facebook | Blog RSS

5 de 5

10/10/2011 14:42