Class: WP_Meta_Query

Core class used to implement meta queries for the Meta API.

Used for generating SQL clauses that filter a primary query according to metadata keys and values.

WP_Meta_Query is a helper that allows primary query classes, such as WP_Query and WP_User_Query,

to filter their results by object metadata, by generating JOIN and WHERE subclauses to be attached to the primary SQL query string.


Properties

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

See WP_Meta_Query::__construct() for information on meta query arguments.

relation string The relation between the queries. Can be one of 'AND' or 'OR'.
meta_table string Database table to query for the metadata.
meta_id_column string Column in meta_table that represents the ID of the object the metadata belongs to.
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.
table_aliases array A flat list of table aliases used in JOIN clauses.
clauses array A flat list of clauses, keyed by clause 'name'.
has_or_relation boolean Whether the query contains any OR relations.

Methods

WP_Meta_Query:: __construct( array $meta_query = false )

Constructor. Since 3.2.0. Since 4.2.0. Since 5.1.0.

Arguments

Name Type(s) Default Value Description
$meta_query array

{ Array of meta query clauses. When first-order clauses or sub-clauses use strings as their array keys, they may be referenced in the 'orderby' parameter of the parent query.

@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 meta query.

    @type string $key         Meta key to filter by.
    @type string $compare_key MySQL operator used for comparing the $key. Accepts '=' and 'LIKE'.
                              Default '='.
    @type string $value       Meta value to filter by.
    @type string $compare     MySQL operator used for comparing the $value. Accepts '=',
                              '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE',
                              'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'REGEXP',
                              'NOT REGEXP', 'RLIKE', 'EXISTS' or 'NOT EXISTS'.
                              Default is 'IN' when `$value` is an array, '=' otherwise.
    @type string $type        MySQL data type that the meta_value column will be CAST to for
                              comparisons. Accepts 'NUMERIC', 'BINARY', 'CHAR', 'DATE',
                              'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', or 'UNSIGNED'.
                              Default is 'CHAR'.
}

}


WP_Meta_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_Meta_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 | boolean

Table alias if found, otherwise false.


WP_Meta_Query:: get_cast_for_type( string $type = '' )

Return the appropriate alias for the given meta type if applicable. Since 3.7.0.

Arguments

Name Type(s) Default Value Description
$type string

MySQL type to cast meta_value.

Returns

string

MySQL type.


WP_Meta_Query:: get_clauses( )

Get a flattened list of sanitized meta clauses. Since 4.2.0.

This array should be used for clause lookup, as when the table alias and CAST type must be determined for a value of 'orderby' corresponding to a meta clause.

Returns

array

Meta clauses.


WP_Meta_Query:: get_sql( string $type, string $primary_table, string $primary_id_column, object $context = null )

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

Arguments

Name Type(s) Default Value Description
$type string

Type of meta, eg 'user', 'post'.

$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.

$context object

Optional. The main query object.

Returns

false | 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_Meta_Query:: get_sql_clauses( )

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

Called by the public WP_Meta_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_Meta_Query:: get_sql_for_clause( array &$clause, array $parent_query, string $clause_key = '' )

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

"First-order" means that it's an array with a 'key' or 'value'.

Arguments

Name Type(s) Default Value Description
$clause array

Query clause (passed by reference).

$parent_query array

Parent query array.

$clause_key string

Optional. The array key used to name the clause in the original $meta_query parameters. If not provided, a key will be generated automatically.

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_Meta_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_Meta_Query:: has_or_relation( )

Checks whether the current query has any OR relations. Since 4.3.0.

In some cases, the presence of an OR relation somewhere in the query will require the use of a DISTINCT or GROUP BY keyword in the SELECT clause. The current method can be used in these cases to determine whether such a clause is necessary.

Returns

boolean

True if the query contains any OR relations, otherwise false.


WP_Meta_Query:: is_first_order_clause( array $query )

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

A first-order meta query clause is one that has either a 'key' or a 'value' array key.

Arguments

Name Type(s) Default Value Description
$query array

Meta query arguments.

Returns

boolean

Whether the query clause is a first-order clause.


WP_Meta_Query:: parse_query_vars( array $qv )

Constructs a meta query based on 'meta_*' query vars Since 3.2.0.

Arguments

Name Type(s) Default Value Description
$qv array

The query variables


WP_Meta_Query:: sanitize_query( array $queries )

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

Eliminates empty items and ensures that a 'relation' is set.

Arguments

Name Type(s) Default Value Description
$queries array

Array of query clauses.

Returns

array

Sanitized array of query clauses.


WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.