Documentation Home
MySQL 8.0 リファレンスマニュアル
Download this Manual
PDF (US Ltr) - 36.1Mb
PDF (A4) - 36.2Mb

このページは機械翻訳したものです。

9.6 クエリー属性

SQL ステートメントの最も表示される部分は、ステートメントのテキストです。 MySQL 8.0.23 以降、クライアントは、実行のためにサーバーに送信される次のステートメントに適用されるクエリー属性を定義することもできます:

  • 属性は、ステートメントを送信する前に定義されます。

  • 属性はステートメントの実行が終了するまで存在し、その時点で属性セットがクリアされます。

  • 属性は存在しますが、サーバー側でアクセスできます。

クエリー属性の使用方法の例を次に示します:

  • web アプリケーションは、データベースクエリーを生成するページを生成し、クエリーごとに、そのクエリーを生成したページの URL を追跡する必要があります。

  • アプリケーションは、監査プラグインやクエリーリライトプラグインなどのプラグインで使用するために、各クエリーに追加の処理情報を渡します。

MySQL では、クエリー文字列に含まれる特別にフォーマットされたコメントなどの回避策を使用せずにこれらの機能をサポートしています。 このセクションの残りの部分では、満たす必要がある前提条件など、クエリー属性のサポートの使用方法について説明します。

クエリー属性の定義およびアクセス

MySQL C API を使用するアプリケーションでは、mysql_bind_param() 関数をコールしてクエリー属性を定義します。 mysql_bind_param()を参照してください。 その他の MySQL コネクタでは、クエリー属性のサポートも提供される場合があります。 個々のコネクタのドキュメントを参照してください。

mysql クライアントには、最大 32 の属性名と値のペアを定義できる query_attributes コマンドがあります。 セクション4.5.1.2「mysql クライアントコマンド」を参照してください。

クエリー属性名は、character_set_client システム変数で示される文字セットを使用して転送されます。

属性が定義されている SQL ステートメント内のクエリー属性にアクセスするには、クエリー属性の使用の前提条件 の説明に従って query_attributes コンポーネントをインストールします。 コンポーネントは、属性名引数を取り、属性値を文字列として返す mysql_query_attribute_string() ユーザー定義関数 (UDF) を実装します。属性が存在しない場合は NULL を返します。 クエリー属性のユーザー定義関数を参照してください。

次の例では、mysql クライアントの query_attributes コマンドを使用して属性名と値のペアを定義し、mysql_query_attribute_string() UDF を使用して名前で属性値にアクセスします。

この例では、n1 および n2 という名前の 2 つの属性を定義します。 最初の SELECT では、これらの属性を取得する方法を示し、存在しない属性 (n3) を取得すると NULL が返されることも示します。 2 番目の SELECT は、属性が複数のステートメントにわたって永続化されないことを示しています。 

mysql> query_attributes n1 v1 n2 v2;
mysql> SELECT
         mysql_query_attribute_string('n1') AS 'attr 1',
         mysql_query_attribute_string('n2') AS 'attr 2',
         mysql_query_attribute_string('n3') AS 'attr 3';
+--------+--------+--------+
| attr 1 | attr 2 | attr 3 |
+--------+--------+--------+
| v1     | v2     | NULL   |
+--------+--------+--------+

mysql> SELECT
         mysql_query_attribute_string('n1') AS 'attr 1',
         mysql_query_attribute_string('n2') AS 'attr 2';
+--------+--------+
| attr 1 | attr 2 |
+--------+--------+
| NULL   | NULL   |
+--------+--------+

2 番目の SELECT ステートメントで示されているように、特定のステートメントの前に定義された属性は、そのステートメントでのみ使用可能であり、ステートメントの実行後にクリアされます。 複数のステートメントで属性値を使用するには、属性値を変数に割り当てます。 次の例では、これを行う方法を示し、属性値が変数を使用して後続のステートメントで使用可能であり、mysql_query_attribute_string() をコールしては使用できないことを示します: 

mysql> query_attributes n1 v1 n2 v2;
mysql> SET
         @attr1 = mysql_query_attribute_string('n1'),
         @attr2 = mysql_query_attribute_string('n2');

mysql> SELECT
         @attr1, mysql_query_attribute_string('n1') AS 'attr 1',
         @attr2, mysql_query_attribute_string('n2') AS 'attr 2';
