MySQL 9.0 參考手冊  /  語言結構  /  查詢屬性

11.6 查詢屬性

SQL 陳述式最明顯的部分是陳述式的文字。客戶端也可以定義套用至下一個傳送到伺服器執行的陳述式的查詢屬性。

  • 屬性在傳送陳述式之前定義。

  • 屬性存在直到陳述式執行結束,此時屬性集會被清除。

  • 當屬性存在時,可以在伺服器端存取它們。

查詢屬性可能的使用方式範例

  • 網頁應用程式產生產生資料庫查詢的頁面,而且每個查詢都必須追蹤產生它的頁面的 URL。

  • 應用程式會隨著每個查詢傳遞額外的處理資訊,供外掛程式(例如稽核外掛程式或查詢重寫外掛程式)使用。

MySQL 支援這些功能,而無需使用諸如包含在查詢字串中的特殊格式化註解之類的變通方法。本節的其餘部分說明如何使用查詢屬性支援,包括必須滿足的先決條件。

定義與存取查詢屬性

使用 MySQL C API 的應用程式會透過呼叫 mysql_bind_param() 函式來定義查詢屬性。請參閱 mysql_bind_param()。其他 MySQL 連接器也可能提供查詢屬性支援。請參閱個別連接器的文件。

mysql 用戶端有一個 query_attributes 命令,可讓您定義最多 32 對屬性名稱和值。請參閱 第 6.5.1.2 節,「mysql 用戶端命令」

查詢屬性名稱會使用 character_set_client 系統變數所指示的字元集傳輸。

若要在已定義屬性的 SQL 陳述式中存取查詢屬性,請安裝 query_attributes 元件,如使用查詢屬性的先決條件所述。此元件實作 mysql_query_attribute_string() 可載入函式,該函式會採用屬性名稱引數,並傳回屬性值做為字串,如果屬性不存在則傳回 NULL。請參閱查詢屬性可載入函式

下列範例使用 mysql 用戶端 query_attributes 命令來定義屬性名稱/值配對,並使用 mysql_query_attribute_string() 函式依名稱存取屬性值。

此範例會定義兩個名為 n1n2 的屬性。第一個 SELECT 會顯示如何擷取這些屬性,並示範擷取不存在的屬性 (n3) 會傳回 NULL。第二個 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   |
+--------+--------+

如第二個 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() 函式無法在 DDL 陳述式中使用。

  • 屬性不會複製。叫用 mysql_query_attribute_string() 函式的陳述式將不會在所有伺服器上取得相同的值。

使用查詢屬性的先決條件

若要在已定義屬性的 SQL 陳述式中存取查詢屬性,必須安裝 query_attributes 元件。使用此陳述式執行此操作

INSTALL COMPONENT "file://component_query_attributes";

元件安裝是一次性操作,不需要在每個伺服器啟動時都執行。INSTALL COMPONENT 會載入元件,並將其註冊在 mysql.component 系統表格中,以使其在後續伺服器啟動期間載入。

query_attributes 元件會存取查詢屬性以實作 mysql_query_attribute_string() 函式。請參閱第 7.5.4 節,「查詢屬性元件」

若要解除安裝 query_attributes 元件,請使用此陳述式

UNINSTALL COMPONENT "file://component_query_attributes";

UNINSTALL COMPONENT 會解除載入元件,並將其從 mysql.component 系統表格中取消註冊,以使其在後續伺服器啟動期間不載入。

因為安裝和解除安裝 query_attributes 元件會安裝和解除安裝元件實作的 mysql_query_attribute_string() 函式,因此不需要使用 CREATE FUNCTIONDROP FUNCTION 來執行此操作。

查詢屬性可載入函式

  • mysql_query_attribute_string(name)

    應用程式可以定義套用至下一個傳送到伺服器的查詢的屬性。mysql_query_attribute_string() 函式會傳回屬性值做為字串,並提供屬性名稱。此函式可讓查詢存取和併入適用於其的屬性值。

    安裝 query_attributes 元件即可安裝 mysql_query_attribute_string()。請參閱 第 11.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   |
    +--------+--------+--------+