SEO & AI search · Explainer
What Is a Meta Query in WordPress? Explained

Short answer
A meta query is the meta_query argument in WP_Query and similar classes. It filters posts, users, terms or comments by custom field values, using a key, a value, a compare operator and a type, joined with AND or OR logic.
Key takeaways
- A meta query filters content by custom field values.
- Each clause uses key, value, compare and type.
- Relation joins clauses with AND or OR, and arrays can nest.
- Set type to NUMERIC or DATE for correct comparisons.
- Large meta queries can be slow; taxonomies often filter faster.
What is a meta query in WordPress?
A meta query is a set of conditions you pass to WordPress queries, using the meta_query argument, to find posts, users or terms by their custom field values instead of only by title, date or category.
Every post in WordPress can store extra data called post meta, also known as custom fields. A price, an event date, a rating or a featured flag are all typical examples.
A meta query lets you ask questions about that data. For example: show events whose date is after today, or products where the color is blue and the price is under 50.
It is part of the main query tools, most often WP_Query, and the same format works in several other query classes too.
| Term | Meaning |
|---|---|
| Post meta | Extra key and value pairs stored for a post |
| meta_key | The name of a custom field, such as price |
| meta_value | The stored value, such as 49 |
| meta_query | An array of conditions on meta keys and values |
| compare | How the value is tested, such as equals or greater than |
| type | How the value is treated, such as number or date |
| relation | Whether conditions are joined with AND or OR |
Where is meta data stored?
Post meta lives in the wp_postmeta database table, with one row per key and value, linked to the post by its ID.
Users, terms and comments have their own matching tables: wp_usermeta, wp_termmeta and wp_commentmeta. That is why meta queries work for each of them.
You add meta through the Custom Fields panel, plugins such as Advanced Custom Fields, or code using functions like update_post_meta. Our guide on how to add custom fields in WordPress shows each method.
The Custom Fields documentation explains the built-in panel for editors who are not using a plugin.
What does a meta query look like?
A meta query is an array of clauses, each with a key, a value, a compare operator and optionally a type, passed inside the arguments of a query.
Here is a simple example that finds events on or after today:
$events = new WP_Query( array(
'post_type' => 'event',
'meta_query' => array(
array(
'key' => 'event_date',
'value' => date( 'Ymd' ),
'compare' => '>=',
'type' => 'NUMERIC',
),
),
) );
Each inner array is one condition. WordPress turns them into SQL joins and WHERE clauses against the meta table, so you do not write SQL yourself.
The parameters are documented in the custom field parameters section of the WP_Query reference.
What are the parts of a meta query clause?
Each clause has up to four parts: key names the field, value is what to test against, compare sets the test and type tells WordPress how to read the data.
key is the custom field name exactly as stored. It is case-sensitive, and plugins sometimes add prefixes, so check the database if a query returns nothing.
value can be a single value or an array. Arrays are needed for operators like IN and BETWEEN.
compare decides the test. The common operators are:
- = and != for exact matches.
- >, >=, <, <= for ranges.
- LIKE and NOT LIKE for partial text matches.
- IN and NOT IN for lists of values.
- BETWEEN and NOT BETWEEN for ranges with two values.
- EXISTS and NOT EXISTS to check if a key is set at all.
type matters for numbers and dates. Meta values are stored as text, so without NUMERIC, 100 sorts before 20. Other types include DATE, DATETIME, DECIMAL and CHAR.
How do AND and OR relations work?
The relation key joins clauses: AND means every clause must match, and OR means any one clause is enough.
AND is the default if you leave relation out. Add relation at the top level of the meta_query array:
'meta_query' => array(
'relation' => 'OR',
array( 'key' => 'color', 'value' => 'blue' ),
array( 'key' => 'color', 'value' => 'green' ),
),
You can nest arrays to build more complex logic, such as color is blue AND (size is small OR size is medium). Each nested array can have its own relation.
Nesting is powerful but each extra clause adds another join to the database query. Keep logic as simple as the task allows.
Which functions accept a meta query?
WP_Query is the most common, but WP_User_Query, WP_Comment_Query, WP_Term_Query and functions built on them, such as get_posts, get_users and get_terms, accept the same format.
That consistency comes from the shared WP_Meta_Query class, which turns the array into SQL for whichever table is involved.
Some common uses:
- Posts: list featured articles or upcoming events.
- Users: find members with a certain plan stored in user meta.
- Terms: show categories marked as featured.
- Comments: filter reviews by a rating stored in comment meta.
For the bigger picture of building custom loops, see our guide on how to use WP_Query.
How do you sort results by a meta value?
Use orderby with meta_value or meta_value_num, or name your meta query clauses and order by the clause name.
The older way sets meta_key and orderby together. The newer way gives each clause a key in the array, such as price_clause, and passes that name to orderby.
Named clauses let you sort by several fields at once, such as by date and then by price. WordPress explains this in the orderby parameters of WP_Query.
Posts without the meta key are left out when you sort by a meta value. Use an OR relation with an EXISTS and a NOT EXISTS clause if you need to keep them.
Do meta queries slow down a site?
They can, because the meta table is indexed for keys but not fully for values, so complex meta queries on large sites can be slow.
MySQL can only search quickly on indexed columns, as its guide on how MySQL uses indexes explains. The wp_postmeta table grows fast. A store with thousands of products may have hundreds of thousands of meta rows, and each clause adds a join.
Ways to keep them fast:
- Use as few clauses as possible.
- Set type so the database compares the right way.
- Avoid LIKE with leading wildcards on large tables.
- Store data you filter on often in taxonomies instead.
- Cache query results with transients or an object cache.
Taxonomies are often the better choice for filtering. Categories and tags have tables built for grouping, while meta suits values unique to each post.
Our guide on how to query the WordPress database helps you inspect what a slow query is doing.
For repeated heavy queries, setting up Redis object cache can store results in memory.
Is a meta query safe to use with user input?
Yes, when you pass values through the meta_query array, WordPress escapes them, but you should still validate and sanitize anything that comes from a form or URL.
Never build raw SQL strings with user input. The meta_query format exists so you do not have to.
Sanitize input before using it, for example with sanitize_text_field for text or absint for whole numbers. The WordPress security handbook on sanitizing explains which function to use.
Whitelist allowed keys too. Letting visitors choose any meta key could expose private fields stored by plugins.
How is meta query different from meta_key and meta_value?
The simple meta_key and meta_value arguments test one field, while meta_query handles several fields, operators and AND or OR logic in one place.
For a quick single test, the simple arguments are fine. Once you need two conditions or a range, switch to meta_query.
| Need | Simple arguments | meta_query |
|---|---|---|
| One field equals one value | Works well | Also works |
| Numeric range | Limited | Works with type |
| Several fields | Not supported | Works |
| AND or OR logic | Not supported | Works |
| Sort by named clause | Not supported | Works |
Where do people go wrong with meta queries?
Typical mistakes are wrong key names, missing type for numbers or dates, date formats that do not match, and running heavy queries on every page load.
ACF date fields, for example, often store dates as Ymd. Comparing them with a different format returns nothing. PHP's date function reference lists the format characters if you need to build matching values.
If a meta query returns the wrong posts or none at all, our guide on how to fix a meta query in WordPress walks through debugging step by step.
For fields from Advanced Custom Fields, see how to display Advanced Custom Fields to check how values are stored and printed.
Frequently asked questions
What is the difference between meta_key and meta_query?
meta_key with meta_value tests a single custom field in a simple way. meta_query is an array that can test many fields at once, use operators like greater than or BETWEEN, and combine conditions with AND or OR.
Why does my meta query sort numbers in the wrong order?
Meta values are stored as text, so 100 can sort before 20. Set the type to NUMERIC in the clause, or use meta_value_num when ordering, so the database treats the values as numbers.
Can I use a meta query on users?
Yes. WP_User_Query and get_users accept the same meta_query format, which tests values in the user meta table. This is a common way to find members by plan, status or any field saved on their profile.
Are meta queries bad for performance?
Not always, but they can be slow on large sites because each clause adds a database join and meta values are not fully indexed. Keep clauses few, cache results and use taxonomies for common filters.
What does EXISTS do in a meta query?
EXISTS matches posts that have the meta key set, whatever its value. NOT EXISTS matches posts that lack the key. Together they help include posts without a field, for example when sorting by a meta value.
Sources
- WP_Query WordPress Developer Resources
- WP_Meta_Query WordPress Developer Resources
- Assign Custom Fields WordPress.org Documentation
- Sanitizing data WordPress Developer Resources
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


