Ultimate Guide to meta_query – Get and Order Posts by Meta Values

47 Comments

In this post I assume that you already have basic knowledge how to work with WP_Query class in WordPress. Before I begin, I want to show you some very simple examples. The similar examples you can find in WordPress Codex.

As you know all the posts have the metadata you can populate in “Custom fields” metabox (the metabox by the way can be hidden). So, for example, if you want to get a post with meta key show_on_homepage and meta value on, you can do it the following way:

$rd_args = array(
	'meta_key' => 'show_on_homepage',
	'meta_value' => 'on'
);
 
$rd_query = new WP_Query( $rd_args );

Otherwise, if you need to query all posts except the ones with this pair of meta key and value, you can use the following parameters:

$rd_args = array(
	'meta_key' => 'show_on_homepage',
	'meta_value' => 'on',
	'meta_compare' => '!='
);
 
$rd_query = new WP_Query( $rd_args );

Do not forget that all examples in this post are simplified, so, some of WP_Query parameters are missing, e.g posts_per_page or post_type.

If you are interested in other meta_compare parameter values, please look at “compare” parameter description below, because both of them accept the same values.

This was very very simple examples, just an introdution. But this post is about meta_query parameter. This parameter allows us to create a really cool post filters and search scripts.

Query Posts by a Meta Value

The simple example below allows you to get all the posts with a specific custom field value. Let’s just get all the posts with custom field name “color” and custom field value white.

// the meta_key 'color' with the meta_value 'white'
$rd_args = array(
	'meta_query' => array(
		array(
			'key' => 'color',
			'value' => 'white'
		)
	)
);
 
$rd_query = new WP_Query( $rd_args );

If you look at the post edit page (in admin area) in any post which matches the query, you will see the following in the “Custom Fields” section:

Let’s do the opposite thing – get all the posts except the ones with meta key “color” and meta value white:

$rd_args = array(
	'meta_query' => array(
		array(
			'key' => 'color',
			'value' => 'white',
			'compare' => '!='
		)
	)
);
 
$rd_query = new WP_Query( $rd_args );

Get Posts by Multiple Meta Values

Now let’s get all the posts with white OR green “color” custom field value:

// custom field name is color and custom field value is 'white' OR 'green'
$rd_args = array(
	'meta_query' => array(
		array(
			'key' => 'color',
			'value' => array('white','green'),
			'compare' => 'IN'
		)
	)
);
 
$rd_query = new WP_Query( $rd_args );

Get all the posts (products in online shop for example) except white products and green products:

$rd_args = array(
	'meta_query' => array(
		array(
			'key' => 'color',
			'value' => array('white','green'),
			'compare' => 'NOT IN'
		)
	)
);
 
$rd_query = new WP_Query( $rd_args );

How to use “compare” in meta_query

As you can see in example below and in further examples too, there is a compare parameter in every of them. Now I would like to show which values it can accept and what do they mean.

= (or not set) Equal to,
!= – Not equal to,
< – Less than,
<= – Less or equal to,
> – Greater than,
>= – Greater than or equal to, example:

// the product price in this example is 2000 or more than 2000:
$args = array(
	'meta_query' => array(
		array(
			'key' => 'price',
			'value' => 2000,
			'type' => 'numeric', // specify it for numeric values
			'compare' => '>='
		)
	)
);

LIKE – Allows to search in meta values for a specific string, in the example below the query returns all the posts where “first_name” name contains John, it can be also Johnny, Johnathan, somethingJohnsomething:

$args = array(
	'meta_query' => array(
		array(
			'key' => 'first_name',
			'value' => 'John',
			'compare' => 'LIKE'
		)
	)
);

Two more things: first – it is not case sensitive, second – wildcard symbols @ are not necessary.
NOT LIKE – similar to LIKE just works in an opposite way – meta value mustn’t contain the given string.
IN – posts meta value must contain one of the values of the given array, you can see the example above
NOT IN – meta values must not contain ANY of the values in the given array.
BETWEEN – post meta value should be between the given range of values, example:

// the product price is more than 2000 and less than 4000
$args = array(
	'meta_query' => array(
		array(
			'key' => 'price',
			'value' => array( 2000, 4000 ),
			'type' => 'numeric',
			'compare' => 'BETWEEN'
		)
	)
);