+--------+--------+--------+--------+
| @attr1 | attr 1 | @attr2 | attr 2 |
+--------+--------+--------+--------+
| v1     | NULL   | v2     | NULL   |
+--------+--------+--------+--------+

属性は、後で使用するためにテーブルに格納することで保存することもできます: 

mysql> CREATE TABLE t1 (c1 CHAR(20), c2 CHAR(20));

mysql> query_attributes n1 v1 n2 v2;
mysql> INSERT INTO t1 (c1, c2) VALUES(
         mysql_query_attribute_string('n1'),
         mysql_query_attribute_string('n2')
       );

mysql> SELECT * FROM t1;
+------+------+
| c1   | c2   |
+------+------+
| v1   | v2   |
+------+------+

クエリー属性には、次の制限事項があります:

  • サーバーにステートメントを送信して実行する前に複数の属性定義操作が発生した場合、最新の定義操作が適用され、以前の操作で定義された属性が置換されます。

  • 複数の属性が同じ名前で定義されている場合、属性値を取得しようとすると未定義の結果になります。

  • 空の名前で定義された属性は名前で取得できません。

  • 属性は、PREPARE で準備されたステートメントでは使用できません。

  • mysql_query_attribute_string() UDF は DDL ステートメントでは使用できません。

  • 属性はレプリケートされません。 mysql_query_attribute_string() UDF を呼び出すステートメントは、すべてのサーバーで同じ値を取得するわけではありません。

クエリー属性の使用の前提条件

属性が定義されている SQL ステートメント内のクエリー属性にアクセスするには、query_attributes コンポーネントをインストールする必要があります。 これを行うには、次のステートメントを使用します: 

INSTALL COMPONENT "file://component_query_attributes";

コンポーネントのインストールは、サーバーの起動ごとに実行する必要のない一度限りの操作です。 INSTALL COMPONENT によってコンポーネントがロードされ、mysql.component システムテーブルにも登録されて、後続のサーバー起動時にロードされます。

query_attributes コンポーネントは、クエリー属性にアクセスして mysql_query_attribute_string() UDF を実装します。 セクション5.5.4「クエリー属性コンポーネント」を参照してください。

query_attributes コンポーネントをアンインストールするには、次のステートメントを使用します: 

UNINSTALL COMPONENT "file://component_query_attributes";

UNINSTALL COMPONENT はコンポーネントをアンロードし、mysql.component システムテーブルから登録解除して、後続のサーバー起動時にロードされないようにします。

query_attributes コンポーネントをインストールおよびアンインストールすると、コンポーネントが実装する mysql_query_attribute_string() 関数がインストールおよびアンインストールされるため、CREATE FUNCTION または DROP FUNCTION を使用して行う必要はありません。

クエリー属性のユーザー定義関数

  • mysql_query_attribute_string(name)

    アプリケーションでは、サーバーに送信される次のクエリーに適用される属性を定義できます。 MySQL 8.0.23 で使用可能な mysql_query_attribute_string() 関数は、属性名を指定して属性値を文字列として戻します。 この関数を使用すると、クエリーは、クエリーに適用される属性の値にアクセスして組み込むことができます。

    mysql_query_attribute_string() は、query_attributes コンポーネントをインストールすることによってインストールされます。 クエリー属性の目的および使用方法についても説明している セクション9.6「クエリー属性」 を参照してください。

    引数:

    • name: 属性名。

    戻り値:

    成功した場合は文字列として属性値を返し、属性が存在しない場合は NULL を返します。

    例:

    次の例では、mysql クライアントの query_attributes コマンドを使用して、mysql_query_attribute_string() で取得できるクエリー属性を定義します。 SELECT は、存在しない属性 (n3) を取得すると NULL が返されることを示しています。 

    mysql> query_attributes n1 v1 n2 v2;
mysql> SELECT
    ->   mysql_query_attribute_string('n1') AS 'attr 1',
    ->   mysql_query_attribute_string('n2') AS 'attr 2',
    ->   mysql_query_attribute_string('n3') AS 'attr 3';
+--------+--------+--------+
| attr 1 | attr 2 | attr 3 |
+--------+--------+--------+
| v1     | v2     | NULL   |
+--------+--------+--------+

PREV   HOME   UP   NEXT
Download this Manual
PDF (US Ltr) - 36.1Mb
PDF (A4) - 36.2Mb