How to Use meta_query in WordPress for Custom Queries

Use meta_query in WordPress to filter posts by custom fields in WP_Query. It accepts an array of conditions specifying the meta key, value, and comparison operator to find posts matching those meta values.

Syntax

The meta_query parameter is an array of arrays, where each inner array defines a condition with keys like key, value, and compare. You can combine multiple conditions using relation ('AND' or 'OR').

Key parts explained:

• key: The custom field name to check.
• value: The value to compare against.
• compare: The comparison operator (e.g., '=', '!=', 'LIKE').
• type: Data type for comparison (e.g., 'NUMERIC', 'CHAR').
• relation: How multiple conditions combine ('AND' or 'OR').

php

$meta_query = [
  'relation' => 'AND',
  [
    'key' => 'custom_field_name',
    'value' => 'some_value',
    'compare' => '=',
    'type' => 'CHAR'
  ],
  [
    'key' => 'another_field',
    'value' => 10,
    'compare' => '>',
    'type' => 'NUMERIC'
  ]
];

$args = [
  'post_type' => 'post',
  'meta_query' => $meta_query
];

$query = new WP_Query($args);

Example

This example fetches posts where the custom field price is greater than 20 and the color field equals 'blue'. It shows how to use meta_query with multiple conditions and the 'AND' relation.

php

<?php
$args = [
  'post_type' => 'product',
  'meta_query' => [
    'relation' => 'AND',
    [
      'key' => 'price',
      'value' => 20,
      'compare' => '>',
      'type' => 'NUMERIC'
    ],
    [
      'key' => 'color',
      'value' => 'blue',
      'compare' => '='
    ]
  ]
];

$query = new WP_Query($args);

if ($query->have_posts()) {
  while ($query->have_posts()) {
    $query->the_post();
    echo get_the_title() . "\n";
  }
} else {
  echo "No products found.";
}
wp_reset_postdata();
?>

Output

Product A
Product C

Common Pitfalls

Common mistakes when using meta_query include:

• Not specifying type when comparing numbers, causing string comparison issues.
• Using wrong comparison operators or forgetting to set relation when combining multiple conditions.
• Not resetting post data after custom queries with wp_reset_postdata().
• Confusing meta_query with meta_key and meta_value which only support single conditions.

Example of a wrong and right way:

php

<?php
// Wrong: comparing numbers as strings
$args_wrong = [
  'meta_query' => [
    [
      'key' => 'price',
      'value' => 20,
      'compare' => '>',
      // Missing 'type' => 'NUMERIC'
    ]
  ]
];

// Right: specify type for numeric comparison
$args_right = [
  'meta_query' => [
    [
      'key' => 'price',
      'value' => 20,
      'compare' => '>',
      'type' => 'NUMERIC'
    ]
  ]
];

Quick Reference

Use this quick guide when building meta_query arrays:

Parameter	Description	Example
key	Custom field name to query	'price'
value	Value to compare	20
compare	Comparison operator (=, !=, >, <, LIKE)	'>'
type	Data type for comparison (NUMERIC, CHAR, DATE)	'NUMERIC'
relation	How multiple conditions combine (AND, OR)	'AND'

Key Takeaways

Use meta_query inside WP_Query to filter posts by custom fields.

Always specify the 'type' key for numeric or date comparisons to avoid errors.

Combine multiple meta conditions with 'relation' set to 'AND' or 'OR'.

Reset post data after custom queries with wp_reset_postdata().

meta_query supports complex queries beyond simple meta_key and meta_value.