It can also work for dates, check the example below too.
NOT BETWEEN – not in a given range.
EXISTS (WordPress >= 3.5) – If meta value of a specific meta key exists or empty / null.

$args = array(
	'meta_query' => array(
		array(
			'key' => 'misha_key',
			'compare' => 'EXISTS'
		)
	)
);

So, actually it checks if a meta key exists, you do not even have to pass any value with this parameter.
NOT EXISTS (WordPress >= 3.5) – if a given meta key doesn’t exist at all
REGEXP (WordPress >= 3.7) – it allows you to compare meta values with regular expression, example:

$args = array(
	'meta_query' => array(
		array(
			'key' => 'misha_key',
			'value' => '^[0-9]*$', // "misha_key" must be only numbers
			'compare' => 'REGEXP'
		)
	)
);

NOT REGEXP (WordPress >= 3.7) – Similar to REGEXP but meta values must not match your given regular expression
RLIKE (WordPress >= 3.7) – it is the synonym to REGEXP

How to Use “compare => between” for Dates in meta_query

You can also use meta_query to check if a custom field is between two dates.

The most important thing you have to keep in mind is that your date format should be like YYYY-MM-DD or YYYY/MM/DD or something like that (year goes first, then month, then day, then time if you need it too). Check how it is stored in database – if it is stored in another format, for example days go first, then filtering won’t work for you until you change dates presence in database.

array(
	'key' => 'sale_day',
	'value' => array( '2018-01-01', '2018-01-09' ),
	'compare' => 'BETWEEN'
)

If the date is stored in UNIX time, example: 1543391233, everything became super simple:

array(
	'key' => 'sale_day',
	'value' => array( strtotime('2018-01-01'), strtotime('2018-01-09') ),
	'type' => 'numeric',
	'compare' => 'BETWEEN'
)

Multiple meta queries – get posts by multiple pairs of keys and values

Now I will show you how to combine posts by several (two or more) custom field values. First of all let me introduce you relation parameter which can accept two vaues – OR or AND (default).

// the 'color' is 'white' AND the 'price' is more than 2000 and less than 4000
$rd_query = new WP_Query( array(
	'meta_query' => array(
		'relation' => 'AND', // both of below conditions must match
		array(
			'key' => 'show_on_homepage',
			'value' => 'on'
		),
		array(
			'relation' => 'OR', // only 'color' OR 'price' must match
			array(
				'key' => 'color',
				'value' => 'white'
			),
			array(
				'key' => 'price',
				'value' => array( 2000, 4000 ),
				'type' => 'numeric',
				'compare' => 'BETWEEN'
			)
		)
	)
) );

As you can see, in meta_query above we used multiple relation.

How to Sort Posts by Meta Values (“orderby” and “order” parameters)

I will show you different examples of how you can order your posts by meta values. First of all, look at this simple code sample, where we don’t even use meta query:

$args = array(
	'meta_key' => 'misha_key',
	'orderby' => 'meta_value'
);

Now, let’s say that misha_key contains only numeric values, we can change our code for that case just a little bit.

$args = array(
	'meta_key' => 'misha_key',
	'orderby' => 'meta_value_num'
);

But how to use it together with meta query? Simple, just change our code the following way:

$args = array(
	'meta_query' => array(
		'misha_clause' => array(
			'key' => 'misha_key',
			'compare' => 'EXIST'
		)
	),
	'orderby' => 'misha_clause'
);

How to Order by Two and More Meta Keys

Yes, it is also possible since WordPress 4.2

$args = array(
	'meta_query' => array(
		'relation' => 'AND',
		'price_clause' => array(
			'key' => 'price',
			'value' => array( 2000, 4000 ),
			'type' => 'numeric',
			'compare' => 'BETWEEN'
		),
		'misha_clause' => array(
			'key' => 'misha_key',
			'compare' => 'EXISTS'
		), 
	),
	'orderby' => array(
		'price_clause' => 'ASC',
		'misha_clause' => 'DESC'
	),
);

So, first of all we order posts by price_clause ascending and then we order posts by misha_clause descending.

Misha Rudrastyh

I develop websites since 2008, so it is total of 13 years of experience, oh my gosh. Most of all I love love love to create websites with WordPress and Gutenberg, some ideas and thoughts I share throughout my blog.

Need some developer help? Contact me

