MySQL :: MySQL 8.4 参考手册 :: 14.21 性能模式函数

版本 8.4

9.0
8.0

8.0 日语

14.21 性能模式函数

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

表 14.31 性能模式函数

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

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

FORMAT_BYTES(count)

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

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

参数值	结果单位	结果单位指示符
不超过 1023	字节	字节
不超过 1024² − 1	Kibibyte	KiB
不超过 1024³ − 1	Mebibyte	MiB
不超过 1024⁴ − 1	Gibibyte	GiB
不超过 1024⁵ − 1	Tebibyte	TiB
不超过 1024⁶ − 1	Pebibyte	PiB
1024⁶ 及以上	Exbibyte	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)

给定一个以皮秒为单位的数字性能模式延迟时间或等待时间，将其转换为人类可读的格式，并返回一个由值和单位指示符组成的字符串。该字符串包含四舍五入到小数点后两位且至少包含三位有效数字的十进制时间。小于 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()。