Class used for querying terms from the database.

Source: wp-includes/class-wp-term-query.php
Since: 4.6.0

Class Declaration

#[AllowDynamicProperties]
class WP_Term_Query

Properties

Protected Properties

Query Variables

Constructor Parameters

public function __construct( string|array $query = '' )

Supported Query Variables

Orderby Options

Fields Options

Methods

__construct()

Sets up the term query, based on the query vars passed.

public function __construct( string|array $query = '' )

Behavior:

• Sets default query vars
• If query provided, calls query()

parse_query()

Parse arguments passed to the term query with default query parameters.

public function parse_query( string|array $query = '' ): void

Filters Applied:

• get_terms_defaults — Filter default query arguments

Actions Fired:

• parse_term_query — After query vars parsed

Behavior:

1. Applies get_terms_defaults filter
2. Merges with defaults
3. Converts number and offset to integers
4. If parent is set, disables child_of
5. If get is 'all', resets hierarchy/empty filters
6. Fires parse_term_query action

query()

Sets up the query and retrieves the results.

public function query( string|array $query ): WP_Term[]|int[]|string[]|string

Returns: Array of terms, or count as numeric string.

get_terms()

Retrieves the query results.

public function get_terms(): WP_Term[]|int[]|string[]|string

Returns: Based on fields parameter:

• 'all', 'all_with_object_id' — WP_Term[]
• 'count' — Numeric string
• 'names', 'slugs', 'id=>name', 'id=>slug' — string[]
• 'ids', 'tt_ids', 'id=>parent' — int[]

Filters Applied:

• get_terms_args — Filter query arguments
• list_terms_exclusions — Filter exclusion SQL
• get_terms_fields — Filter SELECT fields
• terms_clauses — Filter all SQL clauses
• terms_pre_query — Short-circuit opportunity
• get_terms — Filter final results (via get_terms() wrapper)

Actions Fired:

• pre_get_terms — Before query execution

Execution Flow:

1. parse_query() — Parse arguments
2. Set up WP_Meta_Query
3. Fire pre_get_terms action
4. Determine if taxonomy is hierarchical
5. Apply get_terms_args filter
6. Build SQL clauses:
   • Taxonomy filter
   • Inclusions/exclusions
   • Name/slug filters
   • Object ID filters
   • Parent/count filters
   • Search conditions
   • Meta query joins
7. Apply terms_clauses filter
8. Check cache or execute query
9. Prime term caches
10. Handle hierarchy (child_of, pad_counts, hide_empty)
11. Apply offset/number limits for hierarchical
12. Format results based on fields
13. Cache results

parse_orderby() (protected)

Parse and sanitize ‘orderby’ keys passed to the term query.

protected function parse_orderby( string $orderby_raw ): string|false

Returns: Value for ORDER clause, or false.

Filters Applied:

• Taxonomy filter
• Inclusions/exclusions
• Name/slug filters
• Object ID filters
• Parent/count filters
• Search conditions
• Meta query joins

parse_orderby_meta() (protected)

Generate the ORDER BY clause for an ‘orderby’ param that is potentially related to a meta query.

protected function parse_orderby_meta( string $orderby_raw ): string

Returns: ORDER BY clause.

parse_order() (protected)

Parse an ‘order’ query variable and cast it to ASC or DESC.

protected function parse_order( string $order ): string

Returns: 'ASC' or 'DESC'.

get_search_sql() (protected)

Used internally to generate a SQL string related to the ‘search’ parameter.

protected function get_search_sql( string $search ): string

Returns: Search SQL (matches name or slug with wildcards).

format_terms() (protected)

Format response depending on field requested.

protected function format_terms( WP_Term[] $term_objects, string $_fields ): WP_Term[]|int[]|string[]

Returns: Formatted array based on $_fields.

populate_terms() (protected)

Creates an array of term objects from an array of term IDs.

protected function populate_terms( Object[]|int[] $terms ): WP_Term[]

Returns: Array of WP_Term objects.

generate_cache_key() (protected)

Generate cache key.

protected function generate_cache_key( array $args, string $sql ): string

Returns: Cache key string.

Usage Examples

Basic Query

$query = new WP_Term_Query( array(
    'taxonomy'   => 'category',
    'hide_empty' => false,
) );

foreach ( $query->terms as $term ) {
    echo $term->name;
}

Get Term IDs Only

$query = new WP_Term_Query( array(
    'taxonomy' => 'post_tag',
    'fields'   => 'ids',
    'number'   => 10,
) );

$term_ids = $query->terms; // array( 1, 2, 3, ... )

Search Terms

$query = new WP_Term_Query( array(
    'taxonomy' => 'category',
    'search'   => 'news',
    'fields'   => 'all',
) );

With Meta Query

$query = new WP_Term_Query( array(
    'taxonomy'   => 'genre',
    'meta_query' => array(
        array(
            'key'     => 'popularity',
            'value'   => 100,
            'compare' => '>=',
            'type'    => 'NUMERIC',
        ),
    ),
    'orderby'    => 'meta_value_num',
    'meta_key'   => 'popularity',
    'order'      => 'DESC',
) );

Get Terms for Specific Posts

$query = new WP_Term_Query( array(
    'taxonomy'   => 'category',
    'object_ids' => array( 1, 2, 3 ),
    'fields'     => 'all_with_object_id',
) );

foreach ( $query->terms as $term ) {
    echo "Post {$term->object_id} has category: {$term->name}";
}

Hierarchical Query

$query = new WP_Term_Query( array(
    'taxonomy'   => 'category',
    'child_of'   => 5,  // Get descendants of term 5
    'hide_empty' => false,
) );

// Or get direct children only
$query = new WP_Term_Query( array(
    'taxonomy'   => 'category',
    'parent'     => 5,  // Direct children of term 5
    'hide_empty' => false,
) );

Count Terms

$query = new WP_Term_Query( array(
    'taxonomy' => 'category',
    'fields'   => 'count',
) );

$count = $query->terms; // "42" (string)

Using get_terms() Wrapper

// Simpler syntax using get_terms()
$terms = get_terms( array(
    'taxonomy'   => 'category',
    'hide_empty' => false,
    'number'     => 10,
    'orderby'    => 'count',
    'order'      => 'DESC',
) );

SQL Clauses

The $sql_clauses property contains:

Access the full query via $query->request after execution.