function product_listing_function($atts) { extract(shortcode_atts( array( 'color' => '', 'price' => '', ), $atts ) ); $rd_args = array( 'meta_query' => array( 'relation' => 'AND', array( 'key' => 'color', 'value' => $color ), array( 'key' => 'price', 'value' => $price, 'type' => 'numeric' ) ) ); $rd_query = new WP_Query( $rd_args ); } add_shortcode( 'product_list', 'product_listing_function' );

$args = array ( 'post_type' => 'tour', 'meta_query'=> array( array( 'key' => 'trav_tour_city', 'compare' => 'LIKE', 'value' => $term->term_id, ) ), 'meta_key' => 'trav_tour_city', );

$query = array ( 'post_type' => 'clients', 'meta_query'=> array( 'relation' => 'OR', array( 'key' => 'cupom', 'value' => $idCupom, 'compare' => '!=', ), array( 'key' => 'cupom', 'compare' => 'NOT EXISTS', 'value' => '', )), 'posts_per_page' => -1, );

$args = array( 'post_type' => array('post', 'my_cpt1', 'my_cpt2'), 'post_status' => 'publish', 'meta_query' => array( 'relation' => 'AND', 'my_order' => array( 'key' => 'my_meta_date', 'orderby' => 'meta_value', 'order' => 'DESC' ), array( 'key' => 'my_meta_name', 'value' => $post -> post_title ) ), 'orderby' => 'my_order' );

$args = array( ... 'meta_query' => array( array( 'key' => 'my_meta_name', 'value' => $post->post_title, ), 'my_order' => array( 'key' => 'my_meta_date', 'compare' => 'EXISTS', ), ), 'orderby' => 'my_order', 'order' => 'DESC', );

Comments — 47

Kurt

13 Jan 2014 #

I’m trying to figure out how I would wrap a short code function around your code sample so that the admin could put in their own values to filter the meta content displayed on a page

function product_listing_function($atts) {
	 
	 extract(shortcode_atts( array(
		'color' => '',
		'price' => '',
		), $atts
	)
);
}
add_shortcode( 'product_list', 'product_listing_function' );

[product_list color=”white” price=”100″]

I can’t seem to get the values to pass into the meta_query array? Could you please share an example of this.

Thank You

Misha

14 Jan 2014 #

I hope it helps.

Ryan 14 Jun 2014 #
Hi man,

This seems like some nice clear examples of the WP_Query. I was working with the WP_Meta_Query and wondered how it was possible to just query for all values under a particular meta key. Say for example you have a custom field called member_city, and many posts use this to give location informations such as “This user is from London”.

What I’m actually trying to do is kind of hard to explain. I’m trying to get all custom meta data from the database, i.e all the cities, then output them into an array which can be used to generate a drop down menu that users can then select from to search users by location. I also don’t want this to duplicate cities, i.e if two people are from London, I don’t want London in the list twice. I’m using WordPress Advanced Search by Growth Spark for my search.

I’m able to query the database and get an output such as:
```
INNER JOIN rm_postmeta ON (rm_posts.ID = rm_postmeta.post_id)
     AND ( (rm_postmeta.meta_key = 'member_city' AND CAST(rm_postmeta.meta_value AS CHAR) IN    ('London')) )
```
I just don’t know how to extract that information, then get it into my drop down. Does this make sense to you? May be confusing without code examples and understanding of the site architecture.
Salvatore Capolupo 2 Jan 2015 #

Fine and useful examples, happy new year!

riteshiz 27 Mar 2015 #

Thanks a lot !!!

- Misha 27 Mar 2015 #
  
  You are welcome!
  
Juankql 29 May 2015 #

Hi, i found this examples very good, but i have a doubt, what if i want to order by a metabox value. For example, I have a custom post type named team_member and this post-type have a metabox named order, later in the loop, i need query the post but ordering by this order that i defined in the metabox, How i could do this?
Thanks in advance.
Please sorry my english….

- Misha 30 May 2015 #
  Hi,
  WP_Query supports the orderby parameter, so it should look like this:
```
$args = array(
	'meta_key'=>'key_of_the_metabox_field',
	'orderby'=>'meta_value',
	'order'=> 'ASC' // or DESC
);
```
Juankql 30 May 2015 #

