address comments

Signed-off-by: Yang Keao <[email protected]>
pingcap · Mar 4, 2024 · 2dabcd3 · 2dabcd3
1 parent 1dc5a34
commit 2dabcd3
Show file tree

Hide file tree

Showing 3 changed files with 100 additions and 48 deletions.
diff --git a/TOC.md b/TOC.md
@@ -961,6 +961,7 @@
         - [`TIDB_HOT_REGIONS`](/information-schema/information-schema-tidb-hot-regions.md)
         - [`TIDB_HOT_REGIONS_HISTORY`](/information-schema/information-schema-tidb-hot-regions-history.md)
         - [`TIDB_INDEXES`](/information-schema/information-schema-tidb-indexes.md)
+        - [`TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md)
         - [`TIDB_SERVERS_INFO`](/information-schema/information-schema-tidb-servers-info.md)
         - [`TIDB_TRX`](/information-schema/information-schema-tidb-trx.md)
         - [`TIFLASH_REPLICA`](/information-schema/information-schema-tiflash-replica.md)
@@ -977,7 +978,7 @@
       - PERFORMANCE_SCHEMA
         - [概述](/performance-schema/performance-schema.md)
         - [`SESSION_CONNECT_ATTRS`](/performance-schema/performance-schema-session-connect-attrs.md)
-      - [`sys`](/sys-schema.md)
+      - [`SYS`](/sys-schema.md)
     - [元数据锁](/metadata-lock.md)
     - [TiDB DDL V2](/ddl-v2.md)
   - UI

diff --git a/information-schema/information-schema-tidb-index-usage.md b/information-schema/information-schema-tidb-index-usage.md
@@ -5,13 +5,11 @@ summary: 了解 information_schema 表 `TIDB_INDEX_USAGE`。
 
 # TIDB_INDEX_USAGE
 
-`TIDB_INDEX_USAGE` 记录了当前节点所有 Index 的访问统计信息。
-
-{{< copyable "sql" >}}
+TiDB 从 v8.0.0 开始提供 `TIDB_INDEX_USAGE` 表，你可以使用该表查看当前 TiDB 节点中所有索引的访问统计信息。
 
 ```sql
-USE information_schema;
-DESC tidb_index_usage;
+USE INFORMATION_SCHEMA;
+DESC TIDB_INDEX_USAGE;
 ```
 
 ```sql
@@ -40,20 +38,56 @@ DESC tidb_index_usage;
 
 * `TABLE_SCHEMA`：索引所在表的所属数据库的名称。
 * `TABLE_NAME`：索引所在表的名称。
-* `INDEX_NAME`：索引的名称
+* `INDEX_NAME`：索引的名称。
 * `QUERY_TOTAL`：访问该索引的语句总数。
 * `KV_REQ_TOTAL`：访问该索引时产生的 KV 请求总数。
 * `ROWS_ACCESS_TOTAL`：访问该索引时扫描的总行数。
-* `PERCENTAGE_ACCESS_0`：访问行数占表总行数比例为 0 的次数。
-* `PERCENTAGE_ACCESS_0_1`：访问行数占总行数比例为 0 到 1% 的次数。
-* `PERCENTAGE_ACCESS_1_10`：访问行数占总行数比例为 1% 到 10% 的次数。
-* `PERCENTAGE_ACCESS_10_20`：访问行数占总行数比例为 10% 到 20% 的次数。
-* `PERCENTAGE_ACCESS_20_50`：访问行数占总行数比例为 20% 到 50% 的次数。
-* `PERCENTAGE_ACCESS_50_100`：访问行数占总行数比例为 50% 到 100% 的次数。
-* `PERCENTAGE_ACCESS_100`：访问行数占总行数比例为 100% 的次数。
-* `LAST_ACCESS_TIME`：最后一次访问该索引的时间。
-
-# 限制
-
-- `TIDB_INDEX_USAGE` 表中的数据可能有至多 5 分钟的延迟。
+* `PERCENTAGE_ACCESS_0`：行访问比例（访问行数占表总行数的百分比）为 0 的次数。
+* `PERCENTAGE_ACCESS_0_1`：行访问比例为 0 到 1% 的次数。
+* `PERCENTAGE_ACCESS_1_10`：行访问比例为 1% 到 10% 的次数。
+* `PERCENTAGE_ACCESS_10_20`：行访问比例为 10% 到 20% 的次数。
+* `PERCENTAGE_ACCESS_20_50`：行访问比例为 20% 到 50% 的次数。
+* `PERCENTAGE_ACCESS_50_100`：行访问比例为 50% 到 100% 的次数。
+* `PERCENTAGE_ACCESS_100`：行访问比例为 100% 的次数。
+* `LAST_ACCESS_TIME`：最近一次访问该索引的时间。
+
+## CLUSTER_TIDB_INDEX_USAGE
+
+`TIDB_INDEX_USAGE` 表仅提供单个 TiDB 节点中所有索引的访问统计信息。如果要查看整个集群上所有 TiDB 节点中索引的访问统计信息，需要查询 `CLUSTER_TIDB_INDEX_USAGE` 表。
+
+与 `TIDB_INDEX_USAGE` 表的查询结果相比，`CLUSTER_TIDB_INDEX_USAGE` 表的查询结果额外包含了 INSTANCE 字段。INSTANCE 字段展示了集群中各节点的 IP 地址和端口，用于区分不同节点上的统计信息。
+
+```sql
+USE INFORMATION_SCHEMA;
+DESC CLUSTER_TIDB_INDEX_USAGE;
+```
+
+输出结果如下：
+
+```sql
++-------------------------+-----------------------------------------------------------------+------+------+---------+-------+
+| Field                   | Type                                                            | Null | Key  | Default | Extra |
++-------------------------+-----------------------------------------------------------------+------+------+---------+-------+
+| INSTANCE                | varchar(64)                                                     | YES  |      | NULL    |       |
+| ID                      | bigint(21) unsigned                                             | NO   | PRI  | NULL    |       |
+| START_TIME              | timestamp(6)                                                    | YES  |      | NULL    |       |
+| CURRENT_SQL_DIGEST      | varchar(64)                                                     | YES  |      | NULL    |       |
+| CURRENT_SQL_DIGEST_TEXT | text                                                            | YES  |      | NULL    |       |
+| STATE                   | enum('Idle','Running','LockWaiting','Committing','RollingBack') | YES  |      | NULL    |       |
+| WAITING_START_TIME      | timestamp(6)                                                    | YES  |      | NULL    |       |
+| MEM_BUFFER_KEYS         | bigint(64)                                                      | YES  |      | NULL    |       |
+| MEM_BUFFER_BYTES        | bigint(64)                                                      | YES  |      | NULL    |       |
+| SESSION_ID              | bigint(21) unsigned                                             | YES  |      | NULL    |       |
+| USER                    | varchar(16)                                                     | YES  |      | NULL    |       |
+| DB                      | varchar(64)                                                     | YES  |      | NULL    |       |
+| ALL_SQL_DIGESTS         | text                                                            | YES  |      | NULL    |       |
+| RELATED_TABLE_IDS       | text                                                            | YES  |      | NULL    |       |
+| WAITING_TIME            | double                                                          | YES  |      | NULL    |       |
++-------------------------+-----------------------------------------------------------------+------+------+---------+-------+
+15 rows in set (0.00 sec)
+```
+
+## 使用限制
+
+- `TIDB_INDEX_USAGE` 表中的数据可能存在最多 5 分钟的延迟。
 - 在 TiDB 重启后，`TIDB_INDEX_USAGE` 表中的数据会被清空。
diff --git a/sys-schema.md b/sys-schema.md
@@ -1,35 +1,52 @@
 ---
 title: sys Schema
-summary: 了解 sys 库中的系统表。
+summary: 了解 TiDB `sys` 系统数据库。
 ---
 
 # `sys` Schema
 
-> **注意：**
->
-> 从 v8.0.0 及之前版本升级的集群将不包含 `sys` Schema 和其中的 View。它们可以通过以下 SQL 语句创建：
->
-> {{< copyable "sql" >}}
->
-> ```sql
-> CREATE DATABASE IF NOT EXISTS sys;
-> CREATE OR REPLACE VIEW sys.schema_unused_indexes AS
->   SELECT
->     table_schema as object_schema,
->     table_name as object_name,
->     index_name
->   FROM information_schema.cluster_tidb_index_usage
->   WHERE
->     table_schema not in ('sys', 'mysql', 'INFORMATION_SCHEMA', 'PERFORMANCE_SCHEMA') and
->     index_name != 'PRIMARY'
->   GROUP BY table_schema, table_name, index_name
->   HAVING
->     sum(last_access_time) is null;
-> ```
-
-`sys` 库里的表或视图被用于帮助用户理解 TiDB 的系统表、`INFORMATION_SCHEMA` 表和 `Performance Schema` 表内的数据。
-
-- `schema_unused_index` 用于记录自从 TiDB 上一次重启以来未使用的索引。
-    - `OBJECT_SCHEMA`：索引所在表的所属数据库的名称。
-    - `OBJECT_NAME`：索引所在表的名称。
-    - `INDEX_NAME`：索引的名称。
+TiDB 从 v8.0.0 开始提供 `sys` Schema。你可以通过查看 `sys` 系统数据库中的表或视图理解 TiDB 的系统表、[`INFORMATION_SCHEMA` 表](/information-schema/information-schema.md)和 [`PERFORMANCE SCHEMA` 表](/performance-schema/performance-schema.md)内的数据。
+
+对于从 v8.0.0 之前版本升级的集群，`sys` Schema 和其中的视图不会自动创建。你可以通过以下 SQL 语句手动创建：
+
+```sql
+CREATE DATABASE IF NOT EXISTS sys;
+CREATE OR REPLACE VIEW sys.schema_unused_indexes AS
+  SELECT
+    table_schema as object_schema,
+    table_name as object_name,
+    index_name
+  FROM information_schema.cluster_tidb_index_usage
+  WHERE
+    table_schema not in ('sys', 'mysql', 'INFORMATION_SCHEMA', 'PERFORMANCE_SCHEMA') and
+    index_name != 'PRIMARY'
+  GROUP BY table_schema, table_name, index_name
+  HAVING
+    sum(last_access_time) is null;
+```
+
+## `schema_unused_index`
+
+`schema_unused_index` 用于记录自 TiDB 上次启动以来未被使用的索引信息，包括如下列：
+
+- `OBJECT_SCHEMA`：索引所在表的所属数据库的名称。
+- `OBJECT_NAME`：索引所在表的名称。
+- `INDEX_NAME`：索引的名称。
+
+```sql
+USE sys;
+DESC schema_unused_indexes;
+```
+
+输出结果如下：
+
+```sql
++---------------+-------------+------+------+---------+-------+
+| Field         | Type        | Null | Key  | Default | Extra |
++---------------+-------------+------+------+---------+-------+
+| object_schema | varchar(64) | YES  |      | NULL    |       |
+| object_name   | varchar(64) | YES  |      | NULL    |       |
+| index_name    | varchar(64) | YES  |      | NULL    |       |
++---------------+-------------+------+------+---------+-------+
+3 rows in set (0.00 sec)
+```