• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

クラスリファレンス/WP Meta Query

提供: WordPress Codex 日本語版
移動先: 案内検索

説明

WP_Meta_Query is a class defined in wp-includes/meta.php that generates the necessary SQL for meta-related queries. バージョン 3.2.0 で導入されました。カスタムフィールドによる投稿を照会するには、可能性が大幅に向上しています。 WP のコアでは、WP_QueryWP_User_Queryクラス、since Version 3.5以降では、WP_Comment_Query クラス内で使用されています。

Unless you're writing a custom SQL query, you should look in the *Custom Field Parameters* section for the corresponding class.

使い方

引数の受け入れ

次の引数は、key=>valueペアの配列で渡すことができます。

  • meta_key (文字列) - カスタムフィールドのキー( 自分でサニタイズが必要)
  • meta_value (文字列|配列) - カスタムフィールドの値 ( 自分でサニタイズが必要)
  • meta_type (number) - カスタムフィールドタイプ (以下の type オプションを参照)
  • meta_compare (文字列) -'meta_value'をテストする演算子 (参照 compare 以下の使用可能な値)
  • meta_query (配列) - 以下のキーで一つ以上の配列を含みます:
    • key (文字列) - カスタムフィールドキー
    • value (文字列|配列) - カスタムフィールドの値。compare'IN', 'NOT IN', 'BETWEEN',または 'NOT BETWEEN'の時のみ、配列にできる。

You don't have to specify a value when using the 'EXISTS' or 'NOT EXISTS' comparisons in WordPress 3.9以降で。
(注意:bug #23268のため、value was required for NOT EXISTS comparisons to work correctly prior to 3.9. valueパラメータにsome文字列を指定する必要がありました。 空の文字列または NULL は動作しません。 However, any other string will do the trick and will NOT show up in your SQL when using NOT EXISTS. インスピレーションが必要ですか? 'bug #23268'はどうですか?)

    • compare (文字列) - テストする演算子。可能な値は、 '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' (WP >= 3.5でのみ), 'NOT EXISTS' (WP >= 3.5でのみ). 値 'REGEXP'、'NOT REGEXP'、 'RLIKE' は WordPress 3.7で追加されました。 デフォルト値は '=' 。
    • type (文字列) - カスタムフィールドの型。 有効な値は、 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'. デフォルト値は、'CHAR'。

The 'type' DATE works with the 'compare' value BETWEEN only if the date is stored at the format YYYY-MM-DD and tested with this format.

注: 'meta_key''meta_value''meta_type''meta_compare'引数は下の 2 番目の方法を使用している場合のみ動作します。

WP_Meta_Query のイニシャライズ(初期化)

一般的には、初期化するか、new WP_Meta_Query オブジェクトを使う2つのオプションがあります。

コンストラクタにクエリパラメータの配列を渡します:

$meta_query_args = array(
	'relation' => 'OR', // オプション、デフォルト値は "AND"
	array(
		'key'     => '_my_custom_key',
		'value'   => 'Value I am looking for',
		'compare' => '='
	)
);
$meta_query = new WP_Meta_Query( $meta_query_args );

この事例では、(meta_query の引数で上述した)キー/値のペアの配列の配列を渡します。

You can optionally pass the `relation` key and set it to either OR or AND. It defines the relation, when there is more than one meta query(whether all of the conditions should be met, or at least one of them needs to be met).

WP_Meta_Query::parse_query_vars( $query ) メソッドを使う:

(`meta_key`, `meta_value`, `meta_type`, `meta_compare`)を単純なクエリの引数に使用する場合、または、メタクエリパラメータの存在が不明な場合、このメソッドを使用することができます。

// $query_vars can have various contents, so an example is not added here, but you need to have it defined beforehand
$meta_query = new WP_Meta_Query();
// Won't work with an array( 'relation', array( 'key' => '...' ) )
// as the parse_query_vars() method searches for the `meta_` prefix
$meta_query->parse_query_vars( array(
	'meta_key' => 'some_key',
	// etc.
) );

最終的なSQLを取得する

以下の方法を使用して生成されたSQLを取得できます。

$mq_sql = $meta_query->get_sql(
	$type,
	$primary_table,
	$primary_id_column,
	$context = null
);

引数のリスト:

  • $type' (文字列) - metaの型(post, comment, user).
  • $primary_table (文字列) - 列を探しているテーブル。$wpdb->postsのインスタンスを渡すことができる、または、エイリアス名、 SQL クエリーでは、テーブルエイリアスする場合
  • $primary_id_column (文字列) - IDを保持する列 (投稿では ID, コメントでは comment_ID ユーザーでは ID).
  • $context (オブジェクト) - オプション - メインのクエリオブジェクト。結果はget_meta_sqlフィルタに渡されたときにのみ使用されます。

失敗時には(たとえば、クエリ配列の任意のメタクエリパラメータが不足している)、 この関数は `false`を返します。

成功時には、このような配列を返します:

array(
	'join'  => $join_sql,
	'where' => $where_sql
)

各キーに対応するセクションのSQLを保持する。

例: シングルメタエントリー - フラット配列

クエリ

// Note that this will produce a "key only" query
// If you want a full one, add a meta_value and meta_compare array key/value pair
$query_args = array(
	'meta_key' => 'some_key_name',
);
$meta_query = new WP_Meta_Query();
$meta_query->parse_query_vars( $query_args );
$mq = $meta_query->get_sql(
	'post',
	$wpdb->posts,
	'ID',
	null
);

結果

array (size=2)
  'join' => string ' INNER JOIN wp_postmeta ON (wp_posts.ID = wp_postmeta.post_id)' (length=62)
  'where' => string ' AND (wp_postmeta.meta_key = 'some_key' )' (length=40)

例: 複数のメタエントリ - 多次元配列:

クエリ:

$query_args = array( 'meta_query' => array(
	'relation' => 'OR',
	array(
		'key' => 'foo_key',
		// 'value' => 'foo',
		// 'compare' => 'LIKE',
	),
	array(
		'key' => 'bar_key',
	),
) );
$meta_query = new WP_Meta_Query();
$meta_query->parse_query_vars( $query_args );
$mq_sql = $meta_query->get_sql(
	'post',
	$wpdb->posts,
	'ID',
	null
);

結果:

'join' => string ' INNER JOIN wp_postmeta ON wp_posts.ID = wp_postmeta.post_id' (length=60)
'where' => string ' AND (wp_postmeta.meta_key = 'foo_key' OR wp_postmeta.meta_key = 'bar_key' )' (length=75)

注: この例は、 will not append a space to the join statement, so you have to do it manually to not crash your query. The same goes for the where statement.

If you're using the value and compare parts of the meta_query input argument array, then the query string will look something like the following:

'where' => string ' AND (wp_postmeta.meta_key = 'foo_key' OR  (mt1.meta_key = 'bar_key' AND CAST(mt1.meta_value AS CHAR) LIKE '%foo%') )'

Keep in mind that mt1 is the alias of the meta table and the join clause will look something like this and therefore use the JOIN twice:

'join' => string ' INNER JOIN wp_postmeta ON wp_posts.ID = wp_postmeta.post_id INNER JOIN wp_postmeta AS mt1 ON (wp_posts.ID = mt1.post_id)'

Use that in further queries or form inside your posts_clauses, posts_where or posts_join filter callbacks.

ソースファイル

WP_Meta_Query()wp-includes/meta.phpにあります。

関連

このページ「クラスリファレンス/WP Meta Query」は未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

クラスリファレンス関数リファレンスの各インデックスも参照してください。

最新英語版: WordPress Codex » Class Reference/WP Meta Query最新版との差分