From 2258f3c8f8ba839346d9be3c1a592bff678558f4 Mon Sep 17 00:00:00 2001
From: houfaxin <hfxsd@hotmail.com>
Date: Thu, 27 Mar 2025 10:30:35 +0800
Subject: [PATCH 01/12] initial trans

---
 TOC.md              |   1 +
 system-variables.md |  45 ++++++++++++++++++
 workloadrepo.md     | 113 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 159 insertions(+)
 create mode 100644 workloadrepo.md

diff --git a/TOC.md b/TOC.md
index 85716c7f31f3..571724c97e78 100644
--- a/TOC.md
+++ b/TOC.md
@@ -1069,6 +1069,7 @@
   - [错误码](/error-codes.md)
   - [通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md)
   - [外部存储服务的 URI 格式](/external-storage-uri.md)
+  - [TiDB 工作负载存储库 (Workload Repository)](/workloadrepo.md)
 - 常见问题解答 (FAQ)
   - [FAQ 汇总](/faq/faq-overview.md)
   - [产品 FAQ](/faq/tidb-faq.md)
diff --git a/system-variables.md b/system-variables.md
index 23c99388b914..4f3c0dfe2801 100644
--- a/system-variables.md
+++ b/system-variables.md
@@ -5339,6 +5339,51 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
 - 这个变量用于设置 window 算子的并行度。
 - 默认值 `-1` 表示使用 `tidb_executor_concurrency` 的值。
 
+### `tidb_workload_repository_dest` <span class="version-mark">从 v9.0.0 版本开始引入</span>
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
+- 类型：字符串
+- 默认值：`''`
+- 该变量用于设置 [Workload Repository](/workloadrepo.md) 的目标位置。
+- 可选值为 `'table'`（启用 Workload Repository）或 `''`（禁用 Workload Repository）。
+
+### `tidb_workload_repository_active_sampling_interval` <span class="version-mark">从 v9.0.0 版本开始引入</span>
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
+- 类型：整数型
+- 默认值：`5`
+- 范围：`[0, 600]`
+- 单位：秒
+- 用于设置 [Workload Repository](/workloadrepo.md) 的基于时间的采样过程的采样间隔。
+- 将该值设置为 `0` 会禁用基于时间的采样过程。
+
+### `tidb_workload_repository_retention_days` <span class="version-mark">从 v9.0.0 版本开始引入</span>
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
+- 类型：整数型
+- 默认值：`7`
+- 范围：`[0, 365]`
+- 单位：天
+- 用于设置 [Workload Repository](/workloadrepo.md) 数据的保留天数。
+- 将该值设置为 `0` 会禁用旧数据的自动清理。
+
+### `tidb_workload_repository_snapshot_interval` <span class="version-mark">从 v9.0.0 版本开始引入</span>
+
+- 作用域：GLOBAL
+- 是否持久化到集群：是
+- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
+- 类型：整数型
+- 默认值：`3600`
+- 范围：`[900, 7200]`
+- 单位：秒
+- 用于设置 [TiDB Workload Repository](/workloadrepo.md) 的快照采样过程的采样间隔。
+
 ### `tiflash_fastscan` <span class="version-mark">从 v6.3.0 版本开始引入</span>
 
 - 作用域：SESSION | GLOBAL
