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

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

「クラスリファレンス/WP Meta Query」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(ページ追加)
 
1行目: 1行目:
 
==説明==
 
==説明==
  
WP_Meta_Query is a class defined in wp-includes/meta.php that generates the necessary SQL for meta-related queries. It was introduced in Version 3.2.0 and greatly improved the possibility to query posts by custom fields. In the WP core, it's used in the [[Class_Reference/WP_Query#Custom_Field_Parameters|WP_Query]] and [[Class_Reference/WP_User_Query#Custom_Field_Parameters|WP_User_Query]] classes, and since Version 3.5 in the [[Class_Reference/WP_Comment_Query#Custom_Field_Parameters|WP_Comment_Query]] class. Unless you're writing a custom SQL query, you should look in the *Custom Field Parameters* section for the corresponding class.
+
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 のコアでは、[[Class_Reference/WP_Query#Custom_Field_Parameters|WP_Query]] [[Class_Reference/WP_User_Query#Custom_Field_Parameters|WP_User_Query]]クラス、since Version 3.5以降では、[[Class_Reference/WP_Comment_Query#Custom_Field_Parameters|WP_Comment_Query]] クラス内で使用されています。
 +
 
 +
Unless you're writing a custom SQL query, you should look in the *Custom Field Parameters* section for the corresponding class.
  
 
==使い方==
 
==使い方==
8行目: 12行目:
 
===引数の受け入れ===
 
===引数の受け入れ===
 
</div>
 
</div>
The following arguments can be passed in a key=>value paired array.
 
  
* '''<tt>meta_key</tt>''' (''string'') - カスタムフィールドのキー( 自分でサニタイズが必要)
+
次の引数は、key=>valueペアの配列で渡すことができます。
* '''<tt>meta_value</tt>''' (''string|array'') - カスタムフィールドの値 ( 自分でサニタイズが必要)
+
 
 +
* '''<tt>meta_key</tt>''' (''文字列'') - カスタムフィールドのキー( 自分でサニタイズが必要)
 +
* '''<tt>meta_value</tt>''' (''文字列|配列'') - カスタムフィールドの値 ( 自分でサニタイズが必要)
 
* '''<tt>meta_type</tt>''' (''number'') - カスタムフィールドタイプ (以下の '''<tt>type</tt>''' オプションを参照)
 
* '''<tt>meta_type</tt>''' (''number'') - カスタムフィールドタイプ (以下の '''<tt>type</tt>''' オプションを参照)
* '''<tt>meta_compare</tt>''' (''string'') - Operator to test the <tt>'meta_value'</tt> (参照 '''<tt>compare</tt>''' below for possible values).
+
* '''<tt>meta_compare</tt>''' (''文字列'') -<tt>'meta_value'</tt>をテストする演算子 (参照 '''<tt>compare</tt>''' 以下の使用可能な値)
  
* '''<tt>meta_query</tt>''' (''array'') - Contains one or more arrays with the following keys:
+
* '''<tt>meta_query</tt>''' (''配列'') - 以下のキーで一つ以上の配列を含みます:
** '''<tt>key</tt>''' (''string'') - カスタムフィールドキー
+
** '''<tt>key</tt>''' (''文字列'') - カスタムフィールドキー
** '''<tt>value</tt>''' (''string''|''array'') - カスタムフィールドの値。 It can be an array only when <tt>'''compare'''</tt> is <tt>'IN'</tt>, <tt>'NOT IN'</tt>, <tt>'BETWEEN'</tt>, or <tt>'NOT BETWEEN'</tt>. You don't have to specify a value when using the <tt>'EXISTS'</tt> or <tt>'NOT EXISTS'</tt> comparisons in WordPress 3.9 and up. <br>(<strong>Note:</strong> Due to [http://core.trac.wordpress.org/ticket/23268 bug #23268], <tt>value</tt> was required for <tt>NOT EXISTS</tt> comparisons to work correctly prior to 3.9. You had to supply ''some'' string for the <tt>value</tt> parameter. An empty string or <tt>NULL</tt> will NOT work. However, any other string will do the trick and will NOT show up in your SQL when using <tt>NOT EXISTS</tt>. Need inspiration? How about <tt>'bug #23268'</tt>.)
+
** '''<tt>value</tt>''' (''文字列''|''配列'') - カスタムフィールドの値。<tt>'''compare'''</tt><tt>'IN'</tt>, <tt>'NOT IN'</tt>, <tt>'BETWEEN'</tt>,または <tt>'NOT BETWEEN'</tt>の時のみ、配列にできる。
** '''<tt>compare</tt>''' (''string'') - Operator to test. Possible values are '=', '!=', '>', '>=', '<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'EXISTS' (only in WP >= 3.5), and 'NOT EXISTS' (also only in WP >= 3.5). Values 'REGEXP', 'NOT REGEXP' and 'RLIKE' were added in WordPress 3.7. Default value is '='.
+
You don't have to specify a value when using the <tt>'EXISTS'</tt> or <tt>'NOT EXISTS'</tt> comparisons in WordPress 3.9以降で。<br>
** '''<tt>type</tt>''' (''string'') - カスタムフィールドの型。 有効な値は、 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'. デフォルト値は、'CHAR'.
+
(<strong>注意:</strong>[http://core.trac.wordpress.org/ticket/23268 bug #23268]のため、<tt>value</tt> was required for <tt>NOT EXISTS</tt> comparisons to work correctly prior to 3.9.  
 +
<tt>value</tt>パラメータに''some''文字列を指定する必要がありました。
 +
空の文字列または <tt>NULL</tt> は動作しません。 However, any other string will do the trick and will NOT show up in your SQL when using <tt>NOT EXISTS</tt>. インスピレーションが必要ですか? <tt>'bug #23268'</tt>はどうですか?)
 +
** '''<tt>compare</tt>''' (''文字列'') - テストする演算子。可能な値は、 '=', '!=', '>', '>=', '<', '<=', '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で追加されました。 デフォルト値は '='
 +
** '''<tt>type</tt>''' (''文字列'') - カスタムフィールドの型。 有効な値は、 'NUMERIC', 'BINARY', 'CHAR', 'DATE', 'DATETIME', 'DECIMAL', 'SIGNED', 'TIME', 'UNSIGNED'. デフォルト値は、'CHAR'
  
 
The <tt>'type'</tt> <tt>DATE</tt> works with the <tt>'compare'</tt> value <tt>BETWEEN</tt> only if the date is stored at the format <tt>YYYY-MM-DD</tt> and tested with this format.
 
The <tt>'type'</tt> <tt>DATE</tt> works with the <tt>'compare'</tt> value <tt>BETWEEN</tt> only if the date is stored at the format <tt>YYYY-MM-DD</tt> and tested with this format.
  
<em>注:</em> The <tt>'meta_key'</tt>, <tt>'meta_value'</tt>, <tt>'meta_type'</tt> and <tt>'meta_compare'</tt> arguments will only work if you use the second method described below.
+
<em>注:</em> <tt>'meta_key'</tt><tt>'meta_value'</tt><tt>'meta_type'</tt><tt>'meta_compare'</tt>引数は下の 2 番目の方法を使用している場合のみ動作します。
  
 
===WP_Meta_Query のイニシャライズ(初期化)===
 
===WP_Meta_Query のイニシャライズ(初期化)===
  
You generally have two options on how to initialize and use a new WP_Meta_Query object:
+
一般的には、初期化するか、new WP_Meta_Query オブジェクトを使う2つのオプションがあります。
  
<b>Passing an Array of query parameters to the constructor:</b>
+
<b>コンストラクタにクエリパラメータの配列を渡します:</b>
  
 
<pre>
 
<pre>
 
$meta_query_args = array(
 
$meta_query_args = array(
'relation' => 'OR', // Optional, defaults to "AND"
+
'relation' => 'OR', // オプション、デフォルト値は "AND"
 
array(
 
array(
 
'key'    => '_my_custom_key',
 
'key'    => '_my_custom_key',
43行目: 52行目:
 
</pre>
 
</pre>
  
In this case, you pass an array of key/value pair arrays(which were described above in the <b>meta_query</b> argument).
+
この事例では、(<b>meta_query</b> の引数で上述した)キー/値のペアの配列の配列を渡します。
  
You can optionally pass the `relation` key and set it to either <b>OR</b> or <b>AND</b>. 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).  
+
You can optionally pass the `relation` key and set it to either <b>OR</b> or <b>AND</b>.  
 +
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).  
  
<b>Using the WP_Meta_Query::parse_query_vars( $query ) method:</b>
+
<b>WP_Meta_Query::parse_query_vars( $query ) メソッドを使う:</b>
You can use this method, if you want to use the simple query args(`meta_key`, `meta_value`, `meta_type`, `meta_compare`), or if you are unsure of the presence of meta query parameters.
+
 
 +
(`meta_key`, `meta_value`, `meta_type`, `meta_compare`)を単純なクエリの引数に使用する場合、または、メタクエリパラメータの存在が不明な場合、このメソッドを使用することができます。
 
<pre>
 
<pre>
 
// $query_vars can have various contents, so an example is not added here, but you need to have it defined beforehand
 
// $query_vars can have various contents, so an example is not added here, but you need to have it defined beforehand
62行目: 73行目:
 
===最終的なSQLを取得する===
 
===最終的なSQLを取得する===
 
</div>
 
</div>
You can retrieve the generated SQL by using the following method.
+
 
 +
以下の方法を使用して生成されたSQLを取得できます。
  
 
<pre>$mq_sql = $meta_query->get_sql(
 
<pre>$mq_sql = $meta_query->get_sql(
71行目: 83行目:
 
);</pre>
 
);</pre>
  
List of Arguments:
+
引数のリスト:
  
* '''<tt>$type</tt>''' (''string'') - metaの型(''post'', ''comment'', ''user''').
+
* '''<tt>$type</tt>''' (''文字列'') - metaの型(''post'', ''comment'', ''user''').
* '''<tt>$primary_table</tt>''' (''string'') - The table where we will be looking for rows. You can pass for instance <code>$wpdb->posts</code>, or the alias name if you are aliasing the table in your SQL query
+
* '''<tt>$primary_table</tt>''' (''文字列'') - 列を探しているテーブル。<code>$wpdb->posts</code>のインスタンスを渡すことができる、または、エイリアス名、 SQL クエリーでは、テーブルエイリアスする場合
* '''<tt>$primary_id_column</tt>''' (''string'') - The column that holds the ID(for posts, it is ''ID'', for comments it is ''comment_ID'' and for users is ''ID'').
+
* '''<tt>$primary_id_column</tt>''' (''文字列'') - IDを保持する列 (投稿では ''ID'', コメントでは ''comment_ID'' ユーザーでは ''ID'').
* '''<tt>$context</tt>''' (''object'') - オプション - The main query object. It is only used when the result is passed to the ''get_meta_sql'' filter.
+
* '''<tt>$context</tt>''' (''オブジェクト'') - オプション - メインのクエリオブジェクト。結果は''get_meta_sql''フィルタに渡されたときにのみ使用されます。
  
On failure(for instance - lacking any meta query parameters in the query array), this function will return `false`.
+
失敗時には(たとえば、クエリ配列の任意のメタクエリパラメータが不足している)、 この関数は `false`を返します。
 +
 
 +
成功時には、このような配列を返します:
  
On success, it will return an array like this:
 
 
<pre>
 
<pre>
 
array(
 
array(
87行目: 100行目:
 
)
 
)
 
</pre>
 
</pre>
With each key holding the SQL for the corresponding section.
 
  
'''例: Single Meta Entry - Flat array'''
+
各キーに対応するセクションのSQLを保持する。
 +
 
 +
'''例: シングルメタエントリー - フラット配列'''
  
 
''クエリ''
 
''クエリ''
114行目: 128行目:
 
   'where' => string ' AND (wp_postmeta.meta_key = 'some_key' )' (length=40)</pre>
 
   'where' => string ' AND (wp_postmeta.meta_key = 'some_key' )' (length=40)</pre>
  
'''例: Multiple Meta Entries - Multi dimensional array:'''
+
'''例: 複数のメタエントリ - 多次元配列:'''
  
 
''クエリ:''
 
''クエリ:''
143行目: 157行目:
 
'where' => string ' AND (wp_postmeta.meta_key = 'foo_key' OR wp_postmeta.meta_key = 'bar_key' )' (length=75)</pre>
 
'where' => string ' AND (wp_postmeta.meta_key = 'foo_key' OR wp_postmeta.meta_key = 'bar_key' )' (length=75)</pre>
  
''Note: This example will '''not''' append a space to the <tt>join</tt> statement, so you have to do it manually to not crash your query. The same goes for the <tt>where</tt> statement.''
+
'': この例は、 will '''not''' append a space to the <tt>join</tt> statement, so you have to do it manually to not crash your query. The same goes for the <tt>where</tt> statement.''
  
 
If you're using the <tt>value</tt> and <tt>compare</tt> parts of the <tt>meta_query</tt> input argument array, then the query string will look something like the following:
 
If you're using the <tt>value</tt> and <tt>compare</tt> parts of the <tt>meta_query</tt> input argument array, then the query string will look something like the following:

2015年9月2日 (水) 22:28時点における版

説明

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最新版との差分