Documentation Home
MySQL 8.4 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 40.0Mb
PDF (A4) - 40.1Mb
Man Pages (TGZ) - 258.5Kb
Man Pages (Zip) - 365.7Kb
Info (Gzip) - 4.0Mb
Info (Zip) - 4.0Mb


MySQL 8.4 Reference Manual  /  Functions and Operators  /  Performance Schema Functions

14.21 Performance Schema Functions

MySQL includes built-in SQL functions that format or retrieve Performance Schema data, and that may be used as equivalents for the corresponding sys schema stored functions. The built-in functions can be invoked in any schema and require no qualifier, unlike the sys functions, which require either a sys. schema qualifier or that sys be the current schema.

Table 14.31 Performance Schema Functions

Name Description
FORMAT_BYTES() Convert byte count to value with units
FORMAT_PICO_TIME() Convert time in picoseconds to value with units
PS_CURRENT_THREAD_ID() Performance Schema thread ID for current thread
PS_THREAD_ID() Performance Schema thread ID for given thread

The built-in functions supersede the corresponding sys functions, which are deprecated; expect them to be removed in a future version of MySQL. Applications that use the sys functions should be adjusted to use the built-in functions instead, keeping in mind some minor differences between the sys functions and the built-in functions. For details about these differences, see the function descriptions in this section.

  • FORMAT_BYTES(count)

    Given a numeric byte count, converts it to human-readable format and returns a string consisting of a value and a units indicator. The string contains the number of bytes rounded to 2 decimal places and a minimum of 3 significant digits. Numbers less than 1024 bytes are represented as whole numbers and are not rounded. Returns NULL if count is NULL.

    The units indicator depends on the size of the byte-count argument as shown in the following table.

    Argument Value Result Units Result Units Indicator
    Up to 1023 bytes bytes
    Up to 10242 − 1 kibibytes KiB
    Up to 10243 − 1 mebibytes MiB
    Up to 10244 − 1 gibibytes GiB
    Up to 10245 − 1 tebibytes TiB
    Up to 10246 − 1 pebibytes PiB
    10246 and up exbibytes EiB
    mysql> SELECT FORMAT_BYTES(512), FORMAT_BYTES(18446644073709551615);
    +-------------------+------------------------------------+
    | FORMAT_BYTES(512) | FORMAT_BYTES(18446644073709551615) |
    +-------------------+------------------------------------+
    |  512 bytes        | 16.00 EiB                          |
    +-------------------+------------------------------------+

    FORMAT_BYTES() may be used instead of the sys schema format_bytes() function, keeping in mind this difference:

  • FORMAT_PICO_TIME(time_val)

    Given a numeric Performance Schema latency or wait time in picoseconds, converts it to human-readable format and returns a string consisting of a value and a units indicator. The string contains the decimal time rounded to 2 decimal places and a minimum of 3 significant digits. Times under 1 nanosecond are represented as whole numbers and are not rounded.

    If time_val is NULL, this function returns NULL.

    The units indicator depends on the size of the time-value argument as shown in the following table.

    Argument Value Result Units Result Units Indicator
    Up to 103 − 1 picoseconds ps
    Up to 106 − 1 nanoseconds ns
    Up to 109 − 1 microseconds us
    Up to 1012 − 1 milliseconds ms
    Up to 60×1012 − 1 seconds s
    Up to 3.6×1015 − 1 minutes min
    Up to 8.64×1016 − 1 hours h
    8.64×1016 and up days 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() may be used instead of the sys schema format_time() function, keeping in mind these differences:

  • PS_CURRENT_THREAD_ID()

    Returns a BIGINT UNSIGNED value representing the Performance Schema thread ID assigned to the current connection.

    The thread ID return value is a value of the type given in the THREAD_ID column of Performance Schema tables.

    Performance Schema configuration affects PS_CURRENT_THREAD_ID() the same way as for PS_THREAD_ID(). For details, see the description of that function.

    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() may be used as a shortcut for invoking the sys schema ps_thread_id() function with an argument of NULL or CONNECTION_ID().

  • PS_THREAD_ID(connection_id)

    Given a connection ID, returns a BIGINT UNSIGNED value representing the Performance Schema thread ID assigned to the connection ID, or NULL if no thread ID exists for the connection ID. The latter can occur for threads that are not instrumented, or if connection_id is NULL.

    The connection ID argument is a value of the type given in the PROCESSLIST_ID column of the Performance Schema threads table or the Id column of SHOW PROCESSLIST output.

    The thread ID return value is a value of the type given in the THREAD_ID column of Performance Schema tables.

    Performance Schema configuration affects PS_THREAD_ID() operation as follows. (These remarks also apply to PS_CURRENT_THREAD_ID().)

    mysql> SELECT PS_THREAD_ID(6);
    +-----------------+
    | PS_THREAD_ID(6) |
    +-----------------+
    |              45 |
    +-----------------+

    PS_THREAD_ID() may be used instead of the sys schema ps_thread_id() function, keeping in mind this difference: