From ef693a6a4cf65dde9285b26c6417c1fb7cbe5cd3 Mon Sep 17 00:00:00 2001 From: Yang Keao Date: Mon, 5 Feb 2024 13:33:30 +0800 Subject: [PATCH] add documents for index usage Signed-off-by: Yang Keao --- TOC.md | 1 + .../information-schema-tidb-index-usage.md | 59 +++++++++++++++++++ information-schema/information-schema.md | 3 + sys-schema.md | 13 ++++ 4 files changed, 76 insertions(+) create mode 100644 information-schema/information-schema-tidb-index-usage.md create mode 100644 sys-schema.md diff --git a/TOC.md b/TOC.md index 94ce25a8736ee..dc3977fd64059 100644 --- a/TOC.md +++ b/TOC.md @@ -976,6 +976,7 @@ - PERFORMANCE_SCHEMA - [Overview](/performance-schema/performance-schema.md) - [`SESSION_CONNECT_ATTRS`](/performance-schema/performance-schema-session-connect-attrs.md) + - [`sys`](/sys-schema.md) - [Metadata Lock](/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 new file mode 100644 index 0000000000000..6db5420f564dd --- /dev/null +++ b/information-schema/information-schema-tidb-index-usage.md @@ -0,0 +1,59 @@ +--- +title: TIDB_INDEX_USAGE +summary: Learn the `TIDB_INDEX_USAGE` information_schema table. +--- + +# TIDB_INDEX_USAGE + +`TIDB_INDEX_USAGE` records the access statistics of all indexes on the current node. + +{{< copyable "sql" >}} + +```sql +USE information_schema; +DESC tidb_index_usage; +``` + +```sql ++--------------------------+-------------+------+------+---------+-------+ +| Field | Type | Null | Key | Default | Extra | ++--------------------------+-------------+------+------+---------+-------+ +| TABLE_SCHEMA | varchar(64) | YES | | NULL | | +| TABLE_NAME | varchar(64) | YES | | NULL | | +| INDEX_NAME | varchar(64) | YES | | NULL | | +| QUERY_TOTAL | bigint(21) | YES | | NULL | | +| KV_REQ_TOTAL | bigint(21) | YES | | NULL | | +| ROWS_ACCESS_TOTAL | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_0 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_0_1 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_1_10 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_10_20 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_20_50 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_50_100 | bigint(21) | YES | | NULL | | +| PERCENTAGE_ACCESS_100 | bigint(21) | YES | | NULL | | +| LAST_ACCESS_TIME | datetime | YES | | NULL | | ++--------------------------+-------------+------+------+---------+-------+ +14 rows in set (0.00 sec) +``` + +The columns in the `TIDB_INDEX_USAGE` table are as follows: + +* `TABLE_SCHEMA`: The name of the database to which the table containing the index belongs. +* `TABLE_NAME`: The name of the table containing the index. +* `INDEX_NAME`: The name of the index. +* `QUERY_TOTAL`: The total number of statements accessing the index. +* `KV_REQ_TOTAL`: The total number of KV requests generated when accessing the index. +* `ROWS_ACCESS_TOTAL`: The total number of rows scanned when accessing the index. +* `PERCENTAGE_ACCESS_0`: The number of times the access ratio of rows to the total number of rows in the table is 0. +* `PERCENTAGE_ACCESS_0_1`: The number of times the access ratio of rows to the total number of rows in the table is between 0% and 1%. +* `PERCENTAGE_ACCESS_1_10`: The number of times the access ratio of rows to the total number of rows in the table is between 1% and 10%. +* `PERCENTAGE_ACCESS_10_20`: The number of times the access ratio of rows to the total number of rows in the table is between 10% and 20%. +* `PERCENTAGE_ACCESS_20_50`: The number of times the access ratio of rows to the total number of rows in the table is between 20% and 50%. +* `PERCENTAGE_ACCESS_50_100`: The number of times the access ratio of rows to the total number of rows in the table is between 50% and 100%. +* `PERCENTAGE_ACCESS_100`: The number of times the access ratio of rows to the total number of rows in the table is 100%. +* `LAST_ACCESS_TIME`: The time when the index was last accessed. + +# Limitations + +- The data in the `TIDB_INDEX_USAGE` table may be delayed by up to 5 minutes. +- After TiDB restarts, the data in the `TIDB_INDEX_USAGE` table is cleared. diff --git a/information-schema/information-schema.md b/information-schema/information-schema.md index 9afd5684c5624..95633c2effa0e 100644 --- a/information-schema/information-schema.md +++ b/information-schema/information-schema.md @@ -124,6 +124,7 @@ Many `INFORMATION_SCHEMA` tables have a corresponding `SHOW` command. The benefi | `CLUSTER_STATEMENTS_SUMMARY` | Provides a cluster-level view of the `STATEMENTS_SUMMARY` table. This table is not available on [TiDB Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-serverless) clusters. | | `CLUSTER_STATEMENTS_SUMMARY_HISTORY` | Provides a cluster-level view of the `STATEMENTS_SUMMARY_HISTORY` table. This table is not available on [TiDB Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-serverless) clusters. | | `CLUSTER_TIDB_TRX` | Provides a cluster-level view of the `TIDB_TRX` table. | +| `CLUSTER_TIDB_INDEX_USAGE` | Provides a cluster-level view of the `TIDB_INDEX_USAGE` table. | | [`CLUSTER_SYSTEMINFO`](/information-schema/information-schema-cluster-systeminfo.md) | Provides details about kernel parameter configuration for servers in the cluster. This table is not applicable to TiDB Cloud. | | [`DATA_LOCK_WAITS`](/information-schema/information-schema-data-lock-waits.md) | Provides the lock-waiting information on the TiKV server. | | [`DDL_JOBS`](/information-schema/information-schema-ddl-jobs.md) | Provides similar output to `ADMIN SHOW DDL JOBS` | @@ -147,6 +148,7 @@ Many `INFORMATION_SCHEMA` tables have a corresponding `SHOW` command. The benefi | [`TIDB_INDEXES`](/information-schema/information-schema-tidb-indexes.md) | Provides index information about TiDB tables. | | [`TIDB_SERVERS_INFO`](/information-schema/information-schema-tidb-servers-info.md) | Provides a list of TiDB servers (namely, tidb-server component) | | [`TIDB_TRX`](/information-schema/information-schema-tidb-trx.md) | Provides the information of the transactions that are being executed on the TiDB node. | +| [`TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md) | Provides the information of the index usage statistics on the TiDB node. ｜ | [`TIFLASH_REPLICA`](/information-schema/information-schema-tiflash-replica.md) | Provides details about TiFlash replicas. | | [`TIKV_REGION_PEERS`](/information-schema/information-schema-tikv-region-peers.md) | Provides details about where regions are stored. | | [`TIKV_REGION_STATUS`](/information-schema/information-schema-tikv-region-status.md) | Provides statistics about regions. | @@ -198,6 +200,7 @@ Many `INFORMATION_SCHEMA` tables have a corresponding `SHOW` command. The benefi | [`TIDB_INDEXES`](/information-schema/information-schema-tidb-indexes.md) | Provides index information about TiDB tables. | | [`TIDB_SERVERS_INFO`](/information-schema/information-schema-tidb-servers-info.md) | Provides a list of TiDB servers (namely, tidb-server component) | | [`TIDB_TRX`](/information-schema/information-schema-tidb-trx.md) | Provides the information of the transactions that are being executed on the TiDB node. | +| [`TIDB_INDEX_USAGE`](/information-schema/information-schema-tidb-index-usage.md) | Provides the information of the index usage statistics on the TiDB node. ｜ | [`TIFLASH_REPLICA`](/information-schema/information-schema-tiflash-replica.md) | Provides details about TiFlash replicas. | | [`TIKV_REGION_PEERS`](/information-schema/information-schema-tikv-region-peers.md) | Provides details about where regions are stored. | | [`TIKV_REGION_STATUS`](/information-schema/information-schema-tikv-region-status.md) | Provides statistics about regions. | diff --git a/sys-schema.md b/sys-schema.md new file mode 100644 index 0000000000000..60874f8003c30 --- /dev/null +++ b/sys-schema.md @@ -0,0 +1,13 @@ +--- +title: sys Schema +summary: Learn about the system tables in the `sys` schema. +--- + +# `sys` Schema + +Tables and views in the `sys` schema are used to help users understand the data in TiDB's system tables, `INFORMATION_SCHEMA` database, and `PERFORMANCE_SCHEMA` database. + +- `schema_unused_index` is used to record indexes that have not been used since the last restart of TiDB. + - `TABLE_SCHEMA`: The name of the database to which the table containing the index belongs. + - `TABLE_NAME`: The name of the table containing the index. + - `INDEX_NAME`: The name of the index. \ No newline at end of file