Title: posts_clauses
Published: April 25, 2014
Last modified: February 24, 2026

---

# apply_filters_ref_array( ‘posts_clauses’, string[] $clauses, WP_Query $query )

## In this article

 * [Description](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#parameters)
 * [More Information](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#more-information)
 * [Source](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#changelog)
 * [User Contributed Notes](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#user-contributed-notes)

[ Back to top](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#wp--skip-link--target)

Filters all query clauses at once, for convenience.

## 󠀁[Description](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#description)󠁿

Covers the WHERE, GROUP BY, JOIN, ORDER BY, DISTINCT, fields (SELECT), and LIMIT
clauses.

## 󠀁[Parameters](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#parameters)󠁿

 `$clauses`string[]

Associative array of the clauses for the query.

 * `where` string
 * The WHERE clause of the query.
 * `groupby` string
 * The GROUP BY clause of the query.
 * `join` string
 * The JOIN clause of the query.
 * `orderby` string
 * The ORDER BY clause of the query.
 * `distinct` string
 * The DISTINCT clause of the query.
 * `fields` string
 * The SELECT clause of the query.
 * `limits` string
 * The LIMIT clause of the query.

`$query`[WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)

The [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/) instance(
passed by reference).

## 󠀁[More Information](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#more-information)󠁿

The `posts_clauses` filter runs before the query gets executed and is essentially
the sum of all filters that run immediately before it. So it should be used if you
don’t intend to let another plugin override it, or if you need to alter several 
different parts of the query at once. If you’re only modifying a particular clause,
you should probably use one of these clause-specific filters:

    ```php
    * posts_where_paged
    * posts_groupby
    * posts_join_paged
    * posts_orderby
    * posts_distinct
    * post_limits
    * posts_fields
    ```

Note: If you’re working on a caching plugin, use the [posts_clauses_request](https://developer.wordpress.org/reference/hooks/posts_clauses_request/)
filter instead. It’s basically the same filter, but it runs later (and after [posts_selection](https://developer.wordpress.org/reference/hooks/posts_selection/)),
specifically so that “regular” plugins can execute their filters _before_ your caching
plugin does anything.

## 󠀁[Source](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#source)󠁿

    ```php
    $clauses = (array) apply_filters_ref_array( 'posts_clauses', array( compact( $pieces ), &$this ) );
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/class-wp-query.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/class-wp-query.php#L3020)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/class-wp-query.php#L3020-L3020)

## 󠀁[Related](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#related)󠁿

| Used by | Description | 
| [WP_Query::get_posts()](https://developer.wordpress.org/reference/classes/wp_query/get_posts/)`wp-includes/class-wp-query.php` |

Retrieves an array of posts based on query variables.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#changelog)󠁿

| Version | Description | 
| [3.1.0](https://developer.wordpress.org/reference/since/3.1.0/) | Introduced. |

## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#user-contributed-notes)󠁿

 1.   [Skip to note 2 content](https://developer.wordpress.org/reference/hooks/posts_clauses/?output_format=md#comment-content-4529)
 2.    [Steven Lin](https://profiles.wordpress.org/stevenlinx/)  [  5 years ago  ](https://developer.wordpress.org/reference/hooks/posts_clauses/#comment-4529)
 3.  [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fhooks%2Fposts_clauses%2F%23comment-4529)
     Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fhooks%2Fposts_clauses%2F%23comment-4529)
 4.  Example migrated from Codex:
 5.  In the following example, you can see how you can inspect the current query.
 6.      ```php
         <?php
         /**
          * Alter different parts of the query
          * 
          * @param array $pieces
          * 
          * @return array $pieces
          */
         function intercept_query_clauses( $pieces )
         {
         	echo '<style>#post-clauses-dump { display: block; background-color: #777; color: #fff; white-space: pre-line; }</style>';
         	// >>>> Inspect & Debug the Query 
         	// NEVER EVER show this to anyone other than an admin user - unless you're in your local installation
         	if ( current_user_can( 'manage_options' ) )
         	{
         		$dump = var_export( $pieces, true );
         		echo "< PRE id='post-clauses-dump'>{$dump}</ PRE >";
         	}
     
         	return $pieces;
         }
         add_filter( 'posts_clauses', 'intercept_query_clauses', 20, 1 );
         ```
     
 7.  If you need to alter anything, simply set the `$pieces['whatever_part']` string
     to what you need. Be sure to use appropriate [$wpdb](https://developer.wordpress.org/reference/classes/wpdb/)
     properties and methods (e.g. `$wpdb->prefix, $wpdb->prepare()`) in your SQL to
     prevent injection attacks, handle table prefix variations, and so forth.
 8.  This would be the output on the Admin “All Posts” example.com/wp-admin/edit.php
     screen:
 9.      ```php
         array (
         	'where' => ' AND wp_posts.post_type = \'post\' AND (wp_posts.post_status = \'publish\' OR wp_posts.post_status = \'future\' OR wp_posts.post_status = \'draft\' OR wp_posts.post_status = \'pending\' OR wp_posts.post_status = \'private\')',
         	'groupby' => '',
         	'join' => '',
         	'orderby' => 'wp_posts.post_date DESC',
         	'distinct' => '',
         	'fields' => 'wp_posts.*',
         	'limits' => 'LIMIT 0, 20',
         )
         ```
     
 10.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fhooks%2Fposts_clauses%2F%3Freplytocom%3D4529%23feedback-editor-4529)

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fhooks%2Fposts_clauses%2F)
before being able to contribute a note or feedback.