thanks Misha, I try your code, but instead ‘orderby’=>’meta_value’ I used ‘orderby’=>’meta_value_num’ and it’s working perfect!!!! Thanks a lot for the answer.
Regards
Juankql

Rtchie Matos 27 Jun 2016 #

I just want to thank you for all the examples you’ve posted. It has given me some way to be able to start off with the project I’m doing, based on a query on premium post listing. Again, thank you.

deks 29 Jun 2016 #

I have a key that has 2 meta options: “id”:”12345″ , and “select new”

How can i return only the first? (the ome with the id?

- Misha 30 Jun 2016 #
  
  Let me clarify — you have two meta values with the same key and you want to get posts with the first value only, is that right?
  
  - deks 30 Jun 2016 #
    
    thanks @Misha for your reply :)
    
    yes, the key is the same and i want to get in return only {“id”:”12345″} << which comes like this (including the ' " ' charachter and the ' : '.)
    
    thanks !
    
    - Misha 30 Jun 2016 #
      
      I hope it helps :)
      
      $args = array( 'meta_query' => array( 'key' => 'YOUR_KEY_NAME', 'value' => '{"id":"12345"}' ) );
      
deks 30 Jun 2016 #

sure did!

thank you very much :)

Ivan Lemus 1 Aug 2017 #
Hi Misha, thanks for this info…. and since you seem to be very proficient in Wp_Query… Can I pick your brain a little bit and ask for your help:

I need to display posts (tours) that are in a specific location (city) so in my location_taxonomy.php I have a meta query in the form of:
```
$args = array(
  'post_type'     => 'tour',
  'meta_key'      => 'trav_tour_city',
  'meta_value'    => $term->term_id,
);
```
When the key stored in the tour has only one value (one city), it displays the posts. When the key has more than one value (multiple cities or a string of ids separated by commas), it doesn’t.

How can I change the $args so the query would determine that the current city ($term->term_id) exists within the comma separated values stored as a string in ‘trav_tour_city’?

I have tried something in the line of:
```
$args = array(
  array(
	'post_type'   => 'tour',
	 'meta_query' => array(
	  array(
		'key'=> 'trav_tour_city',
		'value'   => $term->term_id, 
		'compare' => 'LIKE',
	  ),
	),
	),
); 
```
and also I tried “LIKE”, but obviously I don’t know what I’m doing… haha..

any help would be greatly appreciated!

Regards,

Ivan
- Misha 2 Aug 2017 #
  Hi Ivan,
  
  LIKE should help:
```
'meta_query' => array(
	array(
		'key'=> 'trav_tour_city',
		'value'   => $term->term_id, 
		'compare' => 'LIKE',
	),
),
```
  - Ivan Lemus 2 Aug 2017 #
    This did the trick:
    
    $args = array ( 'post_type' => 'tour', 'meta_query'=> array( array( 'key' => 'trav_tour_city', 'compare' => 'LIKE', 'value' => $term->term_id, ) ), 'meta_key' => 'trav_tour_city', );
    
    I will try yours also…
    
    Thanks a lot for your input!
Ankit 22 Nov 2017 #

i have a custom -post-type that has 2 custom filed checkboxes
and i need to print only one cpt value for each selected field
and for each field i wan to have different ouptput
howcan i do that?

- Misha 22 Nov 2017 #
  
  I’m not sure that I understand you, but maybe this post is what you are looking for.
  
diaz 11 Dec 2017 #

Hi, Misha How are you? Just have little question about meta query. My meta query working fine in single data, but it can’t working if i use array in there. Any other need to do? i have follow all your step. Thanks :)

- Misha 12 Dec 2017 #
  
  Hi Diaz,
  
  Can I look at your meta query? 🙃
  
Alex 9 Jan 2018 #

Thank you! Really helped me!

Damien 12 Feb 2018 #

Hi Misha,

This is a great article!

I have a situation where a user enters a search terms and that populates the value in the argument via a variable. However, the field expects something to be entered before any results show.

So, do you know if it is possible to set the argument to show all results that can be later filtered to a smaller list of results?

I raised a ticket about it here that shows the code:

https://stackoverflow.com/questions/48725474/show-all-wordpress-authors-then-filter-the-list-by-meta-key

Thanks for your time

Damien

