WP_Comment_Query Reference and Usage Examples for WordPress

WP_Comment_Query is the PHP class WordPress uses to query comment data. The source code lives in wp-includes/comment.php, and the class can retrieve records from both the wp_comments and wp_commentmeta tables. It has been available since WordPress 3.1, so any supported WordPress installation can use it.

Basic introduction to WP_Comment_Query

$args = array(
    // Query arguments.
);

$comments_query = new WP_Comment_Query;
$comments = $comments_query->query($args);

if ($comments) {
    foreach ($comments as $comment) {
        echo '<p>' . $comment->comment_content . '</p>';
    }
} else {
    echo 'No comments found.';
}

Default usage

$args = array(
   'author_email' => '',
   'author__in' => '',
   'author__not_in' => '',
   'include_unapproved' => '',
   'fields' => '',
   'ID' => '',
   'comment__in' => '',
   'comment__not_in' => '',
   'karma' => '',
   'number' => '',
   'offset' => '',
   'orderby' => '',
   'order' => 'DESC',
   'parent' => '',
   'post_author__in' => '',
   'post_author__not_in' => '',
   'post_id' => 0,
   'post__in' => '',
   'post__not_in' => '',
   'post_author' => '',
   'post_name' => '',
   'post_parent' => '',
   'post_status' => '',
   'post_type' => '',
   'status' => 'all',
   'type' => '',
   'type__in' => '',
   'type__not_in' => '',
   'user_id' => '',
   'search' => '',
   'count' => false,
   'meta_key' => '',
   'meta_value' => '',
   'meta_query' => '',
   'date_query' => null,
);

Parameter overview

The most commonly used parameters include status, ordering, limit, offset, post filters, user filters, and field selection. A few especially useful examples are:

status: filter by comment state such as hold, approve, spam, or trash.
orderby and order: control sorting.
number and offset: control pagination or batching.
post_id: limit the query to one specific post.
user_id: return comments made by one specific user.
count: return only the total number of matching comments.
fields: return only IDs or the full comment objects.

Custom field parameters

You can also query comments by their custom metadata.

meta_key: the comment meta key.
meta_value: the value that key should match.
meta_query: an advanced array-based meta query, available since WordPress 3.5.
Inside meta_query, the common keys are key, value, compare, and type.

The compare operator supports values such as =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN, NOT IN, BETWEEN, NOT BETWEEN, EXISTS, and NOT EXISTS. The type option can be NUMERIC, BINARY, CHAR, DATE, DATETIME, DECIMAL, SIGNED, TIME, or UNSIGNED.

Example: show featured comments

$comment_query = new WP_Comment_Query(array(
    'meta_key' => 'featured',
    'meta_value' => '1',
));

Example: multiple meta conditions

$args = array(
    'meta_query' => array(
        'relation' => 'AND',
        array(
            'key' => 'featured',
            'value' => '1',
        ),
        array(
            'key' => 'buried',
            'value' => '1',
            'type' => 'numeric',
            'compare' => '!=',
        ),
    ),
);

$comment_query = new WP_Comment_Query($args);