MySQL :: MySQL 9.0 参考手册 :: 14.22 性能模式函数

版本 9.0

8.4 当前
8.0

8.0 日语

14.22 性能模式函数

MySQL 包含内置 SQL 函数，用于格式化或检索性能模式数据，并且可以用作相应 sys 模式存储函数的等效项。内置函数可以在任何模式中调用，并且不需要限定符，这与 sys 函数不同，后者要求使用 sys. 模式限定符或将 sys 作为当前模式。

表 14.32 性能模式函数

名称	描述
`FORMAT_BYTES()`	将字节计数转换为带单位的值
`FORMAT_PICO_TIME()`	将皮秒时间转换为带单位的值
`PS_CURRENT_THREAD_ID()`	当前线程的性能模式线程 ID
`PS_THREAD_ID()`	给定线程的性能模式线程 ID

内置函数取代了相应的已弃用的 sys 函数；预计它们将在未来版本的 MySQL 中删除。使用 sys 函数的应用程序应调整为使用内置函数，同时要注意 sys 函数和内置函数之间的一些细微差别。有关这些差异的详细信息，请参阅本节中的函数描述。

FORMAT_BYTES(count)

给定一个数字字节计数，将其转换为人类可读的格式，并返回一个由值和单位指示符组成的字符串。该字符串包含四舍五入到小数点后两位且至少包含 3 位有效数字的字节数。小于 1024 字节的数字表示为整数，并且不进行四舍五入。如果 count 为 NULL，则返回 NULL。

单位指示符取决于字节计数参数的大小，如下表所示。

参数值	结果单位	结果单位指示符
最大 1023	字节	字节
最大 1024² − 1	Kibibytes	KiB
最大 1024³ − 1	Mebibytes	MiB
最大 1024⁴ − 1	Gibibytes	GiB
最大 1024⁵ − 1	Tebibytes	TiB
最大 1024⁶ − 1	Pebibytes	PiB
1024⁶ 及以上	Exbibytes	EiB

mysql> SELECT FORMAT_BYTES(512), FORMAT_BYTES(18446644073709551615);
+-------------------+------------------------------------+
| FORMAT_BYTES(512) | FORMAT_BYTES(18446644073709551615) |
+-------------------+------------------------------------+
|  512 bytes        | 16.00 EiB                          |
+-------------------+------------------------------------+

FORMAT_BYTES() 可以用来代替 sys 模式的 format_bytes() 函数，但请注意以下区别：

FORMAT_BYTES() 使用 EiB 单位指示符。sys.format_bytes() 则不使用。

FORMAT_PICO_TIME(time_val)

给定一个以皮秒为单位的数字性能模式延迟时间或等待时间，将其转换为人类可读的格式，并返回一个由值和单位指示符组成的字符串。该字符串包含四舍五入到小数点后两位且至少包含 3 位有效数字的十进制时间。小于 1 纳秒的时间表示为整数，并且不进行四舍五入。

如果 time_val 为 NULL，则此函数返回 NULL。

单位指示符取决于时间值参数的大小，如下表所示。

参数值	结果单位	结果单位指示符
最大 10³ − 1	皮秒	ps
最大 10⁶ − 1	纳秒	ns
最大 10⁹ − 1	微秒	us
最大 10¹² − 1	毫秒	ms
最大 60×10¹² − 1	秒	s
最大 3.6×10¹⁵ − 1	分钟	min
最大 8.64×10¹⁶ − 1	小时	h
8.64×10¹⁶ 及以上	天	d

mysql> SELECT FORMAT_PICO_TIME(3501), FORMAT_PICO_TIME(188732396662000);
+------------------------+-----------------------------------+
| FORMAT_PICO_TIME(3501) | FORMAT_PICO_TIME(188732396662000) |
+------------------------+-----------------------------------+
| 3.50 ns                | 3.15 min                          |
+------------------------+-----------------------------------+

FORMAT_PICO_TIME() 可以用来代替 sys 模式的 format_time() 函数，但请注意以下区别：

为了表示分钟，sys.format_time() 使用 m 单位指示符，而 FORMAT_PICO_TIME() 使用 min。
sys.format_time() 使用 w（周）单位指示符。FORMAT_PICO_TIME() 则不使用。

PS_CURRENT_THREAD_ID()
返回一个 BIGINT UNSIGNED 值，表示分配给当前连接的性能模式线程 ID。
线程 ID 返回值是性能模式表中 THREAD_ID 列中给定类型的值。
性能模式配置对 PS_CURRENT_THREAD_ID() 的影响与对 PS_THREAD_ID() 的影响相同。有关详细信息，请参阅该函数的描述。
```
mysql> SELECT PS_CURRENT_THREAD_ID();
+------------------------+
| PS_CURRENT_THREAD_ID() |
+------------------------+
|                     52 |
+------------------------+
mysql> SELECT PS_THREAD_ID(CONNECTION_ID());
+-------------------------------+
| PS_THREAD_ID(CONNECTION_ID()) |
+-------------------------------+
|                            52 |
+-------------------------------+
```
PS_CURRENT_THREAD_ID() 可以用作调用 sys 模式 ps_thread_id() 函数的快捷方式，其参数为 NULL 或 CONNECTION_ID()。
PS_THREAD_ID(connection_id)
给定一个连接 ID，返回一个 BIGINT UNSIGNED 值，表示分配给该连接 ID 的性能模式线程 ID；如果该连接 ID 不存在线程 ID，则返回 NULL。后一种情况可能发生在未检测的线程上，或者在 connection_id 为 NULL 的情况下。
连接 ID 参数是 Performance Schema threads 表中的 PROCESSLIST_ID 列或 SHOW PROCESSLIST 输出中 Id 列给定类型的值。
线程 ID 返回值是性能模式表中 THREAD_ID 列中给定类型的值。
Performance Schema 配置对 PS_THREAD_ID() 操作的影响如下。（这些注释也适用于 PS_CURRENT_THREAD_ID()。）
- 禁用 thread_instrumentation 使用者会禁用在线程级别收集和聚合统计信息，但不会影响 PS_THREAD_ID()。
- 如果 performance_schema_max_thread_instances 不为 0，则 Performance Schema 会为线程统计信息分配内存，并为分配了实例内存的每个线程分配一个内部 ID。如果存在没有分配实例内存的线程，则 PS_THREAD_ID() 返回 NULL；在这种情况下，Performance_schema_thread_instances_lost 不为零。
- 如果 performance_schema_max_thread_instances 为 0，则 Performance Schema 不会分配线程内存，并且 PS_THREAD_ID() 返回 NULL。
- 如果 Performance Schema 本身被禁用，则 PS_THREAD_ID() 会产生错误。
```
mysql> SELECT PS_THREAD_ID(6);
+-----------------+
| PS_THREAD_ID(6) |
+-----------------+
|              45 |
+-----------------+
```
PS_THREAD_ID() 可以用来代替 sys 模式 ps_thread_id() 函数，但要注意以下区别
- 如果参数为 NULL，则 sys.ps_thread_id() 返回当前连接的线程 ID，而 PS_THREAD_ID() 返回 NULL。要获取当前连接线程 ID，请改用 PS_CURRENT_THREAD_ID()。