WP_Query Arguments: Custom Fields

If you've been following this series, you'll have an understanding of how WP_Query is structured and how you use it to write custom queries. To be able to define what WP_Query fetches from the database, you need to know what arguments you can use to query data.

WP_Query has a large number of possible arguments, which makes it extremely flexible. As you can use it to query just about anything held in your wp_posts table, it has arguments for every permutation of query you might want to run on your content.

In this tutorial I'll look at the arguments for custom fields. But first, a quick recap on how you code arguments in WP_Query.

A Recap on How Arguments Work in WP_Query

Before we start, let's have a quick recap on how arguments work in WP_Query. When you code WP_Query in your themes or plugins, you need to include four main elements:

the arguments for the query, using parameters which will be covered in this tutorial
the query itself
the loop
finishing off: closing if and while tags and resetting post data

In practice this will look something like the following:

<?php

$args = array(
    // Arguments for your query.
);

// Custom query.
$query = new WP_Query( $args );

// Check that we have query results.
if ( $query->have_posts() ) {

    // Start looping over the query results.
    while ( $query->have_posts() ) {

        $query->the_post();

        // Contents of the queried post results go here.

    }

}

// Restore original post data.
wp_reset_postdata();

?>

The arguments tell WordPress what data to fetch from the database and it's those that I'll cover here. So all we're focusing on here is the first part of the code:

$args = array(
    // Arguments for your query.
);

As you can see, the arguments are contained in an array. You'll learn how to code them as you work through this tutorial.

Coding Your Arguments

There is a specific way to code the arguments in the array, which is as follows:

$args = array(
    'parameter1' => 'value',
    'parameter2' => 'value',
    'parameter3' => 'value'
);

You must enclose the parameters and their values in single quotation marks, use => between them, and separate them with a comma. If you get this wrong, WordPress may not add all of your arguments to the query or you may get a white screen.

Custom Field Parameters

Custom fields, also known as post metadata, can use a separate class called WP_Meta_Query. This means that if you want to run a query just for post metadata, you can use either WP_Meta_Query or WP_Query (which accesses WP_Meta_Query), while if you want to query for post metadata and other items such as post type, you use WP_Query.

The WP_Meta_Query class is covered in detail elsewhere in this series so I won't go into detail on that here, but the main difference between using that and WP_Query is that WP_Query lets you create some simple arguments without using nested arrays.

Parameters for Simple Custom Field Queries

The main parameters for using WP_Query to query custom fields are as follows:

meta_key (string): Custom field key.
meta_value (string): Custom field value.
meta_value_num (number): Custom field value.
meta_compare (string): Operator to test the 'meta_value'. Possible values are '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP' or 'RLIKE'. Default value is '='.

Use these parameters for a simple custom field query. So for example to output posts which have a custom field with the key key1 (regardless of its value), you use this argument:

$args = array(
    'meta_key' => 'key1'
);

This would return all posts with a custom field with the key1 key, whatever the value.

If you wanted to specify a value you would add an extra argument for that:

$args = array(
    'meta_key' => 'key1',
    'meta_value' => 'value1'
);

This would return all posts with a custom field with the key1 key and the value1 value for it.

Alternatively you could fetch all posts with a custom field with the value value1, regardless of the key. This might be useful where you have multiple custom field keys with duplicate values:

$args = array(
    'meta_value' => 'value1'
);

So as you can see, you can query for just the custom field's key or value—you don't always have to specify both.

Using the meta_compare Argument

You may have noticed above that there are a lot of potential parameters for the meta_compare argument, and their use may not always be immediately apparent. Let's take a look at the ones you might use the most:

=: Equals. This is the default, so if you don't include a meta_compare argument, this is what WP_Query will use.
!+: Is not equal to.
>: Greater than.
>=: Greater than or equal to.
< : Less than.
<=: Less than or equal to.
LIKE: This will ignore the case of the value you use, and you can also use it with wildcard characters to find values like the value you're looking for.
NOT LIKE: Works in a similar way to LIKE but queries the opposite!
IN: Use this with an array in the 'value' argument to find posts with one or more of the values in the array.
BETWEEN: Use with an array of two numerical values (specified in the meta_value argument) to find posts with a custom field value between those values (but not equal to them).
NOT BETWEEN: Queries posts with custom field values outside an array of two numerical values specified by the meta_value argument.

Let's take a look at some example uses of this argument.

First up, you can exclude custom field keys or values using the meta_compare argument. So to fetch all posts except those with a custom field with the key1 key, you would use this:

$args = array(
    'meta_key' => 'key1',
    'meta_compare' => '!='
);

You could also use the 'NOT IN' value for the meta_compare argument, which can also be used with a string of multiple values:

$args = array(
    'meta_key' => 'key1, key2',
    'meta_compare' => 'NOT IN'
);

This would query posts which don't have custom fields with the key1 or key2 values. If you want to be more specific, maybe querying for posts with one custom field and not another, you use a nested array, which we'll come to shortly.

The examples above use non-numerical values. You can use WP_Query with custom fields that have numerical values, not only to fetch posts with a custom field with that value, but also to fetch ones with custom fields with higher or lower values. You might use this in a store for example, if looking for items above or below a given price.

To find posts with a custom field value above a given number, use something like this:

$args = array(
    'meta_key' => 'numkey',
    'meta_value' => '100',
    'meta_compare' => '>'
);

This would return all posts with a custom field with the numkey key and a value of over 100. If you wanted to query for values of 100 or over, you would use 'meta_compare' => '>='.

You can also find posts whose custom fields have values between two numbers you specify using the BETWEEN argument and an array:

$args = array(
    'meta_key' => 'numkey',
    'meta_value' => array (
        '100',
        '200'
    ),
    'meta_compare' => 'BETWEEN'
);

This would find all posts with a value in the numkey custom field between 100 and 200.

Nested Custom Field Queries

If you want to query for more than one custom field or use more than one operator, you can use a nested array.

These take the following structure:

$args = array(
    'meta_query' => array(
        'relation' => '', // Optional argument.
        array(
            // `meta_query` arguments go here.
        )
    )
);

The way that you structure the 'meta_query' argument in WP_Query is exactly the same as how you do it using the WP_Meta_Query class, which is covered in a later tutorial in this series, so I won't duplicate that here.

Since WordPress version 4.1 you can also use multiple levels of nested array to create ever more complex and precise queries. These look something like this:

$args = array(
    'meta_query' => array(
        'relation' => '', // Optional argument.
        array(
            'relation' => '',
            array (
                // First set of `meta_query` arguments go here.
            ),
            array (
                // Second set of `meta_query` arguments go here.
            )
        )
    )
);

This lets you use different relations at different levels in your query, for example querying for posts with a value in one custom field key, or with both of two values in another custom field key. This is covered in more detail, with examples, in the tutorial on the WP_Meta_Query class, which is part of this series.

Summary

Using the WP_Query class to query your posts' metadata (or custom fields) gives you a lot of flexibility, with multiple potential arguments combined with a number of operators to help you query your database in exactly the way you want to.

If you only want to use post metadata arguments in your query (and not combine it with other arguments, for example for post types), you can also use the WP_Meta_Query class, which is covered later in this series.

HIGHLIGHTS OF THE DAY