- Damien 12 Feb 2018 #
  
  Hi Misha,
  
  No need to worry about this, I actually had a misplaced IF statement in my code that caused this to not work. All good now.
  
  Thanks
  
  - Misha 12 Feb 2018 #
    
    Hi Damien,
    
    I’m glad you figured it out 🙂
    
zutamacka 18 Feb 2018 #
For me, this didn’t work until I replaced “key” with “meta_key” and “value” with “meta_value”. ie:
```
$rd_args = array(
	'meta_query' => array(
		array(
			'meta_key' => '_wpgmp_location_address',
			'meta_value' => $address,
			'compare' => 'IN' 
		),
	),
);
```
I suggest looking into your phpAdmin page and opening the “metadata” table “structure” tab to make sure.
- Misha 19 Feb 2018 #
  
  Very strange, meta_key and meta_value params are OK when using them outside meta_query.
  
Rupak 23 May 2019 #
Hi,

Thank you for this post.

I am trying to put up a meta query to search for values that are in serialised format, for example:

a:3:{i:0;s:28:”Primary School (Classes 1-5)”;i:1;s:27:”Middle School (Classes 6-8)”;i:2;s:31:”Secondary School (Classes 9-10)”;}

My code is below:
```
'key'     => 'type_of_opportunity_college',
'value'   => sprintf( ':"%s";', 'Some Value'),
'compare' => 'LIKE'
```
But it does not give me desired results. Any help is appreciated.

Thanks!
Thomas 16 Jul 2019 #

Hello,

I have a problem with the sorting of my products. I have products which have no price and I want them to be in the end after all products with price. Can you please help me? Thanks!

Nimesh 3 Aug 2019 #
Hello,

thank you for the post.

I wanted to get all the posts if the user selects no meta query. I tried this but it does not work.
```
'meta_query'    => array(
	'relation'      => 'AND',
	array(
		'key'       => 'lbs_authors',
		'value' => ''
	)
)
```
This return no posts, I wanted if the value is empty, all posts should be shown.

Can you Please help me?
- Misha 4 Aug 2019 #
  Hello,
  
  Did you try NOT EXISTS? Example:
```
array(
	'key'       => 'lbs_authors',
	'compare' => 'NOT EXISTS'
)
```

Diniz

25 Nov 2019 #

Hi!

I looking for solution for my problem and find your post.

The intention is to search for customers who do not have coupon X or do not have any coupon.

I am doing according to other answers I found on the web, but the query returns wrong when it finds a post that has a meta_value different from the one searched.

Hannah Smith 22 Jan 2020 #

Great article full of really helpful examples. Helped me out a lot today – thanks!

Marco 9 Mar 2020 #
Hey, thanks for this!

what about this goal: to get all the posts (and cpts) that have a meta_key ‘my_meta_name’ corresponding to the post’s title, and to order them by their other meta_key ‘my_meta_date’, in DESC order.

I’ve tried this:
```
$args = array(
    'post_type' => array('post', 'my_cpt1', 'my_cpt2'),
    'post_status' => 'publish',
    'meta_query' => array(
        'relation' => 'AND',
        'my_order' => array(
            'key' => 'my_meta_date',
            'orderby' => 'meta_value',
            'order' => 'DESC'
        ),
        array(
            'key' => 'my_meta_name',
            'value' => $post -> post_title
        )
    ),
    'orderby' => 'my_order'
);
```
But no luck so far. The above stuff returns a bunch of posts not corresponding to my needs and not even correctly ordered :-)
Could you please enlighten me?
P.S. WP version is 5.3.2
- Misha 10 Mar 2020 #
  Hey Marco,
  
  Well, you code is far away from perfection, sorry 🙃
```
$args = array(
	...
	'meta_query' => array(
		array(
			'key' => 'my_meta_name',
			'value' => $post->post_title,
		),
		'my_order' => array(
			'key' => 'my_meta_date',
			'compare' => 'EXISTS',
		),
	),
	'orderby' => 'my_order',
	'order' => 'DESC',
);
```
  - Marco 10 Mar 2020 #
    
    Hey Misha,
    thanks for replying, hehe yeah I kinda thought it was a mess :-)
    I also came out after a couple of hours with almost the exact code you’ve posted, but I still get mixed results so I guess the catch is somewhere else.
    Thanks again!
    
Michael Ziörjen 1 Apr 2020 #

Thanks for the nice write up! Helped me a lot today.