Using meta_value_num in WordPress orderby queries

In this article, we’ll explore the meta_value_num option for the orderby parameter in WordPress queries. Our focus will be on understanding how meta_value_num operates, particularly in contrast to meta_value. We’ll explore its significance and demonstrate its usage through practical examples involving both WP_Query and WP_User_Query.

What is meta_value_num in WordPress

meta_value_num is a query parameter in WordPress used for sorting and comparing numeric metadata. In the WordPress database, all meta values are stored as strings by default, regardless of whether they represent text, numbers, or other data types. This default storage approach can lead to challenges when trying to sort or compare numerical data, as string comparison rules apply. meta_value_num addresses this by explicitly treating these values as numbers during query operations. When you use meta_value_num in your query, WordPress knows to interpret and handle the metadata as numeric data, enabling accurate numerical sorting and comparison. This is particularly useful for fields like prices, ratings, or any custom field where the numerical value is significant and needs to be precisely managed in your queries.

Difference between meta_value_num and meta_value

In WordPress, meta_value and meta_value_num are both used to order posts and objects based on a meta value, but they handle data types differently.

meta_value treats metadata as strings (text), making it suitable for textual data or when exact string matching is needed. However, this can lead to unexpected results with numbers, as string comparison is different from numeric comparison. For example, when using meta_value the numbers 1, 3, 4, 5, 31, 41 are sorted as 1, 3, 31, 4, 41, 5:

On the other hand, meta_value_num treats the metadata as numeric values. When applied, the database query converts the meta string values into numbers before sorting the results. Therefore, in the same example with the numbers 1, 3, 4, 5, 31, 41 we’ll get the expected result (1, 3, 4, 5, 31, 41):

Using meta_value_num in WP_Query

Here is an example of using meta_value_num in a query:

$args = array(
  'post_type' => 'product',
  'meta_key' => 'price',
  'orderby' => 'meta_value_num',
  'order' => 'ASC'
);
$query = new WP_Query($args);
$posts = $query->posts;

In this code snippet, we query posts with post type “product” and we order them by the post meta field with key “price”. We have specified the arguments array with the following keys:

• meta_key – the key by which we want to sort the returned posts result
• orderby – set to “meta_value_num”, specifies a numeric sorting
• order – set to ASC, meaning that results will be returned in ascending order

Now if we display the meta values for the price key:

wp_list_pluck($posts, 'price'); // [9, 10, 11, 99]

We’ll get the following result:

[9, 10, 11, 99]

Which is the expected sorting order for a numeric value.

Now, let’s see how the result changes if we used the meta_value ordering option instead:

$args = array(
  'post_type' => 'product',
  'meta_key' => 'price',
  'orderby' => 'meta_value',
  'order' => 'ASC'
);
$query = new WP_Query($args);
$posts = $query->posts;

wp_list_pluck($posts, 'price'); // [10, 11, 9, 99]

As you can see, the result in this case returns [10, 11, 9, 99], which is not the correct sorting order because 9 is less than 10 and 11, so the value 9 should be first. This is happening because the meta_value sorts the results alphabetically.

Using meta_value_num in WP_User_Query

In this example, we have 3 user records with an “age” meta field. The users have ages of 14, 25 and 100 respectively, and we want to retrieve these users by age in ascending order (youngest first).

Therefore, we create a WP_User_Query with meta key “age”, orderby set to “meta_value_num” and order set to “ASC”:

$args = array(
  'meta_key' => 'age',
  'orderby' => 'meta_value_num',
  'order'=> 'ASC'
);
$user_query = new WP_User_Query( $args );
$users = $user_query->get_results();

If we now print the “age” meta values of the WP_User array result:

wp_list_pluck($users, 'age');

we will get the correct sorting order, which is: 14, 25, 100. However if we used 'orderby' => 'meta_value', the ages values would have been: 100, 14, 25.

Using meta_value_num is similar to how Users Insights sorts and searches WordPress users by their numeric meta fields:

Conclusion

meta_value_num plays a vital role in WordPress queries when dealing with numeric metadata. Understanding the difference between meta_value_num and meta_value is key for developers working with numeric data. meta_value_num ensures that numeric comparisons and sorting are done accurately, making it indispensable for queries where numerical values are involved. Whether sorting posts by ratings, filtering users by numeric meta, or handling any number-based custom fields, meta_value_num provides the precision needed for effective and accurate data handling in WordPress.