From 7bf332a3d7666f8bdd2c0c342b8127ad159a3d04 Mon Sep 17 00:00:00 2001 From: TonsnakeLin Date: Mon, 28 Mar 2022 21:41:33 +0800 Subject: [PATCH 1/9] update tidb tidb-functions.md doc Signed-off-by: TonsnakeLin --- functions-and-operators/tidb-functions.md | 39 +++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index 87793e78b011..706149da6c9a 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -329,3 +329,42 @@ select tidb_decode_sql_digests(@digests, 10); - [`Statement Summary Tables`](/statement-summary-tables.md) - [`INFORMATION_SCHEMA.TIDB_TRX`](/information-schema/information-schema-tidb-trx.md) + +## TIDB_SHARD + +TIDB_SHARD 函数用于创建一个 SHARD INDEX 来打散热点索引，如下所示。二级唯一索引 `uk((tidb_shard(a)), a))` 的索引字段 `a` 上存在单调递增或递减而导致的热点，前缀 `tidb_shard(a)` 将热点打散，提升集群扩展性。 + +```SQL +create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); +``` + +### 语法图 + +``` +TIDBShardExpr ::= + "TIDB_SHARD" "(" expr ")" +``` + +### 示例 + +{{< copyable "sql" >}} + +```sql +select TIDB_SHARD(12373743746); +``` + +```sql ++-------------------------+ +| TIDB_SHARD(12373743746) | ++-------------------------+ +| 184 | ++-------------------------+ +1 row in set (0.00 sec) +``` + +以上示例使用 `TIDB_SHARD` 计算 `12373743746` 的 SHARD 值。 + +### MySQL 兼容性 + +`TIDB_SHARD` 是 TiDB 特有的函数，和 MySQL 不兼容。 + From b9f3083b8545bcda941de29296407f8d58d173d5 Mon Sep 17 00:00:00 2001 From: TonsnakeLin <87681388+TonsnakeLin@users.noreply.github.com> Date: Tue, 29 Mar 2022 10:21:15 +0800 Subject: [PATCH 2/9] Apply suggestions from code review Co-authored-by: Enwei --- functions-and-operators/tidb-functions.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index 706149da6c9a..88a809b3dacc 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -332,7 +332,14 @@ select tidb_decode_sql_digests(@digests, 10); ## TIDB_SHARD -TIDB_SHARD 函数用于创建一个 SHARD INDEX 来打散热点索引，如下所示。二级唯一索引 `uk((tidb_shard(a)), a))` 的索引字段 `a` 上存在单调递增或递减而导致的热点，前缀 `tidb_shard(a)` 将热点打散，提升集群扩展性。 +`TIDB_SHARD` 函数用于创建一个 SHARD INDEX 来打散热点索引。当二级唯一索引 `uk((tidb_shard(a)), a))` 的索引字段 `a` 上存在因单调递增或递减而导致的热点时，索引的前缀 `tidb_shard(a)` 将热点打散，从而提升集群扩展性。 + +在高吞吐写入、点查询、批量点查询场景下，你可以在保留原有的查询条件的情况下使用该函数，以提升写入性能。 + +> **注意：** +> +> 如果业务中使用范围查询打散后的数据，可能造成性能回退，请验证后使用。 + ```SQL create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); @@ -347,6 +354,8 @@ TIDBShardExpr ::= ### 示例 +本示例会使用 `TIDB_SHARD` 函数计算 `12373743746` 的 SHARD 值。 + {{< copyable "sql" >}} ```sql @@ -362,8 +371,6 @@ select TIDB_SHARD(12373743746); 1 row in set (0.00 sec) ``` -以上示例使用 `TIDB_SHARD` 计算 `12373743746` 的 SHARD 值。 - ### MySQL 兼容性 `TIDB_SHARD` 是 TiDB 特有的函数，和 MySQL 不兼容。 From 906b89596a5afdbf75839e822e96dba775961849 Mon Sep 17 00:00:00 2001 From: TonsnakeLin Date: Tue, 29 Mar 2022 10:52:16 +0800 Subject: [PATCH 3/9] fix by review advice Signed-off-by: TonsnakeLin --- functions-and-operators/tidb-functions.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index 88a809b3dacc..824fb8fc4108 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -336,9 +336,10 @@ select tidb_decode_sql_digests(@digests, 10); 在高吞吐写入、点查询、批量点查询场景下，你可以在保留原有的查询条件的情况下使用该函数，以提升写入性能。 -> **注意：** +> **注意 SHARD INDEX 使用场景限制：** > -> 如果业务中使用范围查询打散后的数据，可能造成性能回退，请验证后使用。 +> - 二级唯一索引上 key 值存在单调递增或递减导致的写入热点，且该索引包含的列是整形值 +> - 业务中 SQL 语句根据该二级索引的全部字段做等值查询，查询可以是单独的 SELECT，也可以是 UPDATE/DELETE 等产生的内部查询，等值查询包括 "a = 1" 或 "a IN (1, 2, ......)" 两种方式 ```SQL @@ -354,8 +355,6 @@ TIDBShardExpr ::= ### 示例 -本示例会使用 `TIDB_SHARD` 函数计算 `12373743746` 的 SHARD 值。 - {{< copyable "sql" >}} ```sql @@ -371,6 +370,16 @@ select TIDB_SHARD(12373743746); 1 row in set (0.00 sec) ``` +上述示例会使用 `TIDB_SHARD` 函数计算 `12373743746` 的 SHARD 值。 + +{{< copyable "sql" >}} + +```sql +create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); +``` + +上述示例使用 `TIDB_SHARD` 函数创建 SHARD INDEX。 + ### MySQL 兼容性 `TIDB_SHARD` 是 TiDB 特有的函数，和 MySQL 不兼容。 From c49e4500d5918a3aa4473b387da84a2c0fca59e5 Mon Sep 17 00:00:00 2001 From: TonsnakeLin Date: Tue, 29 Mar 2022 11:03:58 +0800 Subject: [PATCH 4/9] fix text format Signed-off-by: TonsnakeLin --- functions-and-operators/tidb-functions.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index 824fb8fc4108..c251c0004c59 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -341,7 +341,6 @@ select tidb_decode_sql_digests(@digests, 10); > - 二级唯一索引上 key 值存在单调递增或递减导致的写入热点，且该索引包含的列是整形值 > - 业务中 SQL 语句根据该二级索引的全部字段做等值查询，查询可以是单独的 SELECT，也可以是 UPDATE/DELETE 等产生的内部查询，等值查询包括 "a = 1" 或 "a IN (1, 2, ......)" 两种方式 - ```SQL create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); ``` @@ -383,4 +382,3 @@ create table test(id int primary key clustered, a int, b int, unique key uk((tid ### MySQL 兼容性 `TIDB_SHARD` 是 TiDB 特有的函数，和 MySQL 不兼容。 - From bcdde5e29d01a6108370a8cef19e9566521b7d09 Mon Sep 17 00:00:00 2001 From: TonsnakeLin <87681388+TonsnakeLin@users.noreply.github.com> Date: Tue, 29 Mar 2022 20:43:35 +0800 Subject: [PATCH 5/9] Apply suggestions from code review Co-authored-by: Enwei --- functions-and-operators/tidb-functions.md | 64 +++++++++++++---------- 1 file changed, 37 insertions(+), 27 deletions(-) diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index c251c0004c59..6375fbb3ade0 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -332,18 +332,26 @@ select tidb_decode_sql_digests(@digests, 10); ## TIDB_SHARD -`TIDB_SHARD` 函数用于创建一个 SHARD INDEX 来打散热点索引。当二级唯一索引 `uk((tidb_shard(a)), a))` 的索引字段 `a` 上存在因单调递增或递减而导致的热点时，索引的前缀 `tidb_shard(a)` 将热点打散，从而提升集群扩展性。 +`TIDB_SHARD` 函数用于创建一个 SHARD INDEX 来打散热点索引。SHARD INDEX 是一种以`TIDB_SHARD` 函数为前缀的表达式索引。 -在高吞吐写入、点查询、批量点查询场景下，你可以在保留原有的查询条件的情况下使用该函数，以提升写入性能。 +### SHARD INDEX -> **注意 SHARD INDEX 使用场景限制：** -> -> - 二级唯一索引上 key 值存在单调递增或递减导致的写入热点，且该索引包含的列是整形值 -> - 业务中 SQL 语句根据该二级索引的全部字段做等值查询，查询可以是单独的 SELECT，也可以是 UPDATE/DELETE 等产生的内部查询，等值查询包括 "a = 1" 或 "a IN (1, 2, ......)" 两种方式 +- 创建方式： -```SQL -create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); -``` + 当二级唯一索引 `uk((tidb_shard(a)), a))` 的索引字段 `a` 上存在因单调递增或递减而产生的热点时，索引的前缀 `tidb_shard(a)` 会打散热点，从而提升集群扩展性。 + +- 适用场景： + + 你可以在高吞吐写入、点查询、批量点查询场景中使用 SHARD INDEX。在该类场景下使用时，你可以在保留原有的查询条件的同时使用该函数，以提升写入性能。 + +- 使用限制： + + - 当二级唯一索引上的 key 值存在单调递增或递减导致的写入热点，且该索引包含的列是整形值时，不应该使用 SHARD INDEX，否则 【XXX】 + - 当业务中的 SQL 语句根据该二级索引的全部字段进行等值查询（包括 "a = 1" 或 "a IN (1, 2, ......)" 两种方式），且查询是单独的 SELECT 语句产生的查询，或是 UPDATE、DELETE 等语句产生的内部查询时，不应该使用 SHARD INDEX，否则 【XXX】。 + + ```SQL + create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); + ``` ### 语法图 @@ -354,30 +362,32 @@ TIDBShardExpr ::= ### 示例 -{{< copyable "sql" >}} +- 使用 `TIDB_SHARD` 函数计算 【XXX】 的 SHARD 值 -```sql -select TIDB_SHARD(12373743746); -``` + 以下示例提供如何使用 `TIDB_SHARD` 函数计算 `12373743746` 的 SHARD 值。 -```sql -+-------------------------+ -| TIDB_SHARD(12373743746) | -+-------------------------+ -| 184 | -+-------------------------+ -1 row in set (0.00 sec) -``` + {{< copyable "sql" >}} -上述示例会使用 `TIDB_SHARD` 函数计算 `12373743746` 的 SHARD 值。 + ```sql + select TIDB_SHARD(12373743746); + ``` -{{< copyable "sql" >}} + ```sql + +-------------------------+ + | TIDB_SHARD(12373743746) | + +-------------------------+ + | 184 | + +-------------------------+ + 1 row in set (0.00 sec) + ``` -```sql -create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); -``` +- 使用 `TIDB_SHARD` 函数创建 SHARD INDEX + + {{< copyable "sql" >}} -上述示例使用 `TIDB_SHARD` 函数创建 SHARD INDEX。 + ```sql + create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); + ``` ### MySQL 兼容性 From f654ed18618b3b935715409c9e53a43da928a227 Mon Sep 17 00:00:00 2001 From: TonsnakeLin Date: Tue, 29 Mar 2022 21:01:24 +0800 Subject: [PATCH 6/9] fix by review advice Signed-off-by: TonsnakeLin --- functions-and-operators/tidb-functions.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index 6375fbb3ade0..6a2ce255a7b2 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -342,16 +342,21 @@ select tidb_decode_sql_digests(@digests, 10); - 适用场景： - 你可以在高吞吐写入、点查询、批量点查询场景中使用 SHARD INDEX。在该类场景下使用时，你可以在保留原有的查询条件的同时使用该函数，以提升写入性能。 + - 二级唯一索引上 key 值存在单调递增或递减导致的写入热点，且该索引包含的列是整形值 + - 业务中 SQL 语句根据该二级索引的全部字段做等值查询，查询可以是单独的 SELECT，也可以是 UPDATE/DELETE 等产生的内部查询，等值查询包括 "a = 1" 或 "a IN (1, 2, ......)" 两种方式 - 使用限制： - - 当二级唯一索引上的 key 值存在单调递增或递减导致的写入热点，且该索引包含的列是整形值时，不应该使用 SHARD INDEX，否则 【XXX】 - - 当业务中的 SQL 语句根据该二级索引的全部字段进行等值查询（包括 "a = 1" 或 "a IN (1, 2, ......)" 两种方式），且查询是单独的 SELECT 语句产生的查询，或是 UPDATE、DELETE 等语句产生的内部查询时，不应该使用 SHARD INDEX，否则 【XXX】。 - - ```SQL - create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); - ``` + - 非等值或 IN 查询无法使用索引 + - 查询条件中 AND 和 OR 混合且最外层是 AND 算子时无法使用 Shard Index索引 + - GROUP BY 无法使用 Shard Index + - ORDER BY 无法使用 Shard Index + - ON 子句无法使用 Shard Index + - WHERE 子查询无法使用 Shard Index + - Shard Index 只能打散整形字段的唯一索引 + - Shard Index 联合索引可能失效 + - Shard Index 无法走 FastPlan流程 + - Shard Index 无法使用 Prepare Plan Cache ### 语法图 From d9ac3cd205231c08f28b1f539d995b50ad31a95b Mon Sep 17 00:00:00 2001 From: TonsnakeLin <87681388+TonsnakeLin@users.noreply.github.com> Date: Fri, 20 May 2022 14:14:45 +0800 Subject: [PATCH 7/9] Apply suggestions from code review Co-authored-by: Aolin --- functions-and-operators/tidb-functions.md | 32 ++++++++++++----------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index 6a2ce255a7b2..4ad88d84e08f 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -332,7 +332,7 @@ select tidb_decode_sql_digests(@digests, 10); ## TIDB_SHARD -`TIDB_SHARD` 函数用于创建一个 SHARD INDEX 来打散热点索引。SHARD INDEX 是一种以`TIDB_SHARD` 函数为前缀的表达式索引。 +`TIDB_SHARD` 函数用于创建一个 SHARD INDEX 来打散热点索引。SHARD INDEX 是一种以 `TIDB_SHARD` 函数为前缀的表达式索引。 ### SHARD INDEX @@ -342,21 +342,21 @@ select tidb_decode_sql_digests(@digests, 10); - 适用场景： - - 二级唯一索引上 key 值存在单调递增或递减导致的写入热点，且该索引包含的列是整形值 - - 业务中 SQL 语句根据该二级索引的全部字段做等值查询，查询可以是单独的 SELECT，也可以是 UPDATE/DELETE 等产生的内部查询，等值查询包括 "a = 1" 或 "a IN (1, 2, ......)" 两种方式 + - 二级唯一索引上 key 值存在单调递增或递减导致的写入热点，且该索引包含的列是整型。 + - 业务中 SQL 语句根据该二级索引的全部字段做等值查询，查询可以是单独的 `SELECT`，也可以是 `UPDATE`，`DELETE` 等产生的内部查询，等值查询包括 `a = 1` 或 `a IN (1, 2, ......)` 两种方式。 - 使用限制： - - 非等值或 IN 查询无法使用索引 - - 查询条件中 AND 和 OR 混合且最外层是 AND 算子时无法使用 Shard Index索引 - - GROUP BY 无法使用 Shard Index - - ORDER BY 无法使用 Shard Index - - ON 子句无法使用 Shard Index - - WHERE 子查询无法使用 Shard Index - - Shard Index 只能打散整形字段的唯一索引 - - Shard Index 联合索引可能失效 - - Shard Index 无法走 FastPlan流程 - - Shard Index 无法使用 Prepare Plan Cache + - 非等值或 `IN` 查询无法使用索引。 + - 查询条件中 `AND` 和 `OR` 混合且最外层是 `AND` 算子时无法使用 SHARED INDEX。 + - `GROUP BY` 无法使用 SHARED INDEX。 + - `ORDER BY` 无法使用 SHARED INDEX。 + - `ON` 子句无法使用 SHARED INDEX。 + - `WHERE` 子查询无法使用 SHARED INDEX。 + - SHARED INDEX 只能打散整型字段的唯一索引。 + - SHARED INDEX 联合索引可能失效。 + - SHARED INDEX 无法走 FastPlan 流程。 + - SHARED INDEX 无法使用执行计划缓存。 ### 语法图 @@ -367,7 +367,7 @@ TIDBShardExpr ::= ### 示例 -- 使用 `TIDB_SHARD` 函数计算 【XXX】 的 SHARD 值 +- 使用 `TIDB_SHARD` 函数计算 SHARD 值 以下示例提供如何使用 `TIDB_SHARD` 函数计算 `12373743746` 的 SHARD 值。 @@ -377,6 +377,8 @@ TIDBShardExpr ::= select TIDB_SHARD(12373743746); ``` +计算得出 SHARD 值为： + ```sql +-------------------------+ | TIDB_SHARD(12373743746) | @@ -391,7 +393,7 @@ TIDBShardExpr ::= {{< copyable "sql" >}} ```sql - create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); + create table test(id int primary key clustered, a int, b int, unique key uk((tidb_shard(a)), a)); ``` ### MySQL 兼容性 From 200ab122c25b882b3b27bdf90151163e451d120d Mon Sep 17 00:00:00 2001 From: Aolin Date: Tue, 24 May 2022 15:21:00 +0800 Subject: [PATCH 8/9] Apply suggestions from code review --- functions-and-operators/tidb-functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index 4ad88d84e08f..6d98c5a4900c 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -377,7 +377,7 @@ TIDBShardExpr ::= select TIDB_SHARD(12373743746); ``` -计算得出 SHARD 值为： +- 计算得出 SHARD 值为： ```sql +-------------------------+ From 5a73be6446d287b7e470a26ef633644462e2ef9c Mon Sep 17 00:00:00 2001 From: Aolin Date: Wed, 25 May 2022 12:07:11 +0800 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- functions-and-operators/tidb-functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/functions-and-operators/tidb-functions.md b/functions-and-operators/tidb-functions.md index 6d98c5a4900c..88362db1d80c 100644 --- a/functions-and-operators/tidb-functions.md +++ b/functions-and-operators/tidb-functions.md @@ -360,7 +360,7 @@ select tidb_decode_sql_digests(@digests, 10); ### 语法图 -``` +```ebnf+diagram TIDBShardExpr ::= "TIDB_SHARD" "(" expr ")" ``` @@ -369,7 +369,7 @@ TIDBShardExpr ::= - 使用 `TIDB_SHARD` 函数计算 SHARD 值 - 以下示例提供如何使用 `TIDB_SHARD` 函数计算 `12373743746` 的 SHARD 值。 + 以下示例说明如何使用 `TIDB_SHARD` 函数计算 `12373743746` 的 SHARD 值。 {{< copyable "sql" >}}