MySQL :: MySQL 8.4 參考手冊 :: 14.21 Performance Schema 函式

版本 8.4

9.0
8.0

8.0 日文

MySQL 8.4 參考手冊 / 函式與運算子 / Performance Schema 函式

14.21 Performance Schema 函式

MySQL 包含內建的 SQL 函式，可格式化或擷取 Performance Schema 資料，並且可用作對應 sys 綱要預存函式的替代方案。與 sys 函式不同的是，內建函式可以在任何綱要中叫用，並且不需要限定詞，sys 函式則需要 sys. 綱要限定詞，或是 sys 作為目前的綱要。

表 14.31 Performance Schema 函式

名稱	描述
`FORMAT_BYTES()`	將位元組計數轉換為帶有單位的數值
`FORMAT_PICO_TIME()`	將皮秒時間轉換為帶有單位的數值
`PS_CURRENT_THREAD_ID()`	目前執行緒的 Performance Schema 執行緒 ID
`PS_THREAD_ID()`	指定執行緒的 Performance Schema 執行緒 ID

內建函式取代對應的 sys 函式，後者已棄用；預計在未來版本的 MySQL 中移除。使用 sys 函式的應用程式應調整為改用內建函式，並注意 sys 函式與內建函式之間的一些細微差異。有關這些差異的詳細資訊，請參閱本節中的函式描述。

FORMAT_BYTES(count)

給定數值位元組計數，將其轉換為人類可讀的格式，並傳回一個包含數值和單位指示符的字串。該字串包含四捨五入到小數點後 2 位，且至少有 3 個有效數字的位元組數。小於 1024 位元組的數字會以整數表示，不會四捨五入。如果 count 為 NULL，則傳回 NULL。

單位指示符取決於位元組計數引數的大小，如下表所示。

引數值	結果單位	結果單位指示符
最多 1023	位元組	位元組
最多 1024² − 1	千位元組	KiB
最多 1024³ − 1	百萬位元組	MiB
最多 1024⁴ − 1	吉位元組	GiB
最多 1024⁵ − 1	兆位元組	TiB
最多 1024⁶ − 1	拍位元組	PiB
1024⁶ 及以上	艾位元組	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)

給定以皮秒為單位的數值 Performance Schema 延遲或等待時間，將其轉換為人類可讀的格式，並傳回一個包含數值和單位指示符的字串。該字串包含四捨五入到小數點後 2 位，且至少有 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	分鐘	分
最多 8.64×10¹⁶ − 1	小時	小時
8.64×10¹⁶ 及以上	天	天

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_THREAD_ID() 相同的方式影響 PS_CURRENT_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 引數是效能結構描述 threads 資料表的 PROCESSLIST_ID 欄位或 SHOW PROCESSLIST 輸出的 Id 欄位中給定的類型的值。
傳回的執行緒 ID 值是效能結構描述資料表中 THREAD_ID 欄位中給定的類型的值。
效能結構描述組態會如下影響 PS_THREAD_ID() 的運作。（這些說明也適用於 PS_CURRENT_THREAD_ID()。）
- 停用 thread_instrumentation 取用者會停用在執行緒層級收集和彙總的統計資料，但不會影響 PS_THREAD_ID()。
- 如果 performance_schema_max_thread_instances 不為 0，則效能結構描述會配置記憶體來存放執行緒統計資料，並為每個有執行個體記憶體可用的執行緒指派一個內部 ID。如果有些執行緒沒有可用的執行個體記憶體，則 PS_THREAD_ID() 會傳回 NULL；在這種情況下，Performance_schema_thread_instances_lost 為非零值。
- 如果 performance_schema_max_thread_instances 為 0，則效能結構描述不會配置執行緒記憶體，且 PS_THREAD_ID() 會傳回 NULL。
- 如果效能結構描述本身已停用，則 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()。