Related Documentation Download this Manual
PDF (US Ltr) - 40.8Mb
PDF (A4) - 40.9Mb
Man Pages (TGZ) - 294.0Kb
Man Pages (Zip) - 409.0Kb
Info (Gzip) - 4.0Mb
Info (Zip) - 4.0Mb
Excerpts from this Manual

MySQL 8.3 Reference Manual  /  Language Structure  /  Query Attributes

11.6 查询属性

SQL 语句的最明显部分是语句文本。客户端还可以定义查询属性,以应用于下一个发送到服务器以执行的语句:

  • 属性是在发送语句之前定义的。

  • 属性存在直到语句执行结束,此时属性集将被清除。

  • 在属性存在期间,可以在服务器端访问它们。

查询属性可能被使用的示例:

  • Web 应用程序生成页面,生成数据库查询,并且每个查询都需要跟踪生成它的页面 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 准备的语句。

  • 不能在 DDL 语句中使用 mysql_query_attribute_string() 函数。

  • 属性不被复制。调用 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() 函数返回给定名称的属性值作为字符串,启用查询访问和合并适用于它的属性值。

    mysql_query_attribute_string() 由安装 query_attributes 组件安装。请参阅 第 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   |
    +--------+--------+--------+