wpdevtools.io Logo

Class: WP_Tax_Query

Core class used to implement taxonomy queries for the Taxonomy API.

Used for generating SQL clauses that filter a primary query according to object taxonomy terms.

WP_Tax_Query is a helper that allows primary query classes, such as WP_Query, to filter their results by object metadata, by generating JOIN and WHERE subclauses to be attached to the primary SQL query string.

Properties

Methods

Properties

Name Type(s) Default Value Summary
queries array Array of taxonomy queries.

See WP_Tax_Query::__construct() for information on tax query arguments.
relation string The relation between the queries. Can be one of 'AND' or 'OR'.
no_results string Static ⋅ Standard response when the query should not return any rows.
table_aliases array A flat list of table aliases used in the JOIN clauses.
queried_terms array Terms and taxonomies fetched by this query.

We store this data in a flat array because they are referenced in a number of places by WP_Query.
primary_table string Database table that where the metadata's objects are stored (eg $wpdb->users).
primary_id_column string Column in 'primary_table' that represents the ID of the object.

Methods

WP_Tax_Query:: __construct( array $tax_query )

Constructor. Since 3.1.0. Since 4.1.0.

Arguments

Name Type(s) Default Value Description
$tax_query array

{ Array of taxonomy query clauses.

@type string $relation Optional. The MySQL keyword used to join
                       the clauses of the query. Accepts 'AND', or 'OR'. Default 'AND'.
@type array {
    Optional. An array of first-order clause parameters, or another fully-formed tax query.

    @type string           $taxonomy         Taxonomy being queried. Optional when field=term_taxonomy_id.
    @type string|int|array $terms            Term or terms to filter by.
    @type string           $field            Field to match $terms against. Accepts 'term_id', 'slug',
                                            'name', or 'term_taxonomy_id'. Default: 'term_id'.
    @type string           $operator         MySQL operator to be used with $terms in the WHERE clause.
                                             Accepts 'AND', 'IN', 'NOT IN', 'EXISTS', 'NOT EXISTS'.
                                             Default: 'IN'.
    @type bool             $include_children Optional. Whether to include child terms.
                                             Requires a $taxonomy. Default: true.
}

}

WP_Tax_Query:: clean_query( array &$query )

Validates a single query. Since 3.2.0.

Arguments

Name Type(s) Default Value Description
$query array

The single query. Passed by reference.

WP_Tax_Query:: find_compatible_table_alias( array $clause, array $parent_query )

Identify an existing table alias that is compatible with the current query clause. Since 4.1.0.

We avoid unnecessary table joins by allowing each clause to look for an existing table alias that is compatible with the query that it needs to perform.

An existing alias is compatible if (a) it is a sibling of $clause (ie, it's under the scope of the same relation), and (b) the combination of operator and relation between the clauses allows for a shared table join. In the case of WP_Tax_Query, this only applies to 'IN' clauses that are connected by the relation 'OR'.

Arguments

Name Type(s) Default Value Description
$clause array

Query clause.
$parent_query array

Parent query of $clause.

Returns

string | false

Table alias if found, otherwise false.

WP_Tax_Query:: get_sql( string $primary_table, string $primary_id_column )

Generates SQL clauses to be appended to a main query. Since 3.1.0.

Arguments

Name Type(s) Default Value Description
$primary_table string

Database table where the object being filtered is stored (eg wp_users).
$primary_id_column string

ID column for the filtered object in $primary_table.

Returns

array

{ Array containing JOIN and WHERE SQL clauses to append to the main query.

@type string $join  SQL fragment to append to the main JOIN clause.
@type string $where SQL fragment to append to the main WHERE clause.

}

WP_Tax_Query:: get_sql_clauses( )

Generate SQL clauses to be appended to a main query. Since 4.1.0.

Called by the public WP_Tax_Query::get_sql(), this method is abstracted out to maintain parity with the other Query classes.

Returns

array

{ Array containing JOIN and WHERE SQL clauses to append to the main query.

@type string $join  SQL fragment to append to the main JOIN clause.
@type string $where SQL fragment to append to the main WHERE clause.

}

WP_Tax_Query:: get_sql_for_clause( array &$clause, array $parent_query )

Generate SQL JOIN and WHERE clauses for a "first-order" query clause. Since 4.1.0.

Arguments

Name Type(s) Default Value Description
$clause array

Query clause (passed by reference).
$parent_query array

Parent query array.

Returns

array

{ Array containing JOIN and WHERE SQL clauses to append to a first-order query.

@type string $join  SQL fragment to append to the main JOIN clause.
@type string $where SQL fragment to append to the main WHERE clause.

}

WP_Tax_Query:: get_sql_for_query( array &$query, integer $depth )

Generate SQL clauses for a single query array. Since 4.1.0.

If nested subqueries are found, this method recurses the tree to produce the properly nested SQL.

Arguments

Name Type(s) Default Value Description
$query array

Query to parse (passed by reference).
$depth integer

Optional. Number of tree levels deep we currently are. Used to calculate indentation. Default 0.

Returns

array

{ Array containing JOIN and WHERE SQL clauses to append to a single query array.

@type string $join  SQL fragment to append to the main JOIN clause.
@type string $where SQL fragment to append to the main WHERE clause.

}

WP_Tax_Query:: is_first_order_clause( array $query )

Determine whether a clause is first-order. Since 4.1.0.

A "first-order" clause is one that contains any of the first-order clause keys ('terms', 'taxonomy', 'include_children', 'field', 'operator'). An empty clause also counts as a first-order clause, for backward compatibility. Any clause that doesn't meet this is determined, by process of elimination, to be a higher-order query.

Arguments

Name Type(s) Default Value Description
$query array

Tax query arguments.

Returns

boolean

Whether the query clause is a first-order clause.

WP_Tax_Query:: sanitize_query( array $queries )

Ensure the 'tax_query' argument passed to the class constructor is well-formed. Since 4.1.0.

Ensures that each query-level clause has a 'relation' key, and that each first-order clause contains all the necessary keys from $defaults.

Arguments

Name Type(s) Default Value Description
$queries array

Array of queries clauses.

Returns

array

Sanitized array of query clauses.

WP_Tax_Query:: sanitize_relation( string $relation )

Sanitize a 'relation' operator. Since 4.1.0.

Arguments

Name Type(s) Default Value Description
$relation string

Raw relation key from the query argument.

Returns

string

Sanitized relation ('AND' or 'OR').

WP_Tax_Query:: transform_query( array &$query, string $resulting_field )

Transforms a single query, from one field to another. Since 3.2.0.

Operates on the $query object by reference. In the case of error, $query is converted to a WP_Error object.

Arguments

Name Type(s) Default Value Description
$query array

The single query. Passed by reference.
$resulting_field string

The resulting field. Accepts 'slug', 'name', 'term_taxonomy_id', or 'term_id'. Default 'term_id'.

WordPress Developer Newsletter

Stay on top of the latest WordPress API changes, developer tool updates, security alerts and more.