Working with the WordPress user meta query

The WordPress user meta query is a great tool for user search and segmentation. It allows us to go beyond the simple searches by username or email. With this coding tool, we’re able to retrieve users by using the WordPress meta query for any custom fields they have. Additionally, it’s possible to combine different search criteria and gather the exact information we need.

If you want to search your users, you need to get your hands dirty with the WordPress user meta query, the WP_User_Query . WP_User_Query is a PHP class for direct database search. Although it may seem complex at first, it’s very powerful when mastered. And that’s our goal today, to master the basic elements of the WordPress user meta query for custom field searches.

And although the coding path is great, we have other options. It’s possible to use plugins to greatly simplify our user search tasks. Therefore, we can use plugins such as Users Insights, to filter users based on their custom fields. It works like the WordPress meta query, but it’s a much easier approach.

Now let’s get started and play with the WordPress user query options.

Using custom fields in a WordPress User Query

Don’t be afraid if you don’t know how to code. These are just simple examples, and we go through some coding-free options afterward. But for now, we walk through how the WordPress meta query works when we are filtering users. In order to follow along, we advise you create a child theme.

Let’s get familiarized with beloved WP_User_Query class. Its inner workings are very similar to the posts query, the WP_Query. This is its basic syntax:

Now it’s time to gather all users who have a custom user field set. Thus, you find all users with that value, which can be set by another plugin or the user himself.

This code is going to return all users with the “occupation” custom field set as “developer”. This snippet is, in fact, a shorter version of this one:

There we can see the meta_compare  attribute. It is set to “=” by default, but there are a lot of different operations that you can perform with it. Thus, you can use these values:

  • ‘=’ / ‘!=’ – Exact match
  • ‘>’ / ‘>=’ / ‘<‘ / ‘<=’ – Greater than, greater than or equal to, smaller than, smaller than or equal to
  • ‘LIKE’ / ‘NOT LIKE’ – Finds partial matches for a content, inside of a string. Then, if you search for “web”, you get not just “web” but “web design” and “spiderweb” too
  • ‘IN’ / ‘NOT IN’ – Allows specifying multiple values to match
  • ‘BETWEEN’ / ‘NOT BETWEEN’ – Allows matching based on a range of values. For example, you can search for users with age between 20 and 30
  • ‘EXISTS’ / ‘NOT EXISTS’ – Just check if the meta value is set at all
  • ‘REGEXP’ / ‘RLIKE’ / ‘NOT REGEXP’ – Use regular expressions in your search (being RLIKE just another term for REGEXP)

Thus, you can not only find exact values for your custom fields but try to find values different, greater than, lower than, similar to or even use regular expressions. Following our example, we could find all users who are NOT developers with this code:

Additionally, we can combine more than one set of parameters. This is done using the meta_query  parameter and adding inside of it a relation. After that, we add each of our different parameters. For instance, we can find all developers who are from the USA and with more than 5 years of experience:

From the snippet above, we can see how different search criteria can be combined. The possible relations we can use are AND and OR. If we set it to AND, our results are going to match ALL our rules. If we set OR our results are any item that matches ANY of our rules.

Furthermore, we can use some of the more “obscure” parameters for great results in our WordPress meta query search. Let’s check again the previous example. There we look for users with a “Developer” occupation. But if we have a user who is a “PHP Developer” we won’t see him as a result. In this case, we can use the LIKE operator:

Also, we may want to check value ranges. Let’s say that in our WordPress custom user fields we have hourly rates for developers. If we want to search for a value that is within our budget, we can try the BETWEEN comparison.

Ordering by user meta

Undoubtedly, just getting our users may not be enough. Often, we need to perform a WordPress user meta query, then order our results. The WP_User_Query has an orderby parameter. And we can use it for custom fields as well.

This code is going to work fine, and it loads our users ordered by their age.

Except when it doesn’t.

The problem here is that our orderby will only work when the meta value is present in our query. And this means that we can’t order users with no values set in their custom field.

Hence, if we need to load WordPress users ordered by custom fields including empty values, we need something else. One way to solve this is simply loading all users, then using the pre_user_query action to add some extra code to the default query. In this way, our code will load all users, then we load their custom fields and order them.

Here is how that code would look like:

This code is going to load all users with their display names. Please note that the main query doesn’t include any operations to order the users by the meta fields. Then WordPress is going to apply our extra SQL query. That query is going to load the custom fields for our users and order them based on the values. In our case, we’ve used the “billing_country” custom field, but you can use any field you want.

Now let’s see a much easier approach.

Query users based on custom meta fields via Users Insights

It’s possible to use Users Insights to search and order users based on their user meta fields. In this way, you can overcome the limitations of a coding-only approach. For example, if you want to just change a search parameter, it’s much harder to do it in your code.

The first element of our search is our custom fields. Make sure you have mapped your custom user fields, and you are able to use them. Let’s revive our WordPress meta query searches with just a few clicks.

Our first scenario is simply filtering users based on their occupation. This can be done by using the Occupation filter. You can use the variations of that field to search for “contains”, “starts with”, “ends with” and others.

WordPress query users based on their occupation

When it comes to combining filters, you can use them with the AND operator in Users Insights. Therefore, to find developers from the US with more than 5 years of experience you can try this:

WordPress query users based on different parameters, occupation, country, experience

Additionally, we can add upper and lower boundaries for a range search. Like what we’ve done to find developers and their hourly rates.

FIlter users based on occupation, and hourly rate range

Furthermore, it’s possible to export our users, in case we want to contact them. You can just click the export button.

Export WordPress users filtered

Now it’s time for one of the toughest challenges we saw today: ordering. As opposed to a lot of custom code, you can simply click on the column you want to order by. That’s going to order all users based on that criterion, including users who don’t have it.

Order users by custom fields, country

 

Conclusion

Today we saw many ways to use the WordPress user query. We looked into different examples, as well as some more complex ways to filter your users. We identified the limitations of the WP_User_Query and some ways to work around it. Additionally, we walked through how Users Insights can be used for a very similar purpose.

We hope you enjoyed this article, and see you again next time!