Title: WP_User_Query::query
Published: April 25, 2014
Last modified: August 20, 2026

---

# WP_User_Query::query()

## In this article

 * [Source](https://developer.wordpress.org/reference/classes/wp_user_query/query/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/classes/wp_user_query/query/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/classes/wp_user_query/query/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/classes/wp_user_query/query/?output_format=md#changelog)

Executes the query, with the current variables.

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

    ```php
    public function query() {
    	global $wpdb;

    	if ( ! did_action( 'plugins_loaded' ) ) {
    		_doing_it_wrong(
    			'WP_User_Query::query',
    			sprintf(
    			/* translators: %s: plugins_loaded */
    				__( 'User queries should not be run before the %s hook.' ),
    				'<code>plugins_loaded</code>'
    			),
    			'6.1.1'
    		);
    	}

    	$qv =& $this->query_vars;

    	// Do not cache results if more than 3 fields are requested.
    	if ( is_array( $qv['fields'] ) && count( $qv['fields'] ) > 3 ) {
    		$qv['cache_results'] = false;
    	}

    	/**
    	 * Filters the users array before the query takes place.
    	 *
    	 * Return a non-null value to bypass WordPress' default user queries.
    	 *
    	 * Filtering functions that require pagination information are encouraged to set
    	 * the `total_users` property of the WP_User_Query object, passed to the filter
    	 * by reference. If WP_User_Query does not perform a database query, it will not
    	 * have enough information to generate these values itself.
    	 *
    	 * @since 5.1.0
    	 *
    	 * @param array|null    $results Return an array of user data to short-circuit WP's user query
    	 *                               or null to allow WP to run its normal queries.
    	 * @param WP_User_Query $query   The WP_User_Query instance (passed by reference).
    	 */
    	$this->results = apply_filters_ref_array( 'users_pre_query', array( null, &$this ) );

    	if ( null === $this->results ) {
    		// Beginning of the string is on a new line to prevent leading whitespace. See https://core.trac.wordpress.org/ticket/56841.
    		$this->request =
    			"SELECT {$this->query_fields}
    			 {$this->query_from}
    			 {$this->query_where}
    			 {$this->query_orderby}
    			 {$this->query_limit}";
    		$cache_value   = false;
    		$cache_key     = $this->generate_cache_key( $qv, $this->request );
    		$cache_group   = 'user-queries';
    		$last_changed  = $this->get_cache_last_changed( $qv );

    		if ( $qv['cache_results'] ) {
    			$cache_value = wp_cache_get_salted( $cache_key, $cache_group, $last_changed );
    		}
    		if ( false !== $cache_value ) {
    			$this->results     = $cache_value['user_data'];
    			$this->total_users = $cache_value['total_users'];
    		} else {

    			if ( is_array( $qv['fields'] ) ) {
    				$this->results = $wpdb->get_results( $this->request );
    			} else {
    				$this->results = $wpdb->get_col( $this->request );
    			}

    			if ( isset( $qv['count_total'] ) && $qv['count_total'] ) {
    				/**
    				 * Filters SELECT FOUND_ROWS() query for the current WP_User_Query instance.
    				 *
    				 * @since 3.2.0
    				 * @since 5.1.0 Added the `$query` parameter.
    				 *
    				 * @global wpdb $wpdb WordPress database abstraction object.
    				 *
    				 * @param string        $sql   The SELECT FOUND_ROWS() query for the current WP_User_Query.
    				 * @param WP_User_Query $query The current WP_User_Query instance.
    				 */
    				$found_users_query = apply_filters( 'found_users_query', 'SELECT FOUND_ROWS()', $this );

    				$this->total_users = (int) $wpdb->get_var( $found_users_query );
    			}

    			if ( $qv['cache_results'] ) {
    				$cache_value = array(
    					'user_data'   => $this->results,
    					'total_users' => $this->total_users,
    				);
    				wp_cache_set_salted( $cache_key, $cache_value, $cache_group, $last_changed );
    			}
    		}
    	}

    	if ( ! $this->results ) {
    		return;
    	}
    	if (
    		is_array( $qv['fields'] ) &&
    		isset( $this->results[0]->ID )
    	) {
    		foreach ( $this->results as $result ) {
    			$result->id = $result->ID;
    		}
    	} elseif ( 'all_with_meta' === $qv['fields'] || 'all' === $qv['fields'] ) {
    		if ( function_exists( 'cache_users' ) ) {
    			cache_users( $this->results );
    		}

    		$r = array();
    		foreach ( $this->results as $userid ) {
    			if ( 'all_with_meta' === $qv['fields'] ) {
    				$r[ $userid ] = new WP_User( $userid, '', $qv['blog_id'] );
    			} else {
    				$r[] = new WP_User( $userid, '', $qv['blog_id'] );
    			}
    		}

    		$this->results = $r;
    	}
    }
    ```

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

## 󠀁[Hooks](https://developer.wordpress.org/reference/classes/wp_user_query/query/?output_format=md#hooks)󠁿

 [apply_filters( ‘found_users_query’, string $sql, WP_User_Query $query )](https://developer.wordpress.org/reference/hooks/found_users_query/)

Filters SELECT FOUND_ROWS() query for the current [WP_User_Query](https://developer.wordpress.org/reference/classes/wp_user_query/)
instance.

 [apply_filters_ref_array( ‘users_pre_query’, array|null $results, WP_User_Query $query )](https://developer.wordpress.org/reference/hooks/users_pre_query/)

Filters the users array before the query takes place.

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

| Uses | Description | 
| [WP_User_Query::get_cache_last_changed()](https://developer.wordpress.org/reference/classes/wp_user_query/get_cache_last_changed/)`wp-includes/class-wp-user-query.php` |

Retrieves the last changed cache timestamp for users and optionally posts.

  | 
| [wp_cache_get_salted()](https://developer.wordpress.org/reference/functions/wp_cache_get_salted/)`wp-includes/cache-compat.php` |

Retrieves cached data if valid and unchanged.

  | 
| [wp_cache_set_salted()](https://developer.wordpress.org/reference/functions/wp_cache_set_salted/)`wp-includes/cache-compat.php` |

Stores salted data in the cache.

  | 
| [WP_User_Query::generate_cache_key()](https://developer.wordpress.org/reference/classes/wp_user_query/generate_cache_key/)`wp-includes/class-wp-user-query.php` |

Generate cache key.

  | 
| [WP_User::__construct()](https://developer.wordpress.org/reference/classes/wp_user/__construct/)`wp-includes/class-wp-user.php` |

Constructor.

  | 
| [cache_users()](https://developer.wordpress.org/reference/functions/cache_users/)`wp-includes/pluggable.php` |

Retrieves info for user lists to prevent multiple queries by [get_userdata()](https://developer.wordpress.org/reference/functions/get_userdata/) .

  | 
| [did_action()](https://developer.wordpress.org/reference/functions/did_action/)`wp-includes/plugin.php` |

Retrieves the number of times an action has been fired during the current request.

  | 
| [apply_filters_ref_array()](https://developer.wordpress.org/reference/functions/apply_filters_ref_array/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook, specifying arguments in an array.

  | 
| [wpdb::get_col()](https://developer.wordpress.org/reference/classes/wpdb/get_col/)`wp-includes/class-wpdb.php` |

Retrieves one column from the database.

  | 
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |

Retrieves the translation of $text.

  | 
| [_doing_it_wrong()](https://developer.wordpress.org/reference/functions/_doing_it_wrong/)`wp-includes/functions.php` |

Marks something as being incorrectly called.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  | 
| [wpdb::get_results()](https://developer.wordpress.org/reference/classes/wpdb/get_results/)`wp-includes/class-wpdb.php` |

Retrieves an entire SQL result set from the database (i.e., many rows).

  | 
| [wpdb::get_var()](https://developer.wordpress.org/reference/classes/wpdb/get_var/)`wp-includes/class-wpdb.php` |

Retrieves one value from the database.

  |

[Show 9 more](https://developer.wordpress.org/reference/classes/wp_user_query/query/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/classes/wp_user_query/query/?output_format=md#)

| Used by | Description | 
| [WP_User_Query::__construct()](https://developer.wordpress.org/reference/classes/wp_user_query/__construct/)`wp-includes/class-wp-user-query.php` |

Constructor.

  |

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

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

## User Contributed Notes

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