diff --git a/workloadrepo.md b/workloadrepo.md
new file mode 100644
index 000000000000..e0f5b4b00967
--- /dev/null
+++ b/workloadrepo.md
@@ -0,0 +1,113 @@
+---
+title: TiDB 工作负载存储库 (Workload Repository)
+summary: 介绍用于收集和存储 TiDB 集群历史工作负载数据的工作负载存储库系统。
+---
+
+# TiDB 工作负载存储库 (Workload Repository)
+
+工作负载存储库是一个用于收集和存储 TiDB 集群历史工作负载数据的系统。它会定期采样各种系统表，以跟踪集群的性能和使用模式。
+
+## 启用工作负载存储库
+
+要启用工作负载存储库，可以设置 [`tidb_workload_repository_dest`](/system-variables.md#tidb_workload_repository_dest-从-v900-版本开始引入) 系统变量：
+
+```sql
+SET GLOBAL tidb_workload_repository_dest = 'table';
+```
+
+要禁用它，执行以下语句：
+
+```sql
+SET GLOBAL tidb_workload_repository_dest = '';
+```
+
+## 数据收集
+
+工作负载存储库将数据存储在 `WORKLOAD_SCHEMA` 数据库下的表中。它通过两种不同的方法收集数据：
+
+- 快照采样过程，按可配置的时间间隔运行，通常为每小时一次，也可以手动触发。
+- 基于时间的采样过程，按较短的时间间隔运行，通常为每 5 秒一次。
+
+## 快照采样过程（默认每小时）
+
+快照采样过程每 15 分钟到 2 小时运行一次，从各种监控表中采样数据。快照由指定时间间隔内的某个 TiDB 节点发起，过程如下：
+
+1. 从发起节点向 `HIST_SNAPSHOTS` 表插入一行，记录快照 ID、开始和结束时间戳以及服务器版本信息。
+2. 在每个 TiDB 节点上，将源表中的所有行复制到带有 `HIST_` 前缀的对应历史表中。复制的数据包括源表中的原始列以及用于时间戳、实例 ID 和快照 ID 的附加列。
+
+注意，采样表返回的数据内容与查询这些数据的 TiDB 节点相关。
+
+从以下表中采样数据：
+
+| 表名 | 目标表 | 描述 |
+| --- | --- | --- |
+| `TIDB_INDEX_USAGE` | `HIST_TIDB_INDEX_USAGE` | 索引使用统计信息 |
+| `TIDB_STATEMENTS_STATS` | `HIST_TIDB_STATEMENTS_STATS` | 语句统计信息 |
+| `CLIENT_ERRORS_SUMMARY_BY_HOST` | `HIST_CLIENT_ERRORS_SUMMARY_BY_HOST` | 按主机的客户端错误摘要 |
+| `CLIENT_ERRORS_SUMMARY_BY_USER` | `HIST_CLIENT_ERRORS_SUMMARY_BY_USER` | 按用户的客户端错误摘要 |
+| `CLIENT_ERRORS_SUMMARY_GLOBAL` | `HIST_CLIENT_ERRORS_SUMMARY_GLOBAL` | 全局客户端错误摘要 |
+
+可以通过 [`tidb_workload_repository_snapshot_interval`](/system-variables.md#tidb_workload_repository_snapshot_interval-从-v900-版本开始引入) 控制快照采样间隔：
+
+```sql
+SET GLOBAL tidb_workload_repository_snapshot_interval = 900; -- 将间隔设置为 15 分钟
+```
+
+## 手动快照
+
+请注意，虽然快照采样过程会根据配置的时间间隔自动运行，但你也可以使用以下 SQL 语句触发手动快照：
+
+```sql
+ADMIN WORKLOAD REPOSITORY TAKE SNAPSHOT;
+```
+
+## 基于时间的采样过程（默认每 5 秒）
+
+基于时间的采样过程每 1 秒到 600 秒运行一次，从各种监控表中采样数据。
+
+当基于时间的采样过程运行时，源表中的所有行都会被复制到带有 `HIST_` 前缀的对应历史表中。复制的数据包括源表中的原始列以及用于时间戳和实例 ID 的附加列。
+
+与快照采样过程不同，不会向 `HIST_SNAPSHOTS` 表添加行。
+
+注意，采样表返回的数据内容与查询这些数据的 TiDB 节点相关。
+
+从以下表中采样数据：
+
+| 表名 | 目标表 | 描述 |
+| --- | --- | --- |
+| `PROCESSLIST` | `HIST_PROCESSLIST` | 活跃会话 |
+| `DATA_LOCK_WAITS` | `HIST_DATA_LOCK_WAITS` | 数据锁等待 |
+| `TIDB_TRX` | `HIST_TIDB_TRX` | 活跃事务 |
+| `MEMORY_USAGE` | `HIST_MEMORY_USAGE` | 内存使用情况 |
+| `DEADLOCKS` | `HIST_DEADLOCKS` | 死锁信息 |
+
+可以通过 [`tidb_workload_repository_active_sampling_interval`](/system-variables.md#tidb_workload_repository_active_sampling_interval-从-v900-版本开始引入) 控制基于时间的采样间隔：
+
+```sql
+SET GLOBAL tidb_workload_repository_active_sampling_interval = 20; -- 将间隔设置为 20 秒
+```
+
+## 数据保留
+
+系统会根据保留期设置自动清除数据，并使用分区进行高效的数据管理。
+
+[`tidb_workload_repository_retention_days`](/system-variables.md#tidb_workload_repository_retention_days-从-v900-版本开始引入) 变量控制工作负载存储库中历史数据的保留期。例如，要保留 30 天的数据，运行以下命令：
+
+```sql
+SET GLOBAL tidb_workload_repository_retention_days = 30;
+```
+
+此变量的较高值允许更长的数据保留时间，这可能有助于工作负载分析，但会增加存储需求。
+
+## 注意事项
+
+- 启用工作负载存储库可能会对系统性能产生轻微影响。
+- 采样间隔设置得过低可能会增加系统开销。
+- 将保留天数设置为 `0` 会禁用旧数据的自动清除。
+
+## 最佳实践
+
+- 从默认设置开始，根据你的监控需求进行调整。
+- 根据存储容量设置合理的保留期。
+- 监控 `WORKLOAD_SCHEMA` 数据库的大小。
+- 在生产环境中使用较长的采样间隔以最小化开销。

From bb7427b7c2bf2e477a5160bd9efffbf88215dbc6 Mon Sep 17 00:00:00 2001
From: houfaxin <hfxsd@hotmail.com>
Date: Thu, 27 Mar 2025 10:46:43 +0800
Subject: [PATCH 02/12] Update system-variable-reference.md

---
 system-variable-reference.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/system-variable-reference.md b/system-variable-reference.md
index c9c586dbb612..37971fde9f7a 100644
--- a/system-variable-reference.md
+++ b/system-variable-reference.md
@@ -3898,6 +3898,26 @@ summary: 查看 TiDB 所有的系统变量，以及引用这些变量的文档
 - [SHOW [GLOBAL|SESSION] VARIABLES](/sql-statements/sql-statement-show-variables.md)
 - [系统变量](/system-variables.md#tidb_window_concurrency-从-v40-版本开始引入)
 
+### tidb_workload_repository_dest
+
+- [TiDB Workload Repository](/workloadrepo.md#启用工作负载存储库)
+- [系统变量](/system-variables.md#tidb_workload_repository_dest-从-v900-版本开始引入)
+
+### tidb_workload_repository_active_sampling_interval
+
+- [TiDB Workload Repository](/workloadrepo.md#基于时间的采样过程默认每-5-秒)
+- [系统变量](/system-variables.md#tidb_workload_repository_active_sampling_interval-从-v900-版本开始引入)
+
+### tidb_workload_repository_retention_days
+
+- [TiDB Workload Repository](/workloadrepo.md#数据保留)
+- [系统变量](/system-variables.md#tidb_workload_repository_retention_days-从-v900-版本开始引入)
+
+### tidb_workload_repository_snapshot_interval
+
+- [TiDB Workload Repository](/workloadrepo.md#快照采样过程默认每小时)
+- [系统变量](/system-variables.md#tidb_workload_repository_snapshot_interval-从-v900-版本开始引入)
+
 ### tiflash_fastscan
 
 引用该变量的文档：

From 134a2a91160c61a221022d7d093ecda41508e5a4 Mon Sep 17 00:00:00 2001
From: houfaxin <hfxsd@hotmail.com>
Date: Thu, 27 Mar 2025 10:50:46 +0800
Subject: [PATCH 03/12] Update workloadrepo.md

---
 workloadrepo.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/workloadrepo.md b/workloadrepo.md
index e0f5b4b00967..5a45f2df0387 100644
--- a/workloadrepo.md
+++ b/workloadrepo.md
@@ -1,15 +1,15 @@
 ---
-title: TiDB 工作负载存储库 (Workload Repository)
-summary: 介绍用于收集和存储 TiDB 集群历史工作负载数据的工作负载存储库系统。
+title: TiDB Workload Repository
+summary: 介绍用于收集和存储 TiDB 集群历史工作负载数据的 Workload Repository 系统。
 ---
 
-# TiDB 工作负载存储库 (Workload Repository)
+# TiDB Workload Repository
 
-工作负载存储库是一个用于收集和存储 TiDB 集群历史工作负载数据的系统。它会定期采样各种系统表，以跟踪集群的性能和使用模式。
+Workload Repository 是一个用于收集和存储 TiDB 集群历史工作负载数据的系统。它会定期采样各种系统表，以跟踪集群的性能和使用模式。
 
-## 启用工作负载存储库
+## 启用 Workload Repository 
 
-要启用工作负载存储库，可以设置 [`tidb_workload_repository_dest`](/system-variables.md#tidb_workload_repository_dest-从-v900-版本开始引入) 系统变量：
+要启用 Workload Repository，可以设置 [`tidb_workload_repository_dest`](/system-variables.md#tidb_workload_repository_dest-从-v900-版本开始引入) 系统变量：
 
 ```sql
 SET GLOBAL tidb_workload_repository_dest = 'table';
@@ -23,7 +23,7 @@ SET GLOBAL tidb_workload_repository_dest = '';
 
 ## 数据收集
 
-工作负载存储库将数据存储在 `WORKLOAD_SCHEMA` 数据库下的表中。它通过两种不同的方法收集数据：
+Workload Repository 将数据存储在 `WORKLOAD_SCHEMA` 数据库下的表中。它通过两种不同的方法收集数据：
 
 - 快照采样过程，按可配置的时间间隔运行，通常为每小时一次，也可以手动触发。
 - 基于时间的采样过程，按较短的时间间隔运行，通常为每 5 秒一次。
@@ -91,7 +91,7 @@ SET GLOBAL tidb_workload_repository_active_sampling_interval = 20; -- 将间隔
 
 系统会根据保留期设置自动清除数据，并使用分区进行高效的数据管理。
 
-[`tidb_workload_repository_retention_days`](/system-variables.md#tidb_workload_repository_retention_days-从-v900-版本开始引入) 变量控制工作负载存储库中历史数据的保留期。例如，要保留 30 天的数据，运行以下命令：
+[`tidb_workload_repository_retention_days`](/system-variables.md#tidb_workload_repository_retention_days-从-v900-版本开始引入) 变量控制 Workload Repository 中历史数据的保留期。例如，要保留 30 天的数据，运行以下命令：
 
 ```sql
 SET GLOBAL tidb_workload_repository_retention_days = 30;
@@ -101,7 +101,7 @@ SET GLOBAL tidb_workload_repository_retention_days = 30;
 
 ## 注意事项
 
-- 启用工作负载存储库可能会对系统性能产生轻微影响。
+- 启用 Workload Repository 可能会对系统性能产生轻微影响。
 - 采样间隔设置得过低可能会增加系统开销。
 - 将保留天数设置为 `0` 会禁用旧数据的自动清除。
 

From a34924e556db7d356eab1499ba76f6386d735545 Mon Sep 17 00:00:00 2001
From: houfaxin <hfxsd@hotmail.com>
Date: Thu, 27 Mar 2025 10:51:40 +0800
Subject: [PATCH 04/12] Update TOC.md

---
 TOC.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/TOC.md b/TOC.md
index 571724c97e78..15dbdb2ad8aa 100644
--- a/TOC.md
+++ b/TOC.md
@@ -1069,7 +1069,7 @@
   - [错误码](/error-codes.md)
   - [通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md)
   - [外部存储服务的 URI 格式](/external-storage-uri.md)
-  - [TiDB 工作负载存储库 (Workload Repository)](/workloadrepo.md)
+  - [TiDB Workload Repository](/workloadrepo.md)
 - 常见问题解答 (FAQ)
   - [FAQ 汇总](/faq/faq-overview.md)
   - [产品 FAQ](/faq/tidb-faq.md)

From e3a084cfbe01c0153df3dc29507c3a97b8b39f03 Mon Sep 17 00:00:00 2001
From: houfaxin <hfxsd@hotmail.com>
Date: Thu, 27 Mar 2025 11:09:25 +0800
Subject: [PATCH 05/12] Update system-variable-reference.md

---
 system-variable-reference.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/system-variable-reference.md b/system-variable-reference.md
index 37971fde9f7a..821e4d9916b9 100644
--- a/system-variable-reference.md
+++ b/system-variable-reference.md
@@ -3900,7 +3900,7 @@ summary: 查看 TiDB 所有的系统变量，以及引用这些变量的文档
 
 ### tidb_workload_repository_dest
 
-- [TiDB Workload Repository](/workloadrepo.md#启用工作负载存储库)
+- [TiDB Workload Repository](/workloadrepo.md#启用-workload-repository)
 - [系统变量](/system-variables.md#tidb_workload_repository_dest-从-v900-版本开始引入)
 
 ### tidb_workload_repository_active_sampling_interval

From c278b8944dead215aa4a6d7ad2172f34a75a221c Mon Sep 17 00:00:00 2001
From: xixirangrang <hfxsd@hotmail.com>
Date: Wed, 9 Apr 2025 20:25:35 +0800
Subject: [PATCH 06/12] Apply suggestions from code review

Co-authored-by: Roger Song <roger.song@pingcap.com>
---
 workloadrepo.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/workloadrepo.md b/workloadrepo.md
index 5a45f2df0387..550ce132659d 100644
--- a/workloadrepo.md
+++ b/workloadrepo.md
@@ -30,7 +30,7 @@ Workload Repository 将数据存储在 `WORKLOAD_SCHEMA` 数据库下的表中
 
 ## 快照采样过程（默认每小时）
 
-快照采样过程每 15 分钟到 2 小时运行一次，从各种监控表中采样数据。快照由指定时间间隔内的某个 TiDB 节点发起，过程如下：
+快照采样过程每 15 分钟到 2 小时运行一次，从存储累计指标的内存表中采样数据。快照由指定时间间隔内的某个 TiDB 节点发起，过程如下：
 
 1. 从发起节点向 `HIST_SNAPSHOTS` 表插入一行，记录快照 ID、开始和结束时间戳以及服务器版本信息。
 2. 在每个 TiDB 节点上，将源表中的所有行复制到带有 `HIST_` 前缀的对应历史表中。复制的数据包括源表中的原始列以及用于时间戳、实例 ID 和快照 ID 的附加列。
@@ -60,10 +60,11 @@ SET GLOBAL tidb_workload_repository_snapshot_interval = 900; -- 将间隔设置
 ```sql
 ADMIN WORKLOAD REPOSITORY TAKE SNAPSHOT;
 ```
+手动快照并不会改变下一次自动快照的发生时间。
 
 ## 基于时间的采样过程（默认每 5 秒）
 
-基于时间的采样过程每 1 秒到 600 秒运行一次，从各种监控表中采样数据。
+基于时间的采样间隔可设置为 1 秒到 600 秒之间的任意时间，从各个记录瞬时状态的系统表中采样数据。
 
 当基于时间的采样过程运行时，源表中的所有行都会被复制到带有 `HIST_` 前缀的对应历史表中。复制的数据包括源表中的原始列以及用于时间戳和实例 ID 的附加列。
 
@@ -86,6 +87,7 @@ ADMIN WORKLOAD REPOSITORY TAKE SNAPSHOT;
 ```sql
 SET GLOBAL tidb_workload_repository_active_sampling_interval = 20; -- 将间隔设置为 20 秒
 ```
+把间隔设置为 `0` 将会禁用基于时间的采样。
 
 ## 数据保留
 

From e4709d17b688a5b15bbd770094561897bb36f9c0 Mon Sep 17 00:00:00 2001
From: xixirangrang <hfxsd@hotmail.com>
Date: Wed, 9 Apr 2025 22:00:55 +0800
Subject: [PATCH 07/12] Apply suggestions from code review

---
 workloadrepo.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/workloadrepo.md b/workloadrepo.md
index 550ce132659d..fbf57fd70e6a 100644
--- a/workloadrepo.md
+++ b/workloadrepo.md
@@ -60,6 +60,7 @@ SET GLOBAL tidb_workload_repository_snapshot_interval = 900; -- 将间隔设置
 ```sql
 ADMIN WORKLOAD REPOSITORY TAKE SNAPSHOT;
 ```
+
 手动快照并不会改变下一次自动快照的发生时间。
 
 ## 基于时间的采样过程（默认每 5 秒）
@@ -87,6 +88,7 @@ ADMIN WORKLOAD REPOSITORY TAKE SNAPSHOT;
 ```sql
 SET GLOBAL tidb_workload_repository_active_sampling_interval = 20; -- 将间隔设置为 20 秒
 ```
+
 把间隔设置为 `0` 将会禁用基于时间的采样。
 
 ## 数据保留

From 4760bb5094ae9b5b2be2eeae08ba33f781f0b449 Mon Sep 17 00:00:00 2001
From: xixirangrang <hfxsd@hotmail.com>
Date: Thu, 10 Apr 2025 10:26:46 +0800
Subject: [PATCH 08/12] Update workloadrepo.md

---
 workloadrepo.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/workloadrepo.md b/workloadrepo.md
index fbf57fd70e6a..b77611b49ad1 100644
--- a/workloadrepo.md
+++ b/workloadrepo.md
@@ -30,7 +30,7 @@ Workload Repository 将数据存储在 `WORKLOAD_SCHEMA` 数据库下的表中
 
 ## 快照采样过程（默认每小时）
 
-快照采样过程每 15 分钟到 2 小时运行一次，从存储累计指标的内存表中采样数据。快照由指定时间间隔内的某个 TiDB 节点发起，过程如下：
+快照采样过程每 15 分钟到 2 小时运行一次（默认每小时），从存储累计指标的内存表中采样数据。快照由指定时间间隔内的某个 TiDB 节点发起，过程如下：
 
 1. 从发起节点向 `HIST_SNAPSHOTS` 表插入一行，记录快照 ID、开始和结束时间戳以及服务器版本信息。
 2. 在每个 TiDB 节点上，将源表中的所有行复制到带有 `HIST_` 前缀的对应历史表中。复制的数据包括源表中的原始列以及用于时间戳、实例 ID 和快照 ID 的附加列。

From 3a8c46188320afb3a3c20400f09a86e7bdca6b7e Mon Sep 17 00:00:00 2001
From: xixirangrang <hfxsd@hotmail.com>
Date: Wed, 16 Apr 2025 16:59:22 +0800
Subject: [PATCH 09/12] Apply suggestions from code review

Co-authored-by: Grace Cai <qqzczy@126.com>
---
 workloadrepo.md | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/workloadrepo.md b/workloadrepo.md
index b77611b49ad1..ebc77fe77ada 100644
--- a/workloadrepo.md
+++ b/workloadrepo.md
@@ -25,27 +25,27 @@ SET GLOBAL tidb_workload_repository_dest = '';
 
 Workload Repository 将数据存储在 `WORKLOAD_SCHEMA` 数据库下的表中。它通过两种不同的方法收集数据：
 
-- 快照采样过程，按可配置的时间间隔运行，通常为每小时一次，也可以手动触发。
+- 快照采样过程，按可配置的时间间隔运行，默认为每小时一次，也可以手动触发。
 - 基于时间的采样过程，按较短的时间间隔运行，通常为每 5 秒一次。
 
 ## 快照采样过程（默认每小时）
 
 快照采样过程每 15 分钟到 2 小时运行一次（默认每小时），从存储累计指标的内存表中采样数据。快照由指定时间间隔内的某个 TiDB 节点发起，过程如下：
 
-1. 从发起节点向 `HIST_SNAPSHOTS` 表插入一行，记录快照 ID、开始和结束时间戳以及服务器版本信息。
-2. 在每个 TiDB 节点上，将源表中的所有行复制到带有 `HIST_` 前缀的对应历史表中。复制的数据包括源表中的原始列以及用于时间戳、实例 ID 和快照 ID 的附加列。
+1. 从发起节点向 `WORKLOAD_SCHEMA.HIST_SNAPSHOTS` 表插入一行，记录快照 ID、开始和结束时间戳以及服务器版本信息。
+2. 在每个 TiDB 节点上，将源表中的所有行复制到带有 `HIST_` 前缀的对应目标表中。复制的数据包括源表中的原始列以及用于记录时间戳、实例 ID 和快照 ID 的附加列。
 
 注意，采样表返回的数据内容与查询这些数据的 TiDB 节点相关。
 
 从以下表中采样数据：
 
-| 表名 | 目标表 | 描述 |
+| 源表 | 目标表 | 描述 |
 | --- | --- | --- |
-| `TIDB_INDEX_USAGE` | `HIST_TIDB_INDEX_USAGE` | 索引使用统计信息 |
-| `TIDB_STATEMENTS_STATS` | `HIST_TIDB_STATEMENTS_STATS` | 语句统计信息 |
-| `CLIENT_ERRORS_SUMMARY_BY_HOST` | `HIST_CLIENT_ERRORS_SUMMARY_BY_HOST` | 按主机的客户端错误摘要 |
-| `CLIENT_ERRORS_SUMMARY_BY_USER` | `HIST_CLIENT_ERRORS_SUMMARY_BY_USER` | 按用户的客户端错误摘要 |
-| `CLIENT_ERRORS_SUMMARY_GLOBAL` | `HIST_CLIENT_ERRORS_SUMMARY_GLOBAL` | 全局客户端错误摘要 |
+| [`TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md) | `HIST_TIDB_INDEX_USAGE` | 索引使用统计信息 |
+| [`TIDB_STATEMENTS_STATS`](/statement-summary-tables.md) | `HIST_TIDB_STATEMENTS_STATS` | 语句统计信息 |
+| [`CLIENT_ERRORS_SUMMARY_BY_HOST`](/information-schema/client-errors-summary-by-host.md) | `HIST_CLIENT_ERRORS_SUMMARY_BY_HOST` | 基于主机客户端的错误摘要 |
+| [`CLIENT_ERRORS_SUMMARY_BY_USER`](/information-schema/client-errors-summary-by-user.md) | `HIST_CLIENT_ERRORS_SUMMARY_BY_USER` | 基于用户客户端的错误摘要 |
+| [`CLIENT_ERRORS_SUMMARY_GLOBAL`](/information-schema/client-errors-summary-global.md) | `HIST_CLIENT_ERRORS_SUMMARY_GLOBAL` | 基于全局客户端的错误摘要 |
 
 可以通过 [`tidb_workload_repository_snapshot_interval`](/system-variables.md#tidb_workload_repository_snapshot_interval-从-v900-版本开始引入) 控制快照采样间隔：
 
@@ -67,7 +67,7 @@ ADMIN WORKLOAD REPOSITORY TAKE SNAPSHOT;
 
 基于时间的采样间隔可设置为 1 秒到 600 秒之间的任意时间，从各个记录瞬时状态的系统表中采样数据。
 
-当基于时间的采样过程运行时，源表中的所有行都会被复制到带有 `HIST_` 前缀的对应历史表中。复制的数据包括源表中的原始列以及用于时间戳和实例 ID 的附加列。
+当基于时间的采样过程运行时，源表中的所有行都会被复制到带有 `HIST_` 前缀的对应目标表中。复制的数据包括源表中的原始列以及用于记录时间戳和实例 ID 的附加列。
 
 与快照采样过程不同，不会向 `HIST_SNAPSHOTS` 表添加行。
 
@@ -75,13 +75,13 @@ ADMIN WORKLOAD REPOSITORY TAKE SNAPSHOT;
 
 从以下表中采样数据：
 
-| 表名 | 目标表 | 描述 |
+| 源表 | 目标表 | 描述 |
 | --- | --- | --- |
-| `PROCESSLIST` | `HIST_PROCESSLIST` | 活跃会话 |
-| `DATA_LOCK_WAITS` | `HIST_DATA_LOCK_WAITS` | 数据锁等待 |
-| `TIDB_TRX` | `HIST_TIDB_TRX` | 活跃事务 |
-| `MEMORY_USAGE` | `HIST_MEMORY_USAGE` | 内存使用情况 |
-| `DEADLOCKS` | `HIST_DEADLOCKS` | 死锁信息 |
+| [`PROCESSLIST`](/information-schema/information-schema-processlist.md) | `HIST_PROCESSLIST` | 活跃会话 |
+| [`DATA_LOCK_WAITS`](/information-schema/information-schema-data-lock-waits.md) | `HIST_DATA_LOCK_WAITS` | 数据锁等待 |
+| [`TIDB_TRX`](/information-schema/information-schema-tidb-trx.md) | `HIST_TIDB_TRX` | 活跃事务 |
+| [`MEMORY_USAGE`](/information-schema/information-schema-memory-usage.md) | `HIST_MEMORY_USAGE` | 内存使用情况 |
+| [`DEADLOCKS`](/information-schema/information-schema-deadlocks.md) | `HIST_DEADLOCKS` | 死锁信息 |
 
 可以通过 [`tidb_workload_repository_active_sampling_interval`](/system-variables.md#tidb_workload_repository_active_sampling_interval-从-v900-版本开始引入) 控制基于时间的采样间隔：
 
@@ -93,20 +93,20 @@ SET GLOBAL tidb_workload_repository_active_sampling_interval = 20; -- 将间隔
 
 ## 数据保留
 
-系统会根据保留期设置自动清除数据，并使用分区进行高效的数据管理。
+Workload Repository 中历史数据默认保留 7 天。系统会根据保留期设置自动清除数据，并使用分区进行高效的数据管理。
 
-[`tidb_workload_repository_retention_days`](/system-variables.md#tidb_workload_repository_retention_days-从-v900-版本开始引入) 变量控制 Workload Repository 中历史数据的保留期。例如，要保留 30 天的数据，运行以下命令：
+可以通过 [`tidb_workload_repository_retention_days`](/system-variables.md#tidb_workload_repository_retention_days-从-v900-版本开始引入) 变量控制 Workload Repository 中历史数据的保留期。例如，要保留 30 天的数据，运行以下语句：
 
 ```sql
 SET GLOBAL tidb_workload_repository_retention_days = 30;
 ```
 
-此变量的较高值允许更长的数据保留时间，这可能有助于工作负载分析，但会增加存储需求。
+此变量的值越高，数据保留时间越长，这可能有助于工作负载分析，但会增加存储需求。
 
 ## 注意事项
 
 - 启用 Workload Repository 可能会对系统性能产生轻微影响。
-- 采样间隔设置得过低可能会增加系统开销。
+- 采样间隔设置得过短可能会增加系统开销。
 - 将保留天数设置为 `0` 会禁用旧数据的自动清除。
 
 ## 最佳实践

From a5c658a3ec95928208025a3155c2705d6a052871 Mon Sep 17 00:00:00 2001
From: houfaxin <hfxsd@hotmail.com>
Date: Thu, 17 Apr 2025 09:55:21 +0800
Subject: [PATCH 10/12] sync en commit

---
 TOC.md                                    |  2 +-
 sql-statements/sql-statement-admin.md     | 13 ++++++++++++-
 system-variable-reference.md              |  8 ++++----
 system-variables.md                       |  8 ++++----
 workloadrepo.md => workload-repository.md |  6 +++---
 5 files changed, 24 insertions(+), 13 deletions(-)
 rename workloadrepo.md => workload-repository.md (92%)

diff --git a/TOC.md b/TOC.md
index 15dbdb2ad8aa..cd312fcad012 100644
--- a/TOC.md
+++ b/TOC.md
@@ -1069,7 +1069,7 @@
   - [错误码](/error-codes.md)
   - [通过拓扑 label 进行副本调度](/schedule-replicas-by-topology-labels.md)
   - [外部存储服务的 URI 格式](/external-storage-uri.md)
-  - [TiDB Workload Repository](/workloadrepo.md)
+  - [TiDB Workload Repository](/workload-repository.md)
 - 常见问题解答 (FAQ)
   - [FAQ 汇总](/faq/faq-overview.md)
   - [产品 FAQ](/faq/tidb-faq.md)
diff --git a/sql-statements/sql-statement-admin.md b/sql-statements/sql-statement-admin.md
index baf75922a58b..0d6b0e72d9d3 100644
--- a/sql-statements/sql-statement-admin.md
+++ b/sql-statements/sql-statement-admin.md
@@ -14,6 +14,7 @@ summary: TiDB的 `ADMIN` 语句是用于查看TiDB状态和对表数据进行校
 - [`ADMIN REPAIR TABLE`](#admin-repair-table-语句)
 - [`ADMIN SHOW NEXT_ROW_ID`](#admin-show-next_row_id-语句)
 - [`ADMIN SHOW SLOW`](#admin-show-slow-语句)
+- [`ADMIN CREATE WORKLOAD SNAPSHOT`](#admin-create-workload-snapshot-语句)
 
 ## ADMIN 与 DDL 相关的扩展语句
 
@@ -106,7 +107,16 @@ ADMIN SHOW SLOW RECENT N;
 ADMIN SHOW SLOW TOP [INTERNAL | ALL] N;
 ```
 
-这两种语句的具体操作详情可参考：[admin show slow 语句](/identify-slow-queries.md#admin-show-slow-命令)。
+这两种语句的具体操作详情可参考：[ADMIN SHOW SLOW 语句](/identify-slow-queries.md#admin-show-slow-命令)。
+
+## `ADMIN CREATE WORKLOAD SNAPSHOT` 语句
+
+以下 SQL 语句将在 [Workload Repository](/workloadrepo.md) 中触发手动快照：
+
+```sql
+ADMIN CREATE WORKLOAD SNAPSHOT;
+```
+注意，必须启用 Workload Repository，此语句才能生效，否则会报错。
 
 ## 语句概览
 
@@ -145,6 +155,7 @@ AdminStmt ::=
         | 'FLUSH' ('SESSION' | 'INSTANCE') 'PLAN_CACHE'
         | 'SET' 'BDR' 'ROLE' ( 'PRIMARY' | 'SECONDARY' )
         | 'UNSET' 'BDR' 'ROLE'
+        | 'CREATE' 'WORKLOAD' 'SNAPSHOT'
     )
 
 NumList ::=
diff --git a/system-variable-reference.md b/system-variable-reference.md
index 821e4d9916b9..dee9fcb5d3c6 100644
--- a/system-variable-reference.md
+++ b/system-variable-reference.md
@@ -3900,22 +3900,22 @@ summary: 查看 TiDB 所有的系统变量，以及引用这些变量的文档
 
 ### tidb_workload_repository_dest
 
-- [TiDB Workload Repository](/workloadrepo.md#启用-workload-repository)
+- [TiDB Workload Repository](/workload-repository.md#启用-workload-repository)
 - [系统变量](/system-variables.md#tidb_workload_repository_dest-从-v900-版本开始引入)
 
 ### tidb_workload_repository_active_sampling_interval
 
-- [TiDB Workload Repository](/workloadrepo.md#基于时间的采样过程默认每-5-秒)
+- [TiDB Workload Repository](/workload-repository.md#基于时间的采样过程默认每-5-秒)
 - [系统变量](/system-variables.md#tidb_workload_repository_active_sampling_interval-从-v900-版本开始引入)
 
 ### tidb_workload_repository_retention_days
 
-- [TiDB Workload Repository](/workloadrepo.md#数据保留)
+- [TiDB Workload Repository](/workload-repository.md#数据保留)
 - [系统变量](/system-variables.md#tidb_workload_repository_retention_days-从-v900-版本开始引入)
 
 ### tidb_workload_repository_snapshot_interval
 
-- [TiDB Workload Repository](/workloadrepo.md#快照采样过程默认每小时)
+- [TiDB Workload Repository](/workload-repository.md#快照采样过程默认每小时)
 - [系统变量](/system-variables.md#tidb_workload_repository_snapshot_interval-从-v900-版本开始引入)
 
 ### tiflash_fastscan
diff --git a/system-variables.md b/system-variables.md
index 4f3c0dfe2801..4a796c91c734 100644
--- a/system-variables.md
+++ b/system-variables.md
@@ -5346,7 +5346,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
 - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否
 - 类型：字符串
 - 默认值：`''`
-- 该变量用于设置 [Workload Repository](/workloadrepo.md) 的目标位置。
+- 该变量用于设置 [Workload Repository](/workload-repository.md) 的目标位置。
 - 可选值为 `'table'`（启用 Workload Repository）或 `''`（禁用 Workload Repository）。
 
 ### `tidb_workload_repository_active_sampling_interval` <span class="version-mark">从 v9.0.0 版本开始引入</span>
@@ -5358,7 +5358,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
 - 默认值：`5`
 - 范围：`[0, 600]`
 - 单位：秒
-- 用于设置 [Workload Repository](/workloadrepo.md) 的基于时间的采样过程的采样间隔。
+- 用于设置 [Workload Repository](/workload-repository.md) 的基于时间的采样过程的采样间隔。
 - 将该值设置为 `0` 会禁用基于时间的采样过程。
 
 ### `tidb_workload_repository_retention_days` <span class="version-mark">从 v9.0.0 版本开始引入</span>
@@ -5370,7 +5370,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
 - 默认值：`7`
 - 范围：`[0, 365]`
 - 单位：天
-- 用于设置 [Workload Repository](/workloadrepo.md) 数据的保留天数。
+- 用于设置 [Workload Repository](/workload-repository.md) 数据的保留天数。
 - 将该值设置为 `0` 会禁用旧数据的自动清理。
 
 ### `tidb_workload_repository_snapshot_interval` <span class="version-mark">从 v9.0.0 版本开始引入</span>
@@ -5382,7 +5382,7 @@ Query OK, 0 rows affected, 1 warning (0.00 sec)
 - 默认值：`3600`
 - 范围：`[900, 7200]`
 - 单位：秒
-- 用于设置 [TiDB Workload Repository](/workloadrepo.md) 的快照采样过程的采样间隔。
+- 用于设置 [TiDB Workload Repository](/workload-repository.md) 的快照采样过程的采样间隔。
 
 ### `tiflash_fastscan` <span class="version-mark">从 v6.3.0 版本开始引入</span>
 
diff --git a/workloadrepo.md b/workload-repository.md
similarity index 92%
rename from workloadrepo.md
rename to workload-repository.md
index ebc77fe77ada..1a9147e0cbc8 100644
--- a/workloadrepo.md
+++ b/workload-repository.md
@@ -58,7 +58,7 @@ SET GLOBAL tidb_workload_repository_snapshot_interval = 900; -- 将间隔设置
 请注意，虽然快照采样过程会根据配置的时间间隔自动运行，但你也可以使用以下 SQL 语句触发手动快照：
 
 ```sql
-ADMIN WORKLOAD REPOSITORY TAKE SNAPSHOT;
+ADMIN CREATE WORKLOAD SNAPSHOT;
 ```
 
 手动快照并不会改变下一次自动快照的发生时间。
@@ -93,9 +93,9 @@ SET GLOBAL tidb_workload_repository_active_sampling_interval = 20; -- 将间隔
 
 ## 数据保留
 
-Workload Repository 中历史数据默认保留 7 天。系统会根据保留期设置自动清除数据，并使用分区进行高效的数据管理。
+系统会根据保留期设置自动清除数据，并使用分区进行高效的数据管理。
 
-可以通过 [`tidb_workload_repository_retention_days`](/system-variables.md#tidb_workload_repository_retention_days-从-v900-版本开始引入) 变量控制 Workload Repository 中历史数据的保留期。例如，要保留 30 天的数据，运行以下语句：
+默认情况下，Workload Repository 会保留 7 天的历史数据，但你可以通过 [`tidb_workload_repository_retention_days`](/system-variables.md#tidb_workload_repository_retention_days-从-v900-版本开始引入) 变量来控制保留期的长度。例如，要保留 30 天的数据，可以运行以下语句：
 
 ```sql
 SET GLOBAL tidb_workload_repository_retention_days = 30;

From a8bf2b8ab4dbe77da3da83def0fa885a7d6cdb2d Mon Sep 17 00:00:00 2001
From: houfaxin <hfxsd@hotmail.com>
Date: Thu, 17 Apr 2025 09:56:38 +0800
Subject: [PATCH 11/12] Update sql-statement-admin.md

---
 sql-statements/sql-statement-admin.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sql-statements/sql-statement-admin.md b/sql-statements/sql-statement-admin.md
index 0d6b0e72d9d3..a5065620789d 100644
--- a/sql-statements/sql-statement-admin.md
+++ b/sql-statements/sql-statement-admin.md
@@ -111,7 +111,7 @@ ADMIN SHOW SLOW TOP [INTERNAL | ALL] N;
 
 ## `ADMIN CREATE WORKLOAD SNAPSHOT` 语句
 
-以下 SQL 语句将在 [Workload Repository](/workloadrepo.md) 中触发手动快照：
+以下 SQL 语句将在 [Workload Repository](/workload-repository.md) 中触发手动快照：
 
 ```sql
 ADMIN CREATE WORKLOAD SNAPSHOT;

From 89ce68a2a05717b5e7d6d0c5029d2725954d0010 Mon Sep 17 00:00:00 2001
From: houfaxin <hfxsd@hotmail.com>
Date: Thu, 17 Apr 2025 10:02:12 +0800
Subject: [PATCH 12/12] Update sql-statement-admin.md

---
 sql-statements/sql-statement-admin.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/sql-statements/sql-statement-admin.md b/sql-statements/sql-statement-admin.md
index a5065620789d..804aeeb9f908 100644
--- a/sql-statements/sql-statement-admin.md
+++ b/sql-statements/sql-statement-admin.md
@@ -116,6 +116,7 @@ ADMIN SHOW SLOW TOP [INTERNAL | ALL] N;
 ```sql
 ADMIN CREATE WORKLOAD SNAPSHOT;
 ```
+
 注意，必须启用 Workload Repository，此语句才能生效，否则会报错。
 
 ## 语句概览