From cc193733f8415e675b901e4a79bf8edcd8f19138 Mon Sep 17 00:00:00 2001 From: nolouch Date: Wed, 3 Jun 2026 13:17:23 -0700 Subject: [PATCH 01/16] docs: add statement summary system variables --- statement-summary-tables.md | 4 ++++ system-variable-reference.md | 16 ++++++++++++++++ system-variables.md | 22 ++++++++++++++++++++++ 3 files changed, 42 insertions(+) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index 6cf25a383449f..ee703c40bbb2b 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,6 +87,7 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. +> - Starting from v8.5.7, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to further aggregate statement summaries by execution user. When the variable value is `ON`, the same SQL digest executed by different users is collected as different records, and the `SAMPLE_USER` field of each record indicates the execution user corresponding to the record. ## `statements_summary_history` @@ -144,6 +145,8 @@ The following system variables are used to control the statement summary: - `tidb_stmt_summary_max_sql_length`: Specifies the longest display length of `DIGEST_TEXT` and `QUERY_SAMPLE_TEXT`. The default value is `4096`. - `tidb_stmt_summary_internal_query`: Determines whether to count the TiDB SQL statements. `1` means to count, and `0` means not to count. The default value is `0`. +- `tidb_stmt_summary_group_by_user`: Determines whether to further aggregate statement summaries by execution user. `1` means to aggregate by user, and `0` means not to aggregate by user. The default value is `0`. After this variable is enabled, the same SQL digest executed by different users is aggregated into different rows, which might increase the number of statement summary records and memory usage. Modifying this variable clears the current in-memory statement summary data. +- `tidb_stmt_summary_persist_evicted`: Determines whether to write statement summary records that are evicted by LRU to the statement summary log after [statements summary persistence](#persist-statements-summary) is enabled. `1` means to write, and `0` means not to write. The default value is `0`. After this variable is enabled, the log contains JSON records marked with `"evicted": true`, and the amount of logs increases as LRU evictions become more frequent. An example of the statement summary configuration is shown as follows: @@ -261,6 +264,7 @@ After statements summary persistence is enabled, the memory keeps only the curre > > - When statements summary persistence is enabled, the `tidb_stmt_summary_history_size` configuration described in the [Parameter configuration](#parameter-configuration) section will no longer take effect because the memory does not keep the history data. Instead, the following three configurations will be used to control the retention period and size of history data for persistence: [`tidb_stmt_summary_file_max_days`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_days-new-in-v660), [`tidb_stmt_summary_file_max_size`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_size-new-in-v660), and [`tidb_stmt_summary_file_max_backups`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_backups-new-in-v660). > - The smaller the value of `tidb_stmt_summary_refresh_interval`, the more immediate data is written to the disk. However, this also means more redundant data is written to the disk. +> - Starting from v8.5.7, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. The written JSON records are marked with `"evicted": true` for downstream log consumers to identify and are not returned as query results of `statements_summary_history` or `cluster_statements_summary_history`. diff --git a/system-variable-reference.md b/system-variable-reference.md index 5e33e28c63a9d..c5b82544dca8e 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -3955,6 +3955,14 @@ Referenced in: - [TiDB Configuration File](/tidb-configuration-file.md) - [TiDB 6.6.0 Release Notes](/releases/release-6.6.0.md) +### tidb_stmt_summary_group_by_user + +Referenced in: + +- [SHOW [GLOBAL|SESSION] VARIABLES](/sql-statements/sql-statement-show-variables.md) +- [Statement Summary Tables](/statement-summary-tables.md) +- [System Variables](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) + ### tidb_stmt_summary_history_size Referenced in: @@ -3999,6 +4007,14 @@ Referenced in: - [TiDB 5.0.4 Release Notes](/releases/release-5.0.4.md) - [TiDB 4.0.14 Release Notes](/releases/release-4.0.14.md) +### tidb_stmt_summary_persist_evicted + +Referenced in: + +- [SHOW [GLOBAL|SESSION] VARIABLES](/sql-statements/sql-statement-show-variables.md) +- [Statement Summary Tables](/statement-summary-tables.md) +- [System Variables](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) + ### tidb_stmt_summary_refresh_interval Referenced in: diff --git a/system-variables.md b/system-variables.md index a0b7046ec5c24..3d69277dc5c6d 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6254,6 +6254,17 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). +### tidb_stmt_summary_group_by_user New in v8.5.7 + +- Scope: GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Boolean +- Default value: `OFF` +- This variable controls whether to include the user that executes SQL statements as an aggregation dimension in [statement summary tables](/statement-summary-tables.md). When the variable value is `OFF`, the same SQL digest executed by different users is aggregated into the same row, and the `SAMPLE_USER` field displays one sampled user. When the variable value is `ON`, the same SQL digest executed by different users is aggregated into different rows, and the `SAMPLE_USER` field of each row indicates the execution user corresponding to the row. +- Modifying this variable clears the current in-memory statement summary data because data before and after the modification uses different aggregation dimensions. Historical data that has been persisted to the disk is not affected. +- After this variable is enabled, the number of statement summary records might increase with the number of different execution users for the same SQL digest, which increases memory usage. + ### tidb_stmt_summary_history_size New in v4.0 > **Note:** @@ -6329,6 +6340,17 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). +### tidb_stmt_summary_persist_evicted New in v8.5.7 + +- Scope: GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Boolean +- Default value: `OFF` +- This variable controls whether to write statement summary records that are evicted by LRU to the statement summary log after [statements summary persistence](/statement-summary-tables.md#persist-statements-summary) is enabled. The written JSON records are marked with `"evicted": true` for downstream log consumers to identify. +- This variable takes effect only for the persistent implementation of statement summary. Records marked with `"evicted": true` are not returned as query results of `statements_summary_history` or `cluster_statements_summary_history`. +- After this variable is enabled, the amount of statement summary logs increases as LRU evictions become more frequent. Evicted records are written by using an asynchronous buffer mechanism. When the buffer queue is full, new evicted records might be dropped. + ### tidb_stmt_summary_refresh_interval New in v4.0 > **Note:** From b41b1e3e56881839acd909659cebb15465888d91 Mon Sep 17 00:00:00 2001 From: nolouch Date: Wed, 3 Jun 2026 13:23:28 -0700 Subject: [PATCH 02/16] docs: address statement summary review comments --- statement-summary-tables.md | 8 ++++---- system-variables.md | 12 ++++++------ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index ee703c40bbb2b..ae0fe5ac39ef2 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,7 +87,7 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. -> - Starting from v8.5.7, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to further aggregate statement summaries by execution user. When the variable value is `ON`, the same SQL digest executed by different users is collected as different records, and the `SAMPLE_USER` field of each record indicates the execution user corresponding to the record. +> - Starting from v8.5.7, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. ## `statements_summary_history` @@ -145,8 +145,8 @@ The following system variables are used to control the statement summary: - `tidb_stmt_summary_max_sql_length`: Specifies the longest display length of `DIGEST_TEXT` and `QUERY_SAMPLE_TEXT`. The default value is `4096`. - `tidb_stmt_summary_internal_query`: Determines whether to count the TiDB SQL statements. `1` means to count, and `0` means not to count. The default value is `0`. -- `tidb_stmt_summary_group_by_user`: Determines whether to further aggregate statement summaries by execution user. `1` means to aggregate by user, and `0` means not to aggregate by user. The default value is `0`. After this variable is enabled, the same SQL digest executed by different users is aggregated into different rows, which might increase the number of statement summary records and memory usage. Modifying this variable clears the current in-memory statement summary data. -- `tidb_stmt_summary_persist_evicted`: Determines whether to write statement summary records that are evicted by LRU to the statement summary log after [statements summary persistence](#persist-statements-summary) is enabled. `1` means to write, and `0` means not to write. The default value is `0`. After this variable is enabled, the log contains JSON records marked with `"evicted": true`, and the amount of logs increases as LRU evictions become more frequent. +- `tidb_stmt_summary_group_by_user`: Determines whether to aggregate statement summaries by execution user. `1` means to aggregate by user, and `0` means not to aggregate by user. The default value is `0`. After you enable this variable, TiDB aggregates the same SQL digest executed by different users into separate rows, which might increase the number of statement summary records and memory usage. Modifying this variable clears the current in-memory statement summary data. +- `tidb_stmt_summary_persist_evicted`: Determines whether to write statement summary records evicted by LRU to the statement summary log after you enable [statements summary persistence](#persist-statements-summary). `1` means to write, and `0` means not to write. The default value is `0`. After you enable this variable, the log contains JSON records marked with `"evicted": true`, and the log volume increases as LRU evictions become more frequent. An example of the statement summary configuration is shown as follows: @@ -264,7 +264,7 @@ After statements summary persistence is enabled, the memory keeps only the curre > > - When statements summary persistence is enabled, the `tidb_stmt_summary_history_size` configuration described in the [Parameter configuration](#parameter-configuration) section will no longer take effect because the memory does not keep the history data. Instead, the following three configurations will be used to control the retention period and size of history data for persistence: [`tidb_stmt_summary_file_max_days`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_days-new-in-v660), [`tidb_stmt_summary_file_max_size`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_size-new-in-v660), and [`tidb_stmt_summary_file_max_backups`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_backups-new-in-v660). > - The smaller the value of `tidb_stmt_summary_refresh_interval`, the more immediate data is written to the disk. However, this also means more redundant data is written to the disk. -> - Starting from v8.5.7, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. The written JSON records are marked with `"evicted": true` for downstream log consumers to identify and are not returned as query results of `statements_summary_history` or `cluster_statements_summary_history`. +> - Starting from v8.5.7, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. diff --git a/system-variables.md b/system-variables.md index 3d69277dc5c6d..cdf9d1674ff28 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6261,9 +6261,9 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: Boolean - Default value: `OFF` -- This variable controls whether to include the user that executes SQL statements as an aggregation dimension in [statement summary tables](/statement-summary-tables.md). When the variable value is `OFF`, the same SQL digest executed by different users is aggregated into the same row, and the `SAMPLE_USER` field displays one sampled user. When the variable value is `ON`, the same SQL digest executed by different users is aggregated into different rows, and the `SAMPLE_USER` field of each row indicates the execution user corresponding to the row. -- Modifying this variable clears the current in-memory statement summary data because data before and after the modification uses different aggregation dimensions. Historical data that has been persisted to the disk is not affected. -- After this variable is enabled, the number of statement summary records might increase with the number of different execution users for the same SQL digest, which increases memory usage. +- This variable controls whether to include the user who executes SQL statements as an aggregation dimension in [statement summary tables](/statement-summary-tables.md). When this variable is set to `OFF`, TiDB aggregates the same SQL digest executed by different users into the same row, and the `SAMPLE_USER` field displays one sampled user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate rows, and the `SAMPLE_USER` field of each row indicates the user who executed the statement. +- Modifying this variable clears the current in-memory statement summary data because data before and after the modification uses different aggregation dimensions. This does not affect historical data persisted to the disk. +- After you enable this variable, the number of statement summary records might increase with the number of different execution users for the same SQL digest, which increases memory usage. ### tidb_stmt_summary_history_size New in v4.0 @@ -6347,9 +6347,9 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: Boolean - Default value: `OFF` -- This variable controls whether to write statement summary records that are evicted by LRU to the statement summary log after [statements summary persistence](/statement-summary-tables.md#persist-statements-summary) is enabled. The written JSON records are marked with `"evicted": true` for downstream log consumers to identify. -- This variable takes effect only for the persistent implementation of statement summary. Records marked with `"evicted": true` are not returned as query results of `statements_summary_history` or `cluster_statements_summary_history`. -- After this variable is enabled, the amount of statement summary logs increases as LRU evictions become more frequent. Evicted records are written by using an asynchronous buffer mechanism. When the buffer queue is full, new evicted records might be dropped. +- This variable controls whether to write statement summary records evicted by LRU to the statement summary log after you enable [statements summary persistence](/statement-summary-tables.md#persist-statements-summary). TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. +- This variable takes effect only for the persistent implementation of statement summary. TiDB does not return records marked with `"evicted": true` as query results of `statements_summary_history` or `cluster_statements_summary_history`. +- After you enable this variable, the log volume increases as LRU evictions become more frequent. TiDB writes evicted records using an asynchronous buffer mechanism. When the buffer queue is full, TiDB might drop new evicted records. ### tidb_stmt_summary_refresh_interval New in v4.0 From 4acc52208343234fc85114449aed10db4031c095 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 21 Aug 2026 14:18:03 +0800 Subject: [PATCH 03/16] Apply suggestions from code review --- statement-summary-tables.md | 4 ++-- system-variables.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index ae0fe5ac39ef2..d66e82d1d311e 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,7 +87,7 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. -> - Starting from v8.5.7, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. +> - Starting from TiDB-X-CLOUD.202603.1 you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. ## `statements_summary_history` @@ -264,7 +264,7 @@ After statements summary persistence is enabled, the memory keeps only the curre > > - When statements summary persistence is enabled, the `tidb_stmt_summary_history_size` configuration described in the [Parameter configuration](#parameter-configuration) section will no longer take effect because the memory does not keep the history data. Instead, the following three configurations will be used to control the retention period and size of history data for persistence: [`tidb_stmt_summary_file_max_days`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_days-new-in-v660), [`tidb_stmt_summary_file_max_size`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_size-new-in-v660), and [`tidb_stmt_summary_file_max_backups`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_backups-new-in-v660). > - The smaller the value of `tidb_stmt_summary_refresh_interval`, the more immediate data is written to the disk. However, this also means more redundant data is written to the disk. -> - Starting from v8.5.7, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. +> - Starting from TiDB-X-CLOUD.202603.1, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. diff --git a/system-variables.md b/system-variables.md index cdf9d1674ff28..a71cfd310f68b 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6254,7 +6254,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). -### tidb_stmt_summary_group_by_user New in v8.5.7 +### tidb_stmt_summary_group_by_user TiDB-X-CLOUD.202603.1 - Scope: GLOBAL - Persists to cluster: Yes @@ -6340,7 +6340,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). -### tidb_stmt_summary_persist_evicted New in v8.5.7 +### tidb_stmt_summary_persist_evicted New in TiDB-X-CLOUD.202603.1 - Scope: GLOBAL - Persists to cluster: Yes From 879dd442211efdbbfe555a52a8ea74517ed3fb4a Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 31 Aug 2026 16:38:24 +0800 Subject: [PATCH 04/16] Apply suggestions from code review --- system-variables.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/system-variables.md b/system-variables.md index a71cfd310f68b..2333abc6d76c7 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6254,7 +6254,12 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). -### tidb_stmt_summary_group_by_user TiDB-X-CLOUD.202603.1 +### tidb_stmt_summary_group_by_user New in v9.0.0 and TiDB-X-CLOUD.202603 + +> **Note:** +> +> - For TiDB Cloud Starter, this variable is not supported. +> - For TiDB Cloud Essential and Premium, this variable is read-only. - Scope: GLOBAL - Persists to cluster: Yes @@ -6340,7 +6345,12 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). -### tidb_stmt_summary_persist_evicted New in TiDB-X-CLOUD.202603.1 +### tidb_stmt_summary_persist_evicted New in v9.0.0 and TiDB-X-CLOUD.202603 + +> **Note:** +> +> - For TiDB Cloud Starter, this variable is not supported. +> - For TiDB Cloud Essential and Premium, this variable is read-only. - Scope: GLOBAL - Persists to cluster: Yes From 29406e558d89a488a8e42f57b1bfdb7cea312e22 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 31 Aug 2026 16:41:06 +0800 Subject: [PATCH 05/16] Apply suggestions from code review --- statement-summary-tables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index d66e82d1d311e..0917e1078fde3 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,7 +87,7 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. -> - Starting from TiDB-X-CLOUD.202603.1 you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. +> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. ## `statements_summary_history` @@ -264,7 +264,7 @@ After statements summary persistence is enabled, the memory keeps only the curre > > - When statements summary persistence is enabled, the `tidb_stmt_summary_history_size` configuration described in the [Parameter configuration](#parameter-configuration) section will no longer take effect because the memory does not keep the history data. Instead, the following three configurations will be used to control the retention period and size of history data for persistence: [`tidb_stmt_summary_file_max_days`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_days-new-in-v660), [`tidb_stmt_summary_file_max_size`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_size-new-in-v660), and [`tidb_stmt_summary_file_max_backups`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_backups-new-in-v660). > - The smaller the value of `tidb_stmt_summary_refresh_interval`, the more immediate data is written to the disk. However, this also means more redundant data is written to the disk. -> - Starting from TiDB-X-CLOUD.202603.1, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. +> - For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. From 136291157f98f1496f3b615cbff1ca1aa14880a0 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 31 Aug 2026 16:50:40 +0800 Subject: [PATCH 06/16] Apply suggestions from code review --- statement-summary-tables.md | 4 ++-- system-variables.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index 0917e1078fde3..ceaad3e245d7f 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,7 +87,7 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. -> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. +> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). ## `statements_summary_history` @@ -264,7 +264,7 @@ After statements summary persistence is enabled, the memory keeps only the curre > > - When statements summary persistence is enabled, the `tidb_stmt_summary_history_size` configuration described in the [Parameter configuration](#parameter-configuration) section will no longer take effect because the memory does not keep the history data. Instead, the following three configurations will be used to control the retention period and size of history data for persistence: [`tidb_stmt_summary_file_max_days`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_days-new-in-v660), [`tidb_stmt_summary_file_max_size`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_size-new-in-v660), and [`tidb_stmt_summary_file_max_backups`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_backups-new-in-v660). > - The smaller the value of `tidb_stmt_summary_refresh_interval`, the more immediate data is written to the disk. However, this also means more redundant data is written to the disk. -> - For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. +> - For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). diff --git a/system-variables.md b/system-variables.md index 2333abc6d76c7..7fe9550e29002 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6259,7 +6259,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). > **Note:** > > - For TiDB Cloud Starter, this variable is not supported. -> - For TiDB Cloud Essential and Premium, this variable is read-only. +> - For TiDB Cloud Essential and Premium, this variable is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). - Scope: GLOBAL - Persists to cluster: Yes @@ -6350,7 +6350,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). > **Note:** > > - For TiDB Cloud Starter, this variable is not supported. -> - For TiDB Cloud Essential and Premium, this variable is read-only. +> - For TiDB Cloud Essential and Premium, this variable is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). - Scope: GLOBAL - Persists to cluster: Yes From 978f6db8320aa3f302b9d4bd11fd3932829a5d83 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 31 Aug 2026 16:51:49 +0800 Subject: [PATCH 07/16] Apply suggestions from code review --- statement-summary-tables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index ceaad3e245d7f..b91bbb9302c26 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,7 +87,7 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. -> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). +> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). ## `statements_summary_history` @@ -264,7 +264,7 @@ After statements summary persistence is enabled, the memory keeps only the curre > > - When statements summary persistence is enabled, the `tidb_stmt_summary_history_size` configuration described in the [Parameter configuration](#parameter-configuration) section will no longer take effect because the memory does not keep the history data. Instead, the following three configurations will be used to control the retention period and size of history data for persistence: [`tidb_stmt_summary_file_max_days`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_days-new-in-v660), [`tidb_stmt_summary_file_max_size`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_size-new-in-v660), and [`tidb_stmt_summary_file_max_backups`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_backups-new-in-v660). > - The smaller the value of `tidb_stmt_summary_refresh_interval`, the more immediate data is written to the disk. However, this also means more redundant data is written to the disk. -> - For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](/tidb-cloud/tidb-cloud-support.md). +> - For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). From c2abdc17409a05b0fbbb08b5f3fb428d4d2320e2 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 31 Aug 2026 16:52:59 +0800 Subject: [PATCH 08/16] Apply suggestions from code review --- statement-summary-tables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index b91bbb9302c26..168bdf5e58b47 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,7 +87,7 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. -> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). +> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). ## `statements_summary_history` @@ -264,7 +264,7 @@ After statements summary persistence is enabled, the memory keeps only the curre > > - When statements summary persistence is enabled, the `tidb_stmt_summary_history_size` configuration described in the [Parameter configuration](#parameter-configuration) section will no longer take effect because the memory does not keep the history data. Instead, the following three configurations will be used to control the retention period and size of history data for persistence: [`tidb_stmt_summary_file_max_days`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_days-new-in-v660), [`tidb_stmt_summary_file_max_size`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_size-new-in-v660), and [`tidb_stmt_summary_file_max_backups`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_backups-new-in-v660). > - The smaller the value of `tidb_stmt_summary_refresh_interval`, the more immediate data is written to the disk. However, this also means more redundant data is written to the disk. -> - For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). +> - For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). From f7dab6f996d4c08d46686e8457437e4662e81216 Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 31 Aug 2026 17:00:16 +0800 Subject: [PATCH 09/16] Update statement-summary-tables.md --- statement-summary-tables.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index 168bdf5e58b47..609a333c8e835 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -264,10 +264,13 @@ After statements summary persistence is enabled, the memory keeps only the curre > > - When statements summary persistence is enabled, the `tidb_stmt_summary_history_size` configuration described in the [Parameter configuration](#parameter-configuration) section will no longer take effect because the memory does not keep the history data. Instead, the following three configurations will be used to control the retention period and size of history data for persistence: [`tidb_stmt_summary_file_max_days`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_days-new-in-v660), [`tidb_stmt_summary_file_max_size`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_size-new-in-v660), and [`tidb_stmt_summary_file_max_backups`](/tidb-configuration-file.md#tidb_stmt_summary_file_max_backups-new-in-v660). > - The smaller the value of `tidb_stmt_summary_refresh_interval`, the more immediate data is written to the disk. However, this also means more redundant data is written to the disk. -> - For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). +> **Note:** +> +> For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). + ## Troubleshooting examples This section provides two examples to show how to use the statement summary feature to troubleshoot SQL performance issues. From 31b2b4308ae740a2cb2f08851524eb699d2f5f82 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 31 Aug 2026 17:52:46 +0800 Subject: [PATCH 10/16] Apply suggestions from code review --- statement-summary-tables.md | 4 ++-- system-variables.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index 609a333c8e835..40f8bba3595b5 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,7 +87,7 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. -> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). +> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. ## `statements_summary_history` @@ -269,7 +269,7 @@ After statements summary persistence is enabled, the memory keeps only the curre > **Note:** > -> For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). +> For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. ## Troubleshooting examples diff --git a/system-variables.md b/system-variables.md index 7fe9550e29002..2333abc6d76c7 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6259,7 +6259,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). > **Note:** > > - For TiDB Cloud Starter, this variable is not supported. -> - For TiDB Cloud Essential and Premium, this variable is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). +> - For TiDB Cloud Essential and Premium, this variable is read-only. - Scope: GLOBAL - Persists to cluster: Yes @@ -6350,7 +6350,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). > **Note:** > > - For TiDB Cloud Starter, this variable is not supported. -> - For TiDB Cloud Essential and Premium, this variable is read-only. If you need to modify it, contact [TiDB Cloud Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support/). +> - For TiDB Cloud Essential and Premium, this variable is read-only. - Scope: GLOBAL - Persists to cluster: Yes From ea2e8559e7772f31aa4e2966f6060b6ab43ccc8c Mon Sep 17 00:00:00 2001 From: ShuNing Date: Mon, 7 Sep 2026 20:54:38 -0700 Subject: [PATCH 11/16] Apply suggestion from @nolouch --- system-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index 2333abc6d76c7..69c85b46d5675 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6265,7 +6265,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: Boolean -- Default value: `OFF` +- Default value: `OFF` for TiDB Self-Managed and TiDB Cloud Dedicated/Starter, `ON` for TiDB Cloud Essentia and TiDB Cloud Premium - This variable controls whether to include the user who executes SQL statements as an aggregation dimension in [statement summary tables](/statement-summary-tables.md). When this variable is set to `OFF`, TiDB aggregates the same SQL digest executed by different users into the same row, and the `SAMPLE_USER` field displays one sampled user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate rows, and the `SAMPLE_USER` field of each row indicates the user who executed the statement. - Modifying this variable clears the current in-memory statement summary data because data before and after the modification uses different aggregation dimensions. This does not affect historical data persisted to the disk. - After you enable this variable, the number of statement summary records might increase with the number of different execution users for the same SQL digest, which increases memory usage. From 173cff6b523a214dcd4571b2d736a8e7260126cb Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 9 Sep 2026 10:29:34 +0800 Subject: [PATCH 12/16] Update statement-summary-tables.md --- statement-summary-tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index 40f8bba3595b5..9019c6b591e17 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,7 +87,7 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. -> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. +> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is `ON` by default, and it is read-only. ## `statements_summary_history` From 21d83eb838cd43ad0ea9974904c5ce6459fdf280 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 9 Sep 2026 10:35:04 +0800 Subject: [PATCH 13/16] Apply suggestions from code review --- system-variables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/system-variables.md b/system-variables.md index 69c85b46d5675..e90b177f0b124 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6254,7 +6254,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). -### tidb_stmt_summary_group_by_user New in v9.0.0 and TiDB-X-CLOUD.202603 +### tidb_stmt_summary_group_by_user New in v9.0.0 and CLOUD.202603.1 > **Note:** > @@ -6345,7 +6345,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). -### tidb_stmt_summary_persist_evicted New in v9.0.0 and TiDB-X-CLOUD.202603 +### tidb_stmt_summary_persist_evicted New in v9.0.0 and CLOUD.202603.1 > **Note:** > From 50cfd50bb1a2ba4c18c21f0f12f42d60ebf28c9b Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 9 Sep 2026 10:53:18 +0800 Subject: [PATCH 14/16] Apply suggestions from code review --- statement-summary-tables.md | 4 ++-- system-variables.md | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index 9019c6b591e17..123d46cfb124d 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -145,7 +145,7 @@ The following system variables are used to control the statement summary: - `tidb_stmt_summary_max_sql_length`: Specifies the longest display length of `DIGEST_TEXT` and `QUERY_SAMPLE_TEXT`. The default value is `4096`. - `tidb_stmt_summary_internal_query`: Determines whether to count the TiDB SQL statements. `1` means to count, and `0` means not to count. The default value is `0`. -- `tidb_stmt_summary_group_by_user`: Determines whether to aggregate statement summaries by execution user. `1` means to aggregate by user, and `0` means not to aggregate by user. The default value is `0`. After you enable this variable, TiDB aggregates the same SQL digest executed by different users into separate rows, which might increase the number of statement summary records and memory usage. Modifying this variable clears the current in-memory statement summary data. +- `tidb_stmt_summary_group_by_user`: Determines whether to aggregate statement summaries by execution user. `1` means to aggregate by user, and `0` means not to aggregate by user. The default value is `0` for TiDB Self-Managed and TiDB Cloud Dedicated, and `1` for TiDB Cloud Essential and Premium. After you enable this variable, TiDB aggregates the same SQL digest executed by different users into separate rows, which might increase the number of statement summary records and memory usage. Modifying this variable clears the current in-memory statement summary data. - `tidb_stmt_summary_persist_evicted`: Determines whether to write statement summary records evicted by LRU to the statement summary log after you enable [statements summary persistence](#persist-statements-summary). `1` means to write, and `0` means not to write. The default value is `0`. After you enable this variable, the log contains JSON records marked with `"evicted": true`, and the log volume increases as LRU evictions become more frequent. An example of the statement summary configuration is shown as follows: @@ -269,7 +269,7 @@ After statements summary persistence is enabled, the memory keeps only the curre > **Note:** > -> For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. TiDB does not return these records as query results of `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is read-only. +> For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` so that downstream log consumers can identify them. TiDB does not return these records as query results from `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_persist_evicted` is read-only. ## Troubleshooting examples diff --git a/system-variables.md b/system-variables.md index e90b177f0b124..40177132761b5 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6265,9 +6265,9 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: Boolean -- Default value: `OFF` for TiDB Self-Managed and TiDB Cloud Dedicated/Starter, `ON` for TiDB Cloud Essentia and TiDB Cloud Premium +- Default value: `OFF` for TiDB Self-Managed and TiDB Cloud Dedicated; `ON` for TiDB Cloud Essential and TiDB Cloud Premium - This variable controls whether to include the user who executes SQL statements as an aggregation dimension in [statement summary tables](/statement-summary-tables.md). When this variable is set to `OFF`, TiDB aggregates the same SQL digest executed by different users into the same row, and the `SAMPLE_USER` field displays one sampled user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate rows, and the `SAMPLE_USER` field of each row indicates the user who executed the statement. -- Modifying this variable clears the current in-memory statement summary data because data before and after the modification uses different aggregation dimensions. This does not affect historical data persisted to the disk. +- Modifying this variable clears the current in-memory statement summary data because data before and after the modification is aggregated using different dimensions. This does not affect historical data persisted to disk. - After you enable this variable, the number of statement summary records might increase with the number of different execution users for the same SQL digest, which increases memory usage. ### tidb_stmt_summary_history_size New in v4.0 @@ -6357,8 +6357,8 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: Boolean - Default value: `OFF` -- This variable controls whether to write statement summary records evicted by LRU to the statement summary log after you enable [statements summary persistence](/statement-summary-tables.md#persist-statements-summary). TiDB marks these JSON records with `"evicted": true` for downstream log consumers to identify. -- This variable takes effect only for the persistent implementation of statement summary. TiDB does not return records marked with `"evicted": true` as query results of `statements_summary_history` or `cluster_statements_summary_history`. +- This variable controls whether to write statement summary records evicted by LRU to the statement summary log after you enable [statements summary persistence](/statement-summary-tables.md#persist-statements-summary). TiDB marks these JSON records with `"evicted": true` so that downstream log consumers can identify them. +- This variable takes effect only when [tidb_stmt_summary_enable_persistent](/system-variables.md#tidb_stmt_summary_enable_persistent-new-in-v660) is enabled. TiDB does not return records marked with `"evicted": true` as query results from `statements_summary_history` or `cluster_statements_summary_history`. - After you enable this variable, the log volume increases as LRU evictions become more frequent. TiDB writes evicted records using an asynchronous buffer mechanism. When the buffer queue is full, TiDB might drop new evicted records. ### tidb_stmt_summary_refresh_interval New in v4.0 From 06a8e1ab282a6e0eaaca0cd5917a6a983b9433a5 Mon Sep 17 00:00:00 2001 From: qiancai Date: Thu, 10 Sep 2026 23:19:11 +0800 Subject: [PATCH 15/16] add fixed anchors to resolve broken links --- statement-summary-tables.md | 4 ++-- system-variable-reference.md | 4 ++-- system-variables.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index 123d46cfb124d..672b2dda1bdf7 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,7 +87,7 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. -> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is `ON` by default, and it is read-only. +> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is `ON` by default, and it is read-only. ## `statements_summary_history` @@ -269,7 +269,7 @@ After statements summary persistence is enabled, the memory keeps only the curre > **Note:** > -> For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` so that downstream log consumers can identify them. TiDB does not return these records as query results from `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_persist_evicted` is read-only. +> For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` so that downstream log consumers can identify them. TiDB does not return these records as query results from `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_persist_evicted` is read-only. ## Troubleshooting examples diff --git a/system-variable-reference.md b/system-variable-reference.md index c5b82544dca8e..14d22b7d3ce36 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -3961,7 +3961,7 @@ Referenced in: - [SHOW [GLOBAL|SESSION] VARIABLES](/sql-statements/sql-statement-show-variables.md) - [Statement Summary Tables](/statement-summary-tables.md) -- [System Variables](/system-variables.md#tidb_stmt_summary_group_by_user-new-in-v857) +- [System Variables](/system-variables.md#tidb_stmt_summary_group_by_user) ### tidb_stmt_summary_history_size @@ -4013,7 +4013,7 @@ Referenced in: - [SHOW [GLOBAL|SESSION] VARIABLES](/sql-statements/sql-statement-show-variables.md) - [Statement Summary Tables](/statement-summary-tables.md) -- [System Variables](/system-variables.md#tidb_stmt_summary_persist_evicted-new-in-v857) +- [System Variables](/system-variables.md#tidb_stmt_summary_persist_evicted) ### tidb_stmt_summary_refresh_interval diff --git a/system-variables.md b/system-variables.md index 40177132761b5..f85d32e104b4c 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6254,7 +6254,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). -### tidb_stmt_summary_group_by_user New in v9.0.0 and CLOUD.202603.1 +### tidb_stmt_summary_group_by_user New in v9.0.0 and CLOUD.202603.1 {#tidb_stmt_summary_group_by_user} > **Note:** > @@ -6345,7 +6345,7 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). -### tidb_stmt_summary_persist_evicted New in v9.0.0 and CLOUD.202603.1 +### tidb_stmt_summary_persist_evicted New in v9.0.0 and CLOUD.202603.1 {#tidb_stmt_summary_persist_evicted} > **Note:** > From ddd649d1f594fc629a19e4a758c02a20994ed03f Mon Sep 17 00:00:00 2001 From: qiancai Date: Wed, 16 Sep 2026 18:33:17 +0800 Subject: [PATCH 16/16] adapt the content for 2603 --- statement-summary-tables.md | 7 ------- system-variable-reference.md | 16 ---------------- system-variables.md | 14 +++++++++++--- 3 files changed, 11 insertions(+), 26 deletions(-) diff --git a/statement-summary-tables.md b/statement-summary-tables.md index 672b2dda1bdf7..6cf25a383449f 100644 --- a/statement-summary-tables.md +++ b/statement-summary-tables.md @@ -87,7 +87,6 @@ The following is a sample output of querying `statements_summary`: > > - In TiDB, the time unit of fields in statement summary tables is nanosecond (ns), whereas in MySQL the time unit is picosecond (ps). > - Starting from v7.5.1 and v7.6.0, for clusters with [resource control](/tidb-resource-control-ru-groups.md) enabled, `statements_summary` will be aggregated by resource group, for example, the same statements executed in different resource groups will be collected as different records. -> - For TiDB Self-Managed, starting from v9.0.0, you can use [`tidb_stmt_summary_group_by_user`](/system-variables.md#tidb_stmt_summary_group_by_user) to control whether to aggregate statement summaries by execution user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate records, and the `SAMPLE_USER` field of each record indicates the user who executed the statement. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_group_by_user` is `ON` by default, and it is read-only. ## `statements_summary_history` @@ -145,8 +144,6 @@ The following system variables are used to control the statement summary: - `tidb_stmt_summary_max_sql_length`: Specifies the longest display length of `DIGEST_TEXT` and `QUERY_SAMPLE_TEXT`. The default value is `4096`. - `tidb_stmt_summary_internal_query`: Determines whether to count the TiDB SQL statements. `1` means to count, and `0` means not to count. The default value is `0`. -- `tidb_stmt_summary_group_by_user`: Determines whether to aggregate statement summaries by execution user. `1` means to aggregate by user, and `0` means not to aggregate by user. The default value is `0` for TiDB Self-Managed and TiDB Cloud Dedicated, and `1` for TiDB Cloud Essential and Premium. After you enable this variable, TiDB aggregates the same SQL digest executed by different users into separate rows, which might increase the number of statement summary records and memory usage. Modifying this variable clears the current in-memory statement summary data. -- `tidb_stmt_summary_persist_evicted`: Determines whether to write statement summary records evicted by LRU to the statement summary log after you enable [statements summary persistence](#persist-statements-summary). `1` means to write, and `0` means not to write. The default value is `0`. After you enable this variable, the log contains JSON records marked with `"evicted": true`, and the log volume increases as LRU evictions become more frequent. An example of the statement summary configuration is shown as follows: @@ -267,10 +264,6 @@ After statements summary persistence is enabled, the memory keeps only the curre -> **Note:** -> -> For TiDB Self-Managed, starting from v9.0.0, you can enable [`tidb_stmt_summary_persist_evicted`](/system-variables.md#tidb_stmt_summary_persist_evicted) to write records evicted by LRU to the statement summary log. TiDB marks these JSON records with `"evicted": true` so that downstream log consumers can identify them. TiDB does not return these records as query results from `statements_summary_history` or `cluster_statements_summary_history`. For TiDB Cloud Essential and Premium, `tidb_stmt_summary_persist_evicted` is read-only. - ## Troubleshooting examples This section provides two examples to show how to use the statement summary feature to troubleshoot SQL performance issues. diff --git a/system-variable-reference.md b/system-variable-reference.md index 14d22b7d3ce36..5e33e28c63a9d 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -3955,14 +3955,6 @@ Referenced in: - [TiDB Configuration File](/tidb-configuration-file.md) - [TiDB 6.6.0 Release Notes](/releases/release-6.6.0.md) -### tidb_stmt_summary_group_by_user - -Referenced in: - -- [SHOW [GLOBAL|SESSION] VARIABLES](/sql-statements/sql-statement-show-variables.md) -- [Statement Summary Tables](/statement-summary-tables.md) -- [System Variables](/system-variables.md#tidb_stmt_summary_group_by_user) - ### tidb_stmt_summary_history_size Referenced in: @@ -4007,14 +3999,6 @@ Referenced in: - [TiDB 5.0.4 Release Notes](/releases/release-5.0.4.md) - [TiDB 4.0.14 Release Notes](/releases/release-4.0.14.md) -### tidb_stmt_summary_persist_evicted - -Referenced in: - -- [SHOW [GLOBAL|SESSION] VARIABLES](/sql-statements/sql-statement-show-variables.md) -- [Statement Summary Tables](/statement-summary-tables.md) -- [System Variables](/system-variables.md#tidb_stmt_summary_persist_evicted) - ### tidb_stmt_summary_refresh_interval Referenced in: diff --git a/system-variables.md b/system-variables.md index f85d32e104b4c..5c49ad0b6e5a4 100644 --- a/system-variables.md +++ b/system-variables.md @@ -6254,7 +6254,9 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). -### tidb_stmt_summary_group_by_user New in v9.0.0 and CLOUD.202603.1 {#tidb_stmt_summary_group_by_user} + + +### tidb_stmt_summary_group_by_user New in CLOUD.202603.1 {#tidb_stmt_summary_group_by_user} > **Note:** > @@ -6265,11 +6267,13 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). - Persists to cluster: Yes - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No - Type: Boolean -- Default value: `OFF` for TiDB Self-Managed and TiDB Cloud Dedicated; `ON` for TiDB Cloud Essential and TiDB Cloud Premium +- Default value: `ON` for TiDB Cloud Essential and TiDB Cloud Premium - This variable controls whether to include the user who executes SQL statements as an aggregation dimension in [statement summary tables](/statement-summary-tables.md). When this variable is set to `OFF`, TiDB aggregates the same SQL digest executed by different users into the same row, and the `SAMPLE_USER` field displays one sampled user. When this variable is set to `ON`, TiDB aggregates the same SQL digest executed by different users into separate rows, and the `SAMPLE_USER` field of each row indicates the user who executed the statement. - Modifying this variable clears the current in-memory statement summary data because data before and after the modification is aggregated using different dimensions. This does not affect historical data persisted to disk. - After you enable this variable, the number of statement summary records might increase with the number of different execution users for the same SQL digest, which increases memory usage. + + ### tidb_stmt_summary_history_size New in v4.0 > **Note:** @@ -6345,7 +6349,9 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). -### tidb_stmt_summary_persist_evicted New in v9.0.0 and CLOUD.202603.1 {#tidb_stmt_summary_persist_evicted} + + +### tidb_stmt_summary_persist_evicted New in CLOUD.202603.1 {#tidb_stmt_summary_persist_evicted} > **Note:** > @@ -6361,6 +6367,8 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md). - This variable takes effect only when [tidb_stmt_summary_enable_persistent](/system-variables.md#tidb_stmt_summary_enable_persistent-new-in-v660) is enabled. TiDB does not return records marked with `"evicted": true` as query results from `statements_summary_history` or `cluster_statements_summary_history`. - After you enable this variable, the log volume increases as LRU evictions become more frequent. TiDB writes evicted records using an asynchronous buffer mechanism. When the buffer queue is full, TiDB might drop new evicted records. + + ### tidb_stmt_summary_refresh_interval New in v4.0 > **Note:**