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.
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. |
__construct( array $tax_query )
Constructor. Since 3.1.0. Since 4.1.0.
Name | Type(s) | Default Value | Description |
---|---|---|---|
$tax_query
|
array
|
{ Array of taxonomy query clauses.
} |
clean_query( array &$query )
Validates a single query. Since 3.2.0.
Name | Type(s) | Default Value | Description |
---|---|---|---|
$query
|
array
|
The single query. Passed by reference. |
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'.
Name | Type(s) | Default Value | Description |
---|---|---|---|
$clause
|
array
|
Query clause. |
|
$parent_query
|
array
|
Parent query of $clause. |
string | false
Table alias if found, otherwise false.
get_sql( string $primary_table, string $primary_id_column )
Generates SQL clauses to be appended to a main query. Since 3.1.0.
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. |
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.
}
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.
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.
}
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.
Name | Type(s) | Default Value | Description |
---|---|---|---|
$clause
|
array
|
Query clause (passed by reference). |
|
$parent_query
|
array
|
Parent query array. |
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.
}
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.
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. |
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.
}
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.
Name | Type(s) | Default Value | Description |
---|---|---|---|
$query
|
array
|
Tax query arguments. |
boolean
Whether the query clause is a first-order clause.
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
.
Name | Type(s) | Default Value | Description |
---|---|---|---|
$queries
|
array
|
Array of queries clauses. |
array
Sanitized array of query clauses.
sanitize_relation( string $relation )
Sanitize a 'relation' operator. Since 4.1.0.
Name | Type(s) | Default Value | Description |
---|---|---|---|
$relation
|
string
|
Raw relation key from the query argument. |
string
Sanitized relation ('AND' or 'OR').
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.
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'. |