Basic usage
Build an array of arguments, pass it to WP_Query, loop over the results, then reset post data so template tags point back at the main query.
$query = new WP_Query( array(
'post_type' => 'post',
'posts_per_page' => 10,
) );
if ( $query->have_posts() ) :
while ( $query->have_posts() ) : $query->the_post();
the_title( '<h2>', '</h2>' );
endwhile;
endif;
// Restore the main query's $post.
wp_reset_postdata();$query = new WP_Query( [
'post_type' => 'post',
'posts_per_page' => 10,
] );
if ( $query->have_posts() ) :
while ( $query->have_posts() ) : $query->the_post();
the_title( '<h2>', '</h2>' );
endwhile;
endif;
// Restore the main query's $post.
wp_reset_postdata();Author
Docs ↗Show posts by, or not by, certain authors.
| Parameter | Type | Description |
|---|---|---|
author | intstring | Author ID, or a comma-separated list of IDs. Prefix an ID with - to exclude it: '-1,-2'. |
author_name | string | The author's user_nicename, not their display name. |
author__in 3.7+ | int[] | Posts by any of these author IDs. |
author__not_in 3.7+ | int[] | Posts by none of these author IDs. |
$args = array(
'author__in' => array( 2, 6 ),
);$args = [
'author__in' => [ 2, 6 ],
];Category
Docs ↗Show posts in, or not in, certain categories.
| Parameter | Type | Description |
|---|---|---|
cat | intstring | Category ID, children included. Comma-separate several IDs; prefix with - to exclude: '-12,-34'. |
category_name | string | Category slug, children included. 'staff,news' matches any; 'staff+news' matches all. |
category__and | int[] | Posts in all of these categories. |
category__in | int[] | Posts in any of these categories. Children are not included. |
category__not_in | int[] | Posts in none of these categories. Children are not included. |
$args = array(
'category__in' => array( 2 ),
'category__not_in' => array( 6 ),
);$args = [
'category__in' => [ 2 ],
'category__not_in' => [ 6 ],
];Tag
Docs ↗Show posts with, or without, certain tags.
| Parameter | Type | Description |
|---|---|---|
tag | string | Tag slug. 'bread,baking' matches any; 'bread+baking' matches all. |
tag_id | int | Tag ID. |
tag__and | int[] | Posts with all of these tag IDs. |
tag__in | int[] | Posts with any of these tag IDs. |
tag__not_in | int[] | Posts with none of these tag IDs. |
tag_slug__and | string[] | Posts with all of these tag slugs. |
tag_slug__in | string[] | Posts with any of these tag slugs. |
$args = array(
'tag_slug__in' => array( 'red', 'blue' ),
);$args = [
'tag_slug__in' => [ 'red', 'blue' ],
];Taxonomy
Docs ↗Query any taxonomy, including custom ones, with boolean logic between clauses.
| Parameter | Type | Description |
|---|---|---|
tax_query 3.1+ | array | An array of clause arrays. Clauses can be nested, each with its own relation. |
Keys inside tax_query
| Parameter | Type | Description |
|---|---|---|
relation | string | How clauses combine: 'AND' (default) or 'OR'. Goes in the outer array. |
taxonomy | string | Taxonomy name. Optional when field is 'term_taxonomy_id'. |
field | string | What terms holds: 'term_id' (default), 'slug', 'name' or 'term_taxonomy_id'. |
terms | intstringarray | The term or terms to match. |
include_children | bool | Include child terms of hierarchical taxonomies. Default true. |
operator | string | 'IN' (default), 'NOT IN', 'AND', 'EXISTS' or 'NOT EXISTS'. |
$args = array(
'tax_query' => array(
'relation' => 'AND',
array(
'taxonomy' => 'color',
'field' => 'slug',
'terms' => array( 'red', 'blue' ),
),
array(
'taxonomy' => 'category',
'field' => 'slug',
'terms' => array( 'staff' ),
'include_children' => false,
'operator' => 'NOT IN',
),
),
);$args = [
'tax_query' => [
'relation' => 'AND',
[
'taxonomy' => 'color',
'field' => 'slug',
'terms' => [ 'red', 'blue' ],
],
[
'taxonomy' => 'category',
'field' => 'slug',
'terms' => [ 'staff' ],
'include_children' => false,
'operator' => 'NOT IN',
],
],
];Post & Page
Docs ↗Fetch specific posts or pages by ID, slug, title or parent.
| Parameter | Type | Description |
|---|---|---|
p | int | Post ID. |
name | string | Post slug. |
title 4.4+ | string | Post title, exact match. |
page_id | int | Page ID. |
pagename | string | Page slug. For a child page use 'parent/child'. |
attachment_id | int | Attachment ID. |
post_name__in 4.4+ | string[] | Posts with any of these slugs. |
post_parent | int | Children of this ID. Use 0 for top-level entries only. Hierarchical post types only. |
post_parent__in 3.6+ | int[] | Posts whose parent is any of these IDs. |
post_parent__not_in 3.6+ | int[] | Posts whose parent is none of these IDs. |
post__in | int[] | Only these post IDs. Sticky posts are still prepended unless ignore_sticky_posts is set. |
post__not_in | int[] | Exclude these post IDs. Must be an array; a comma-separated string does not work. |
menu_order | int | Posts with exactly this menu order. |
$args = array(
'post_name__in' => array( 'staff-picks-for-summer', 'hello-world', 'cooking-with-cast-iron' ),
'orderby' => 'post_name__in',
);$args = [
'post_name__in' => [ 'staff-picks-for-summer', 'hello-world', 'cooking-with-cast-iron' ],
'orderby' => 'post_name__in',
];Password
Docs ↗Filter by whether posts are password protected.
| Parameter | Type | Description |
|---|---|---|
has_password 3.9+ | boolnull | true for posts with a password, false for posts without, null for both. |
post_password 3.9+ | string | Posts with this exact password. Takes precedence over has_password. |
$args = array(
'has_password' => false,
);$args = [
'has_password' => false,
];Post Type
Docs ↗Choose which post types to return.
| Parameter | Type | Description |
|---|---|---|
post_type | stringstring[] | A post type or an array of them. Default 'post', or 'any' when tax_query is set. |
Values
post- A post.
page- A page.
revision- A revision.
attachment- Media. Attachments use the
'inherit'status, so setpost_statusto'inherit'or'any'. nav_menu_item- A classic navigation menu item.
wp_block- A synced pattern (reusable block).
wp_template- A block template.
wp_template_part- A block template part.
wp_navigation- A navigation block menu.
any- Every type except revisions and types with
exclude_from_search. Cannot be used inside an array.
$args = array(
'post_type' => 'attachment',
'post_status' => 'inherit',
'post_mime_type' => 'image',
);$args = [
'post_type' => 'attachment',
'post_status' => 'inherit',
'post_mime_type' => 'image',
];Post Status
Docs ↗Choose which statuses to return.
| Parameter | Type | Description |
|---|---|---|
post_status | stringstring[] | A status or an array of them. Default 'publish', plus 'private' for users who can read private posts. |
Values
publish- Published.
pending- Pending review.
draft- Draft.
auto-draft- Newly created, no content yet.
future- Scheduled.
private- Visible only to users with the right capability.
inherit- Revisions and attachments.
trash- In the trash.
any- Every status except
'trash'and'auto-draft'. Cannot be used inside an array.
$args = array(
'post_status' => array( 'draft', 'future' ),
);$args = [
'post_status' => [ 'draft', 'future' ],
];Comment
Docs ↗Filter by comment count or discussion settings.
| Parameter | Type | Description |
|---|---|---|
comment_count 4.9+ | intarray | An integer matches that exact count. An array takes 'value' and 'compare' (=, !=, >, >=, <, <=). |
comment_status 4.5+ | string | 'open' or 'closed'. |
ping_status 4.5+ | string | 'open' or 'closed'. |
comments_per_page | int | Comments per page on singular views. Defaults to the comments_per_page option. |
$args = array(
'comment_count' => array(
'value' => 10,
'compare' => '>=',
),
);$args = [
'comment_count' => [
'value' => 10,
'compare' => '>=',
],
];Pagination
Docs ↗Control how many posts are returned and which page of them.
| Parameter | Type | Description |
|---|---|---|
posts_per_page | int | Posts per page. Use -1 for all. In feeds this is replaced by the posts_per_rss option. |
nopaging | bool | Return all posts, no paging. Default false. |
paged | int | Page number, usually get_query_var( 'paged' ). |
page | int | Page number on a static front page. Also the page of a post split with <!--nextpage-->. |
posts_per_archive_page | int | Overrides posts_per_page when is_archive() or is_search() is true. |
offset | int | Number of posts to skip. |
ignore_sticky_posts 3.1+ | bool | Stop sticky posts being moved to the front. They still appear in their natural position. Default false. |
$args = array(
'posts_per_page' => 10,
'paged' => max( 1, get_query_var( 'paged' ) ),
);$args = [
'posts_per_page' => 10,
'paged' => max( 1, get_query_var( 'paged' ) ),
];Order & Orderby
Docs ↗Sort the results.
| Parameter | Type | Description |
|---|---|---|
order | string | 'DESC' (default) or 'ASC'. |
orderby | stringarray | One value, several separated by spaces, or an array of field => direction pairs (since 4.0). Default 'date', or 'relevance' when searching. |
meta_type | string | Cast applied to meta_key values when sorting by 'meta_value'. Same types as meta_query. |
orderby values
none- No order.
ID- Post ID. Note the capitals.
author- Author ID. Also
'post_author'. title- Title. Also
'post_title'. name- Slug. Also
'post_name'. type- Post type. Also
'post_type'. date- Publish date. Also
'post_date'. modified- Last modified date. Also
'post_modified'. parent- Parent ID. Also
'post_parent'. rand- Random.
'RAND(5)'uses a seed (since 4.5). Slow on large tables. comment_count- Number of comments.
relevance- Search relevance: full phrase, then all terms in title, then any term in title, then phrase in content.
menu_order- Page order, then attachment order.
meta_value- Value of
meta_key, sorted as text unlessmeta_typeis set. meta_value_num- Value of
meta_key, sorted as a number. post__in- Keep the order of the
post__inarray. Ignoresorder. post_name__in- Keep the order of the
post_name__inarray (since 4.6). post_parent__in- Keep the order of the
post_parent__inarray (since 4.6). clause key- The key of a named
meta_queryclause (since 4.2).
$args = array(
'orderby' => array(
'menu_order' => 'ASC',
'title' => 'DESC',
),
);$args = [
'orderby' => [
'menu_order' => 'ASC',
'title' => 'DESC',
],
];$args = array(
'meta_key' => 'price',
'orderby' => 'meta_value_num',
'order' => 'ASC',
);$args = [
'meta_key' => 'price',
'orderby' => 'meta_value_num',
'order' => 'ASC',
];Date
Docs ↗Filter by publish or modified date, from simple values to full date ranges.
| Parameter | Type | Description |
|---|---|---|
year | int | Four-digit year. |
monthnum | int | Month, 1 to 12. |
w | int | Week of the year, 0 to 53. Depends on the start_of_week option. |
day | int | Day of the month, 1 to 31. |
hour | int | Hour, 0 to 23. |
minute | int | Minute, 0 to 59. |
second | int | Second, 0 to 59. |
m | int | Year and month together, e.g. 202611. |
date_query 3.7+ | array | An array of date clauses. Clauses can be nested. |
Keys inside date_query
| Parameter | Type | Description |
|---|---|---|
relation | string | 'AND' (default) or 'OR'. Top level only. |
column | string | Column to compare: 'post_date' (default), 'post_date_gmt', 'post_modified', 'post_modified_gmt'. Top level or per clause. |
after | stringarray | A strtotime() string, or an array of year, month, day. |
before | stringarray | A strtotime() string, or an array of year, month, day. |
inclusive | bool | Include the exact after and before dates. Default false. |
year, month, week, day | intint[] | Calendar parts: month 1–12, week 1–53, day 1–31. |
dayofyear | intint[] | Day of the year, 1 to 366. |
dayofweek | intint[] | Day of the week, 1 (Sunday) to 7. |
dayofweek_iso 4.1+ | intint[] | ISO day of the week, 1 (Monday) to 7. |
hour, minute, second | intint[] | Time parts: 0–23, 0–59, 0–59. |
compare | string | = (default), !=, >, >=, <, <=, IN, NOT IN, BETWEEN, NOT BETWEEN. Array values need one of the last four. |
$args = array(
'date_query' => array(
array(
'after' => '2025-01-01',
'before' => '2025-12-31',
'inclusive' => true,
),
),
);$args = [
'date_query' => [
[
'after' => '2025-01-01',
'before' => '2025-12-31',
'inclusive' => true,
],
],
];$args = array(
'date_query' => array(
'relation' => 'AND',
array(
'dayofweek' => array( 1, 7 ),
'compare' => 'IN',
),
array(
'after' => '2025-01-01',
),
),
);$args = [
'date_query' => [
'relation' => 'AND',
[
'dayofweek' => [ 1, 7 ],
'compare' => 'IN',
],
[
'after' => '2025-01-01',
],
],
];Custom Field
Docs ↗Filter by post meta, with simple keys or a full meta_query.
| Parameter | Type | Description |
|---|---|---|
meta_key | stringstring[] | Meta key or keys. |
meta_value | stringstring[] | Meta value or values. |
meta_compare | string | Operator for meta_value. Same values as compare below. Default '=', or 'IN' for an array. |
meta_compare_key 5.1+ | string | Operator for meta_key. Same values as compare_key below. |
meta_type | string | Cast for meta_value. Same values as type below. |
meta_type_key 5.3+ | string | Cast for meta_key. Only 'BINARY'. |
meta_query 3.1+ | array | An array of meta clauses. Clauses can be nested and named. |
Keys inside meta_query
| Parameter | Type | Description |
|---|---|---|
relation | string | 'AND' (default) or 'OR'. |
key | stringstring[] | Meta key or keys. |
value | stringstring[] | Value or values. Leave it out for EXISTS and NOT EXISTS. Arrays only work with IN, NOT IN, BETWEEN, NOT BETWEEN. |
compare | string | = (default), !=, >, >=, <, <=, LIKE, NOT LIKE, IN, NOT IN, BETWEEN, NOT BETWEEN, REGEXP, NOT REGEXP, RLIKE, EXISTS, NOT EXISTS. |
type | string | 'CHAR' (default), 'NUMERIC', 'BINARY', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'. DECIMAL and NUMERIC accept precision, e.g. 'DECIMAL(10,2)'. |
compare_key 5.1+ | string | Operator for the key: =, !=, LIKE, NOT LIKE, IN, NOT IN, REGEXP, NOT REGEXP, RLIKE, EXISTS, NOT EXISTS. |
type_key 5.3+ | string | Cast for the key. Only 'BINARY', for case-sensitive regex. |
$args = array(
'meta_query' => array(
'relation' => 'AND',
array(
'key' => 'color',
'value' => 'blue',
),
'price_clause' => array(
'key' => 'price',
'value' => array( 1, 200 ),
'type' => 'NUMERIC',
'compare' => 'BETWEEN',
),
),
'orderby' => 'price_clause',
'order' => 'ASC',
);$args = [
'meta_query' => [
'relation' => 'AND',
[
'key' => 'color',
'value' => 'blue',
],
'price_clause' => [
'key' => 'price',
'value' => [ 1, 200 ],
'type' => 'NUMERIC',
'compare' => 'BETWEEN',
],
],
'orderby' => 'price_clause',
'order' => 'ASC',
];Permission
Docs ↗Include private posts when the current user may see them.
| Parameter | Type | Description |
|---|---|---|
perm | string | 'readable' or 'editable'. |
$args = array(
'post_status' => array( 'publish', 'private', 'draft' ),
'perm' => 'editable',
);$args = [
'post_status' => [ 'publish', 'private', 'draft' ],
'perm' => 'editable',
];Mime Type
Docs ↗Filter attachments by file type.
| Parameter | Type | Description |
|---|---|---|
post_mime_type | stringstring[] | Mime type or types. A bare type such as 'image' matches every subtype. |
$args = array(
'post_type' => 'attachment',
'post_status' => 'inherit',
'post_mime_type' => array(
'application/pdf',
'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
),
);$args = [
'post_type' => 'attachment',
'post_status' => 'inherit',
'post_mime_type' => [
'application/pdf',
'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
],
];Caching
Docs ↗Trade cache priming for speed when you don't need the extra data.
| Parameter | Type | Description |
|---|---|---|
cache_results | bool | Cache post objects and, since 6.1, the query result itself. Default true. |
update_post_meta_cache | bool | Prime the meta cache. Turn off if you won't read meta. Default true. |
update_post_term_cache | bool | Prime the term cache. Turn off if you won't read terms. Default true. |
update_menu_item_cache 6.1+ | bool | Prime caches for the objects nav menu items point to. Default false. |
lazy_load_term_meta 4.6+ | bool | Prime term meta lazily. Defaults to update_post_term_cache. |
no_found_rows | bool | Skip counting total rows. Faster, but found_posts and max_num_pages become 0, so pagination stops working. Default false. |
$args = array(
'fields' => 'ids',
'no_found_rows' => true,
'update_post_meta_cache' => false,
'update_post_term_cache' => false,
);$args = [
'fields' => 'ids',
'no_found_rows' => true,
'update_post_meta_cache' => false,
'update_post_term_cache' => false,
];Search
Docs ↗Search post content, with control over columns and matching.
| Parameter | Type | Description |
|---|---|---|
s | string | Search terms. Prefix a term with - to exclude it: 'pillow -sofa'. The prefix can be changed with the wp_query_search_exclusion_prefix filter. |
search_columns 6.2+ | string[] | Columns to search: 'post_title', 'post_excerpt', 'post_content'. Default all three. |
exact | bool | Match the whole field, without wildcards. Default false. |
sentence | bool | Search the input as one phrase instead of separate terms. Default false. |
$args = array(
's' => 'pillow -sofa',
'search_columns' => array( 'post_title' ),
);$args = [
's' => 'pillow -sofa',
'search_columns' => [ 'post_title' ],
];Return Fields
Docs ↗Return lighter results than full post objects.
| Parameter | Type | Description |
|---|---|---|
fields | string | What to return. Anything other than the values below returns full post objects. |
Values
''- Full
WP_Postobjects. Default. ids- An array of post IDs.
id=>parent- From
get_posts()or$query->query(): parent IDs keyed by post ID. In$query->posts: objects with onlyIDandpost_parent.
$ids = get_posts( array(
'post_type' => 'page',
'fields' => 'ids',
'nopaging' => true,
) );$ids = get_posts( [
'post_type' => 'page',
'fields' => 'ids',
'nopaging' => true,
] );Filters
Docs ↗Hook into the SQL that WP_Query builds.
| Parameter | Type | Description |
|---|---|---|
suppress_filters | bool | Skip the posts_* SQL filters. Default false, but get_posts() sets it to true. |
Common filters
posts_where- Change the WHERE clause.
posts_join- Change the JOIN clause.
posts_orderby- Change the ORDER BY clause.
posts_clauses- Change all clauses at once.
posts_pre_query- Return posts yourself and skip the database.
found_posts- Adjust the total, for example after using
offset.
No parameters match that filter.
One-file version
Download ↓Download ↓Every top-level parameter in one PHP array with a sample value and a one-line note, for pasting into your editor. It's a reference, not a query to run as-is.
Show the file
<?php
/**
* WP_Query Cheat Sheet: every WP_Query parameter in one file.
* Checked against WordPress 7.1. https://clearanceclarence-software.github.io/wp-query-cheat-sheet/
*
* Every top-level parameter with a sample value. This is a reference,
* not a query to run as-is: many of these contradict each other.
* Nested arrays are shown in full on the site.
*
* Inspired by wp-query-ref by luetkemj: https://github.com/luetkemj/wp-query-ref
*/
$args = array(
// Author: Show posts by, or not by, certain authors.
// https://developer.wordpress.org/reference/classes/wp_query/#author-parameters
'author' => '1,2,3', // (int|string) Author ID, or a comma-separated list of IDs. Prefix an ID with - to exclude it: '-1,-2'.
'author_name' => 'jane', // (string) The author's user_nicename, not their display name.
'author__in' => array( 2, 6 ), // (int[]) Posts by any of these author IDs. Since 3.7.
'author__not_in' => array( 2, 6 ), // (int[]) Posts by none of these author IDs. Since 3.7.
// Category: Show posts in, or not in, certain categories.
// https://developer.wordpress.org/reference/classes/wp_query/#category-parameters
'cat' => 5, // (int|string) Category ID, children included. Comma-separate several IDs; prefix with - to exclude: '-12,-34'.
'category_name' => 'staff,news', // (string) Category slug, children included. 'staff,news' matches any; 'staff+news' matches all.
'category__and' => array( 2, 6 ), // (int[]) Posts in all of these categories.
'category__in' => array( 2, 6 ), // (int[]) Posts in any of these categories. Children are not included.
'category__not_in' => array( 2, 6 ), // (int[]) Posts in none of these categories. Children are not included.
// Tag: Show posts with, or without, certain tags.
// https://developer.wordpress.org/reference/classes/wp_query/#tag-parameters
'tag' => 'cooking', // (string) Tag slug. 'bread,baking' matches any; 'bread+baking' matches all.
'tag_id' => 5, // (int) Tag ID.
'tag__and' => array( 2, 6 ), // (int[]) Posts with all of these tag IDs.
'tag__in' => array( 2, 6 ), // (int[]) Posts with any of these tag IDs.
'tag__not_in' => array( 2, 6 ), // (int[]) Posts with none of these tag IDs.
'tag_slug__and' => array( 'red', 'blue' ), // (string[]) Posts with all of these tag slugs.
'tag_slug__in' => array( 'red', 'blue' ), // (string[]) Posts with any of these tag slugs.
// Taxonomy: Query any taxonomy, including custom ones, with boolean logic between clauses.
// https://developer.wordpress.org/reference/classes/wp_query/#taxonomy-parameters
'tax_query' => array(
'relation' => 'AND',
array(
'taxonomy' => 'color',
'field' => 'slug',
'terms' => array( 'red', 'blue' ),
),
array(
'taxonomy' => 'category',
'field' => 'slug',
'terms' => array( 'staff' ),
'include_children' => false,
'operator' => 'NOT IN',
),
), // (array) An array of clause arrays. Clauses can be nested, each with its own relation. Since 3.1.
// Post & Page: Fetch specific posts or pages by ID, slug, title or parent.
// https://developer.wordpress.org/reference/classes/wp_query/#post-page-parameters
'p' => 1, // (int) Post ID.
'name' => 'hello-world', // (string) Post slug.
'title' => 'Hello World', // (string) Post title, exact match. Since 4.4.
'page_id' => 1, // (int) Page ID.
'pagename' => 'sample-page', // (string) Page slug. For a child page use 'parent/child'.
'attachment_id' => 1, // (int) Attachment ID.
'post_name__in' => array( 'hello-world', 'sample-page' ), // (string[]) Posts with any of these slugs. Since 4.4.
'post_parent' => 0, // (int) Children of this ID. Use 0 for top-level entries only. Hierarchical post types only.
'post_parent__in' => array( 1, 2, 3 ), // (int[]) Posts whose parent is any of these IDs. Since 3.6.
'post_parent__not_in' => array( 1, 2, 3 ), // (int[]) Posts whose parent is none of these IDs. Since 3.6.
'post__in' => array( 1, 2, 3 ), // (int[]) Only these post IDs. Sticky posts are still prepended unless ignore_sticky_posts is set.
'post__not_in' => array( 4, 5 ), // (int[]) Exclude these post IDs. Must be an array; a comma-separated string does not work.
'menu_order' => 0, // (int) Posts with exactly this menu order.
// Password: Filter by whether posts are password protected.
// https://developer.wordpress.org/reference/classes/wp_query/#password-parameters
'has_password' => false, // (bool|null) true for posts with a password, false for posts without, null for both. Since 3.9.
'post_password' => 'multi-pass', // (string) Posts with this exact password. Takes precedence over has_password. Since 3.9.
// Post Type: Choose which post types to return.
// https://developer.wordpress.org/reference/classes/wp_query/#post-type-parameters
'post_type' => array( 'post', 'page' ), // (string|string[]) A post type or an array of them. Default 'post', or 'any' when tax_query is set.
// Post Status: Choose which statuses to return.
// https://developer.wordpress.org/reference/classes/wp_query/#status-parameters
'post_status' => array( 'publish', 'private' ), // (string|string[]) A status or an array of them. Default 'publish', plus 'private' for users who can read private posts.
// Comment: Filter by comment count or discussion settings.
// https://developer.wordpress.org/reference/classes/wp_query/#comment-parameters
'comment_count' => array( 'value' => 10, 'compare' => '>=' ), // (int|array) An integer matches that exact count. An array takes 'value' and 'compare' (=, !=, >, >=, <, <=). Since 4.9.
'comment_status' => 'open', // (string) 'open' or 'closed'. Since 4.5.
'ping_status' => 'open', // (string) 'open' or 'closed'. Since 4.5.
'comments_per_page' => 50, // (int) Comments per page on singular views. Defaults to the comments_per_page option.
// Pagination: Control how many posts are returned and which page of them.
// https://developer.wordpress.org/reference/classes/wp_query/#pagination-parameters
'posts_per_page' => 10, // (int) Posts per page. Use -1 for all. In feeds this is replaced by the posts_per_rss option.
'nopaging' => false, // (bool) Return all posts, no paging. Default false.
'paged' => get_query_var( 'paged' ), // (int) Page number, usually get_query_var( 'paged' ).
'page' => get_query_var( 'page' ), // (int) Page number on a static front page. Also the page of a post split with <!--nextpage-->.
'posts_per_archive_page' => 10, // (int) Overrides posts_per_page when is_archive() or is_search() is true.
'offset' => 0, // (int) Number of posts to skip.
'ignore_sticky_posts' => false, // (bool) Stop sticky posts being moved to the front. They still appear in their natural position. Default false. Since 3.1.
// Order & Orderby: Sort the results.
// https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters
'order' => 'DESC', // (string) 'DESC' (default) or 'ASC'.
'orderby' => array( 'menu_order' => 'ASC', 'date' => 'DESC' ), // (string|array) One value, several separated by spaces, or an array of field => direction pairs (since 4.0). Default 'date', or 'relevance' when searching.
'meta_type' => 'NUMERIC', // (string) Cast applied to meta_key values when sorting by 'meta_value'. Same types as meta_query.
// Date: Filter by publish or modified date, from simple values to full date ranges.
// https://developer.wordpress.org/reference/classes/wp_query/#date-parameters
'year' => 2026, // (int) Four-digit year.
'monthnum' => 4, // (int) Month, 1 to 12.
'w' => 25, // (int) Week of the year, 0 to 53. Depends on the start_of_week option.
'day' => 17, // (int) Day of the month, 1 to 31.
'hour' => 13, // (int) Hour, 0 to 23.
'minute' => 19, // (int) Minute, 0 to 59.
'second' => 30, // (int) Second, 0 to 59.
'm' => 202604, // (int) Year and month together, e.g. 202611.
'date_query' => array(
array(
'after' => '2025-01-01',
'before' => '2025-12-31',
'inclusive' => true,
),
), // (array) An array of date clauses. Clauses can be nested. Since 3.7.
// Custom Field: Filter by post meta, with simple keys or a full meta_query.
// https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
'meta_key' => 'price', // (string|string[]) Meta key or keys.
'meta_value' => '100', // (string|string[]) Meta value or values.
'meta_compare' => '>=', // (string) Operator for meta_value. Same values as compare below. Default '=', or 'IN' for an array.
'meta_compare_key' => '=', // (string) Operator for meta_key. Same values as compare_key below. Since 5.1.
'meta_type' => 'NUMERIC', // (string) Cast for meta_value. Same values as type below.
'meta_type_key' => '', // (string) Cast for meta_key. Only 'BINARY'. Since 5.3.
'meta_query' => array(
'relation' => 'AND',
array(
'key' => 'color',
'value' => 'blue',
),
'price_clause' => array(
'key' => 'price',
'value' => array( 1, 200 ),
'type' => 'NUMERIC',
'compare' => 'BETWEEN',
),
), // (array) An array of meta clauses. Clauses can be nested and named. Since 3.1.
// Permission: Include private posts when the current user may see them.
// https://developer.wordpress.org/reference/classes/wp_query/#permission-parameters
'perm' => 'readable', // (string) 'readable' or 'editable'.
// Mime Type: Filter attachments by file type.
// https://developer.wordpress.org/reference/classes/wp_query/#mime-type-parameters
'post_mime_type' => 'image', // (string|string[]) Mime type or types. A bare type such as 'image' matches every subtype.
// Caching: Trade cache priming for speed when you don't need the extra data.
// https://developer.wordpress.org/reference/classes/wp_query/#caching-parameters
'cache_results' => true, // (bool) Cache post objects and, since 6.1, the query result itself. Default true.
'update_post_meta_cache' => true, // (bool) Prime the meta cache. Turn off if you won't read meta. Default true.
'update_post_term_cache' => true, // (bool) Prime the term cache. Turn off if you won't read terms. Default true.
'update_menu_item_cache' => false, // (bool) Prime caches for the objects nav menu items point to. Default false. Since 6.1.
'lazy_load_term_meta' => true, // (bool) Prime term meta lazily. Defaults to update_post_term_cache. Since 4.6.
'no_found_rows' => false, // (bool) Skip counting total rows. Faster, but found_posts and max_num_pages become 0, so pagination stops working. Default false.
// Search: Search post content, with control over columns and matching.
// https://developer.wordpress.org/reference/classes/wp_query/#search-parameters
's' => 'pillow -sofa', // (string) Search terms. Prefix a term with - to exclude it: 'pillow -sofa'. The prefix can be changed with the wp_query_search_exclusion_prefix filter.
'search_columns' => array( 'post_title', 'post_content' ), // (string[]) Columns to search: 'post_title', 'post_excerpt', 'post_content'. Default all three. Since 6.2.
'exact' => false, // (bool) Match the whole field, without wildcards. Default false.
'sentence' => false, // (bool) Search the input as one phrase instead of separate terms. Default false.
// Return Fields: Return lighter results than full post objects.
// https://developer.wordpress.org/reference/classes/wp_query/#return-fields-parameter
'fields' => '', // (string) What to return. Anything other than the values below returns full post objects.
// Filters: Hook into the SQL that WP_Query builds.
// https://developer.wordpress.org/reference/classes/wp_query/#filters
'suppress_filters' => false, // (bool) Skip the posts_* SQL filters. Default false, but get_posts() sets it to true.
);
$query = new WP_Query( $args );<?php
/**
* WP_Query Cheat Sheet: every WP_Query parameter in one file.
* Checked against WordPress 7.1. https://clearanceclarence-software.github.io/wp-query-cheat-sheet/
*
* Every top-level parameter with a sample value. This is a reference,
* not a query to run as-is: many of these contradict each other.
* Nested arrays are shown in full on the site.
*
* Inspired by wp-query-ref by luetkemj: https://github.com/luetkemj/wp-query-ref
*/
$args = [
// Author: Show posts by, or not by, certain authors.
// https://developer.wordpress.org/reference/classes/wp_query/#author-parameters
'author' => '1,2,3', // (int|string) Author ID, or a comma-separated list of IDs. Prefix an ID with - to exclude it: '-1,-2'.
'author_name' => 'jane', // (string) The author's user_nicename, not their display name.
'author__in' => [ 2, 6 ], // (int[]) Posts by any of these author IDs. Since 3.7.
'author__not_in' => [ 2, 6 ], // (int[]) Posts by none of these author IDs. Since 3.7.
// Category: Show posts in, or not in, certain categories.
// https://developer.wordpress.org/reference/classes/wp_query/#category-parameters
'cat' => 5, // (int|string) Category ID, children included. Comma-separate several IDs; prefix with - to exclude: '-12,-34'.
'category_name' => 'staff,news', // (string) Category slug, children included. 'staff,news' matches any; 'staff+news' matches all.
'category__and' => [ 2, 6 ], // (int[]) Posts in all of these categories.
'category__in' => [ 2, 6 ], // (int[]) Posts in any of these categories. Children are not included.
'category__not_in' => [ 2, 6 ], // (int[]) Posts in none of these categories. Children are not included.
// Tag: Show posts with, or without, certain tags.
// https://developer.wordpress.org/reference/classes/wp_query/#tag-parameters
'tag' => 'cooking', // (string) Tag slug. 'bread,baking' matches any; 'bread+baking' matches all.
'tag_id' => 5, // (int) Tag ID.
'tag__and' => [ 2, 6 ], // (int[]) Posts with all of these tag IDs.
'tag__in' => [ 2, 6 ], // (int[]) Posts with any of these tag IDs.
'tag__not_in' => [ 2, 6 ], // (int[]) Posts with none of these tag IDs.
'tag_slug__and' => [ 'red', 'blue' ], // (string[]) Posts with all of these tag slugs.
'tag_slug__in' => [ 'red', 'blue' ], // (string[]) Posts with any of these tag slugs.
// Taxonomy: Query any taxonomy, including custom ones, with boolean logic between clauses.
// https://developer.wordpress.org/reference/classes/wp_query/#taxonomy-parameters
'tax_query' => [
'relation' => 'AND',
[
'taxonomy' => 'color',
'field' => 'slug',
'terms' => [ 'red', 'blue' ],
],
[
'taxonomy' => 'category',
'field' => 'slug',
'terms' => [ 'staff' ],
'include_children' => false,
'operator' => 'NOT IN',
],
], // (array) An array of clause arrays. Clauses can be nested, each with its own relation. Since 3.1.
// Post & Page: Fetch specific posts or pages by ID, slug, title or parent.
// https://developer.wordpress.org/reference/classes/wp_query/#post-page-parameters
'p' => 1, // (int) Post ID.
'name' => 'hello-world', // (string) Post slug.
'title' => 'Hello World', // (string) Post title, exact match. Since 4.4.
'page_id' => 1, // (int) Page ID.
'pagename' => 'sample-page', // (string) Page slug. For a child page use 'parent/child'.
'attachment_id' => 1, // (int) Attachment ID.
'post_name__in' => [ 'hello-world', 'sample-page' ], // (string[]) Posts with any of these slugs. Since 4.4.
'post_parent' => 0, // (int) Children of this ID. Use 0 for top-level entries only. Hierarchical post types only.
'post_parent__in' => [ 1, 2, 3 ], // (int[]) Posts whose parent is any of these IDs. Since 3.6.
'post_parent__not_in' => [ 1, 2, 3 ], // (int[]) Posts whose parent is none of these IDs. Since 3.6.
'post__in' => [ 1, 2, 3 ], // (int[]) Only these post IDs. Sticky posts are still prepended unless ignore_sticky_posts is set.
'post__not_in' => [ 4, 5 ], // (int[]) Exclude these post IDs. Must be an array; a comma-separated string does not work.
'menu_order' => 0, // (int) Posts with exactly this menu order.
// Password: Filter by whether posts are password protected.
// https://developer.wordpress.org/reference/classes/wp_query/#password-parameters
'has_password' => false, // (bool|null) true for posts with a password, false for posts without, null for both. Since 3.9.
'post_password' => 'multi-pass', // (string) Posts with this exact password. Takes precedence over has_password. Since 3.9.
// Post Type: Choose which post types to return.
// https://developer.wordpress.org/reference/classes/wp_query/#post-type-parameters
'post_type' => [ 'post', 'page' ], // (string|string[]) A post type or an array of them. Default 'post', or 'any' when tax_query is set.
// Post Status: Choose which statuses to return.
// https://developer.wordpress.org/reference/classes/wp_query/#status-parameters
'post_status' => [ 'publish', 'private' ], // (string|string[]) A status or an array of them. Default 'publish', plus 'private' for users who can read private posts.
// Comment: Filter by comment count or discussion settings.
// https://developer.wordpress.org/reference/classes/wp_query/#comment-parameters
'comment_count' => [ 'value' => 10, 'compare' => '>=' ], // (int|array) An integer matches that exact count. An array takes 'value' and 'compare' (=, !=, >, >=, <, <=). Since 4.9.
'comment_status' => 'open', // (string) 'open' or 'closed'. Since 4.5.
'ping_status' => 'open', // (string) 'open' or 'closed'. Since 4.5.
'comments_per_page' => 50, // (int) Comments per page on singular views. Defaults to the comments_per_page option.
// Pagination: Control how many posts are returned and which page of them.
// https://developer.wordpress.org/reference/classes/wp_query/#pagination-parameters
'posts_per_page' => 10, // (int) Posts per page. Use -1 for all. In feeds this is replaced by the posts_per_rss option.
'nopaging' => false, // (bool) Return all posts, no paging. Default false.
'paged' => get_query_var( 'paged' ), // (int) Page number, usually get_query_var( 'paged' ).
'page' => get_query_var( 'page' ), // (int) Page number on a static front page. Also the page of a post split with <!--nextpage-->.
'posts_per_archive_page' => 10, // (int) Overrides posts_per_page when is_archive() or is_search() is true.
'offset' => 0, // (int) Number of posts to skip.
'ignore_sticky_posts' => false, // (bool) Stop sticky posts being moved to the front. They still appear in their natural position. Default false. Since 3.1.
// Order & Orderby: Sort the results.
// https://developer.wordpress.org/reference/classes/wp_query/#order-orderby-parameters
'order' => 'DESC', // (string) 'DESC' (default) or 'ASC'.
'orderby' => [ 'menu_order' => 'ASC', 'date' => 'DESC' ], // (string|array) One value, several separated by spaces, or an array of field => direction pairs (since 4.0). Default 'date', or 'relevance' when searching.
'meta_type' => 'NUMERIC', // (string) Cast applied to meta_key values when sorting by 'meta_value'. Same types as meta_query.
// Date: Filter by publish or modified date, from simple values to full date ranges.
// https://developer.wordpress.org/reference/classes/wp_query/#date-parameters
'year' => 2026, // (int) Four-digit year.
'monthnum' => 4, // (int) Month, 1 to 12.
'w' => 25, // (int) Week of the year, 0 to 53. Depends on the start_of_week option.
'day' => 17, // (int) Day of the month, 1 to 31.
'hour' => 13, // (int) Hour, 0 to 23.
'minute' => 19, // (int) Minute, 0 to 59.
'second' => 30, // (int) Second, 0 to 59.
'm' => 202604, // (int) Year and month together, e.g. 202611.
'date_query' => [
[
'after' => '2025-01-01',
'before' => '2025-12-31',
'inclusive' => true,
],
], // (array) An array of date clauses. Clauses can be nested. Since 3.7.
// Custom Field: Filter by post meta, with simple keys or a full meta_query.
// https://developer.wordpress.org/reference/classes/wp_query/#custom-field-post-meta-parameters
'meta_key' => 'price', // (string|string[]) Meta key or keys.
'meta_value' => '100', // (string|string[]) Meta value or values.
'meta_compare' => '>=', // (string) Operator for meta_value. Same values as compare below. Default '=', or 'IN' for an array.
'meta_compare_key' => '=', // (string) Operator for meta_key. Same values as compare_key below. Since 5.1.
'meta_type' => 'NUMERIC', // (string) Cast for meta_value. Same values as type below.
'meta_type_key' => '', // (string) Cast for meta_key. Only 'BINARY'. Since 5.3.
'meta_query' => [
'relation' => 'AND',
[
'key' => 'color',
'value' => 'blue',
],
'price_clause' => [
'key' => 'price',
'value' => [ 1, 200 ],
'type' => 'NUMERIC',
'compare' => 'BETWEEN',
],
], // (array) An array of meta clauses. Clauses can be nested and named. Since 3.1.
// Permission: Include private posts when the current user may see them.
// https://developer.wordpress.org/reference/classes/wp_query/#permission-parameters
'perm' => 'readable', // (string) 'readable' or 'editable'.
// Mime Type: Filter attachments by file type.
// https://developer.wordpress.org/reference/classes/wp_query/#mime-type-parameters
'post_mime_type' => 'image', // (string|string[]) Mime type or types. A bare type such as 'image' matches every subtype.
// Caching: Trade cache priming for speed when you don't need the extra data.
// https://developer.wordpress.org/reference/classes/wp_query/#caching-parameters
'cache_results' => true, // (bool) Cache post objects and, since 6.1, the query result itself. Default true.
'update_post_meta_cache' => true, // (bool) Prime the meta cache. Turn off if you won't read meta. Default true.
'update_post_term_cache' => true, // (bool) Prime the term cache. Turn off if you won't read terms. Default true.
'update_menu_item_cache' => false, // (bool) Prime caches for the objects nav menu items point to. Default false. Since 6.1.
'lazy_load_term_meta' => true, // (bool) Prime term meta lazily. Defaults to update_post_term_cache. Since 4.6.
'no_found_rows' => false, // (bool) Skip counting total rows. Faster, but found_posts and max_num_pages become 0, so pagination stops working. Default false.
// Search: Search post content, with control over columns and matching.
// https://developer.wordpress.org/reference/classes/wp_query/#search-parameters
's' => 'pillow -sofa', // (string) Search terms. Prefix a term with - to exclude it: 'pillow -sofa'. The prefix can be changed with the wp_query_search_exclusion_prefix filter.
'search_columns' => [ 'post_title', 'post_content' ], // (string[]) Columns to search: 'post_title', 'post_excerpt', 'post_content'. Default all three. Since 6.2.
'exact' => false, // (bool) Match the whole field, without wildcards. Default false.
'sentence' => false, // (bool) Search the input as one phrase instead of separate terms. Default false.
// Return Fields: Return lighter results than full post objects.
// https://developer.wordpress.org/reference/classes/wp_query/#return-fields-parameter
'fields' => '', // (string) What to return. Anything other than the values below returns full post objects.
// Filters: Hook into the SQL that WP_Query builds.
// https://developer.wordpress.org/reference/classes/wp_query/#filters
'suppress_filters' => false, // (bool) Skip the posts_* SQL filters. Default false, but get_posts() sets it to true.
];
$query = new WP_Query( $args );