From 78dd93dee9cd4b136a8fcde7e1831b7198844569 Mon Sep 17 00:00:00 2001 From: Ti Chi Robot Date: Thu, 9 May 2024 11:32:38 +0800 Subject: [PATCH] Add docs for ALTER SEQUENCE and sequence functions (#17220) (#17296) --- TOC.md | 2 + error-codes.md | 2 +- functions-and-operators/sequence-functions.md | 18 ++ .../information-schema-sequences.md | 4 +- .../sql-statement-alter-sequence.md | 215 ++++++++++++++++++ .../sql-statement-create-sequence.md | 53 +++-- sql-statements/sql-statement-drop-sequence.md | 1 + .../sql-statement-show-create-sequence.md | 1 + 8 files changed, 268 insertions(+), 28 deletions(-) create mode 100644 functions-and-operators/sequence-functions.md create mode 100644 sql-statements/sql-statement-alter-sequence.md diff --git a/TOC.md b/TOC.md index 013e39c603e4..92065c16728e 100644 --- a/TOC.md +++ b/TOC.md @@ -740,6 +740,7 @@ - [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md) - [`ALTER RANGE`](/sql-statements/sql-statement-alter-range.md) - [`ALTER RESOURCE GROUP`](/sql-statements/sql-statement-alter-resource-group.md) + - [`ALTER SEQUENCE`](/sql-statements/sql-statement-alter-sequence.md) - [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) - [`ALTER TABLE COMPACT`](/sql-statements/sql-statement-alter-table-compact.md) - [`ALTER USER`](/sql-statements/sql-statement-alter-user.md) @@ -900,6 +901,7 @@ - [其它函数](/functions-and-operators/miscellaneous-functions.md) - [精度数学](/functions-and-operators/precision-math.md) - [集合运算](/functions-and-operators/set-operators.md) + - [序列函数](/functions-and-operators/sequence-functions.md) - [下推到 TiKV 的表达式列表](/functions-and-operators/expressions-pushed-down.md) - [TiDB 特有的函数](/functions-and-operators/tidb-functions.md) - [Oracle 与 TiDB 函数和语法差异对照](/oracle-functions-to-tidb.md) diff --git a/error-codes.md b/error-codes.md index f2089ea05ae8..89c3034d804f 100644 --- a/error-codes.md +++ b/error-codes.md @@ -386,7 +386,7 @@ TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样 * Error Number: 8228 - 在 Sequence 上使用 `setval` 时指定了不支持的类型，该函数的示例可以在 [Sequence 使用文档](/sql-statements/sql-statement-create-sequence.md#示例)中找到。 + 在 Sequence 上使用 `SETVAL` 时指定了不支持的类型，该函数的示例可以在 [Sequence 使用文档](/sql-statements/sql-statement-create-sequence.md#示例)中找到。 * Error Number: 8229 diff --git a/functions-and-operators/sequence-functions.md b/functions-and-operators/sequence-functions.md new file mode 100644 index 000000000000..0f17abd52e29 --- /dev/null +++ b/functions-and-operators/sequence-functions.md @@ -0,0 +1,18 @@ +--- +title: 序列函数 +summary: 了解 TiDB 中的序列函数。 +--- + +# 序列函数 + +TiDB 中的序列函数用于返回或设置使用 [`CREATE SEQUENCE`](/sql-statements/sql-statement-create-sequence.md) 语句创建的序列对象的值。 + +| 函数名称 | 功能描述 | +| :-------- | :-------------------------- | +| `NEXTVAL()` 或 `NEXT VALUE FOR` | 返回序列的下一个值 | +| `SETVAL()` | 设置序列的当前值 | +| `LASTVAL()` | 返回序列中最近一个使用过的值 | + +## MySQL 兼容性 + +根据 [ISO/IEC 9075-2](https://www.iso.org/standard/76584.html)，MySQL 不支持创建和操作序列的函数和语句。 diff --git a/information-schema/information-schema-sequences.md b/information-schema/information-schema-sequences.md index 09ea3833a688..814324b4b543 100644 --- a/information-schema/information-schema-sequences.md +++ b/information-schema/information-schema-sequences.md @@ -37,14 +37,14 @@ DESC SEQUENCES; ```sql CREATE SEQUENCE test.seq; -SELECT nextval(test.seq); +SELECT NEXTVAL(test.seq); ``` 输出结果如下： ```sql +-------------------+ -| nextval(test.seq) | +| NEXTVAL(test.seq) | +-------------------+ | 1 | +-------------------+ diff --git a/sql-statements/sql-statement-alter-sequence.md b/sql-statements/sql-statement-alter-sequence.md new file mode 100644 index 000000000000..cd030e1d9296 --- /dev/null +++ b/sql-statements/sql-statement-alter-sequence.md @@ -0,0 +1,215 @@ +--- +title: ALTER SEQUENCE +summary: 介绍 ALTER SEQUENCE 在 TiDB 中的使用概况。 +--- + +# ALTER SEQUENCE + +`ALTER SEQUENCE` 语句用于在 TiDB 中修改序列对象。序列是一种与 `Table` 和 `View` 对象平级的数据库对象，用于生成自定义的序列化 ID。 + +## 语法图 + +```ebnf+diagram +CreateSequenceStmt ::= + 'ALTER' 'SEQUENCE' TableName CreateSequenceOptionListOpt + +TableName ::= + Identifier ('.' Identifier)? + +CreateSequenceOptionListOpt ::= + SequenceOption* + +SequenceOptionList ::= + SequenceOption + +SequenceOption ::= + ( 'INCREMENT' ( '='? | 'BY' ) | 'START' ( '='? | 'WITH' ) | ( 'MINVALUE' | 'MAXVALUE' | 'CACHE' ) '='? ) SignedNum +| 'COMMENT' '='? stringLit +| 'NOMINVALUE' +| 'NO' ( 'MINVALUE' | 'MAXVALUE' | 'CACHE' | 'CYCLE' ) +| 'NOMAXVALUE' +| 'NOCACHE' +| 'CYCLE' +| 'NOCYCLE' +| 'RESTART' ( ( '='? | 'WITH' ) SignedNum )? +``` + +## 语法说明 + +```sql +ALTER SEQUENCE sequence_name + [ INCREMENT [ BY | = ] increment ] + [ MINVALUE [=] minvalue | NO MINVALUE | NOMINVALUE ] + [ MAXVALUE [=] maxvalue | NO MAXVALUE | NOMAXVALUE ] + [ START [ WITH | = ] start ] + [ CACHE [=] cache | NOCACHE | NO CACHE] + [ CYCLE | NOCYCLE | NO CYCLE] + [table_options] +``` + +## 参数说明 + +|参数 | 默认值 | 描述 | +| :-- | :-- | :--| +| `INCREMENT` | `1` | 指定序列的步长。其正负值可以控制序列的增长方向。| +| `MINVALUE` | `1` 或 `-9223372036854775807` | 指定序列的最小值。当 `INCREMENT` > `0` 时，默认值为 `1`；当 `INCREMENT` < `0` 时，默认值为 `-9223372036854775807`。| +| `MAXVALUE` | `9223372036854775806` 或 `-1` | 指定序列的最大值。当 `INCREMENT` > `0` 时，默认值为 `9223372036854775806`；当 `INCREMENT` < `0` 时，默认值为 `-1`。| +| `START` | `MINVALUE` 或 `MAXVALUE` | 指定序列的初始值。当 `INCREMENT` > `0` 时，默认值为 `MINVALUE`; 当 `INCREMENT` < `0` 时，默认值为 `MAXVALUE`。 | +| `CACHE` | `1000` | 指定每个 TiDB 本地缓存序列的大小。| +| `CYCLE` | `NO CYCLE` | 指定序列用完之后是否要循环使用。在 `CYCLE` 的情况下，当 `INCREMENT` > `0` 时，序列用完后的后续起始值为 `MINVALUE`；当 `INCREMENT` < `0` 时，序列用完后的后续起始值为 `MAXVALUE`。| + +> **注意：** +> +> 在执行 `ALTER SEQUENCE ... RESTART` 之前，更改 `START` 值不会影响生成的值。 + +## `SEQUENCE` 函数 + +主要通过表达式函数来操纵序列的使用。 + ++ `NEXTVAL` 或 `NEXT VALUE FOR` + + 本质上都是 `NEXTVAL()` 函数，获取序列对象的下一个有效值，其参数为序列的 `identifier`。 + ++ `LASTVAL` + + `LASTVAL()` 函数，用于获取本会话上一个使用过的值。如果没有值，则为 `NULL`，其参数为序列的 `identifier`。 + ++ `SETVAL` + + `SETVAL()` 函数，用于设置序列的增长。其第一参数为序列的 `identifier`，第二个参数为 `num`。 + +> **注意：** +> +> 在 TiDB 序列的实现中，`SETVAL` 函数并不能改变序列增长的初始步调或循环步调。在 `SETVAL` 之后只会返回符合步调规律的下一个有效的序列值。 + +## 示例 + +创建一个名为 `s1` 的序列： + +```sql +CREATE SEQUENCE s1; +``` + +``` +Query OK, 0 rows affected (0.15 sec) +``` + +执行以下 SQL 语句两次，获取该序列接下来的两个值： + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 1 | ++-------------+ +1 row in set (0.01 sec) +``` + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 2 | ++-------------+ +1 row in set (0.00 sec) +``` + +将该序列的步长更改为 `2`： + +```sql +ALTER SEQUENCE s1 INCREMENT=2; +``` + +``` +Query OK, 0 rows affected (0.18 sec) +``` + +此时，再次获取该序列接下来的两个值： + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 1001 | ++-------------+ +1 row in set (0.02 sec) +``` + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 1003 | ++-------------+ +1 row in set (0.00 sec) +``` + +从以上输出中可以看到，在执行了 `ALTER SEQUENCE` 语句后，数值的增幅为 `2`。 + +你还可以更改序列的其他参数。例如，可以按照以下方式更改序列的 `MAXVALUE`： + +```sql +CREATE SEQUENCE s2 MAXVALUE=10; +``` + +``` +Query OK, 0 rows affected (0.17 sec) +``` + +```sql +ALTER SEQUENCE s2 MAXVALUE=100; +``` + +``` +Query OK, 0 rows affected (0.15 sec) +``` + +```sql +SHOW CREATE SEQUENCE s2\G +``` + +``` +*************************** 1. row *************************** + Sequence: s2 +Create Sequence: CREATE SEQUENCE `s2` start with 1 minvalue 1 maxvalue 100 increment by 1 cache 1000 nocycle ENGINE=InnoDB +1 row in set (0.00 sec) +``` + +## MySQL 兼容性 + +该语句是 TiDB 的扩展，序列的实现借鉴自 MariaDB。 + +除了 `SETVAL` 函数外，其他函数的“步调 (progressions)” 与 MariaDB 一致。这里的步调是指，序列中的数在定义之后会产生一定的等差关系。`SETVAL` 虽然可以将序列的当前值进行移动设置，但是后续出现的值仍会遵循原有的等差关系。 + +示例如下： + +``` +1, 3, 5, ... // 序列遵循起始为 1、步长为 2 的等差关系。 +SELECT SETVAL(seq, 6) // 设置序列的当前值为 6。 +7, 9, 11, ... // 后续产生值仍会遵循这个等差关系。 +``` + +在 `CYCLE` 模式下，序列的起始值第一轮为 `START`，后续轮次将会是 `MinValue` (INCREMENT > 0) 或 `MaxValue` (INCREMENT < 0)。 + +## 另请参阅 + +* [CREATE SEQUENCE](/sql-statements/sql-statement-create-sequence.md) +* [DROP SEQUENCE](/sql-statements/sql-statement-drop-sequence.md) +* [SHOW CREATE SEQUENCE](/sql-statements/sql-statement-show-create-sequence.md) +* [Sequence Functions](/functions-and-operators/sequence-functions.md) diff --git a/sql-statements/sql-statement-create-sequence.md b/sql-statements/sql-statement-create-sequence.md index f3c1818bae12..fa20fefe0a3a 100644 --- a/sql-statements/sql-statement-create-sequence.md +++ b/sql-statements/sql-statement-create-sequence.md @@ -11,7 +11,7 @@ summary: CREATE SEQUENCE 在 TiDB 中的使用概况 ```ebnf+diagram CreateSequenceStmt ::= - 'CREATE' 'SEQUENCE' IfNotExists TableName CreateSequenceOptionListOpt CreateTableOptionListOpt + 'CREATE' 'SEQUENCE' IfNotExists TableName CreateSequenceOptionListOpt IfNotExists ::= ('IF' 'NOT' 'EXISTS')? @@ -27,6 +27,7 @@ SequenceOptionList ::= SequenceOption ::= ( 'INCREMENT' ( '='? | 'BY' ) | 'START' ( '='? | 'WITH' ) | ( 'MINVALUE' | 'MAXVALUE' | 'CACHE' ) '='? ) SignedNum +| 'COMMENT' '='? stringLit | 'NOMINVALUE' | 'NO' ( 'MINVALUE' | 'MAXVALUE' | 'CACHE' | 'CYCLE' ) | 'NOMAXVALUE' @@ -68,15 +69,15 @@ CREATE [TEMPORARY] SEQUENCE [IF NOT EXISTS] sequence_name + `NEXTVAL` 或 `NEXT VALUE FOR` - 本质上都是 `nextval()` 函数，获取序列对象的下一个有效值，其参数为序列的 `identifier`。 + 本质上都是 `NEXTVAL()` 函数，获取序列对象的下一个有效值，其参数为序列的 `identifier`。 + `LASTVAL` - `lastval()` 函数，用于获取本会话上一个使用过的值。如果没有值，则为 `NULL`，其参数为序列的 `identifier`。 + `LASTVAL()` 函数，用于获取本会话上一个使用过的值。如果没有值，则为 `NULL`，其参数为序列的 `identifier`。 + `SETVAL` - `setval()` 函数，用于设置序列的增长。其第一参数为序列的 `identifier`，第二个参数为 `num`。 + `SETVAL()` 函数，用于设置序列的增长。其第一参数为序列的 `identifier`，第二个参数为 `num`。 > **注意：** > @@ -96,51 +97,51 @@ CREATE [TEMPORARY] SEQUENCE [IF NOT EXISTS] sequence_name Query OK, 0 rows affected (0.06 sec) ``` -+ 使用 `nextval()` 函数获取序列对象的下一个值。 ++ 使用 `NEXTVAL()` 函数获取序列对象的下一个值。 {{< copyable "sql" >}} ```sql - SELECT nextval(seq); + SELECT NEXTVAL(seq); ``` ``` +--------------+ - | nextval(seq) | + | NEXTVAL(seq) | +--------------+ | 1 | +--------------+ 1 row in set (0.02 sec) ``` -+ 使用 `lastval()` 函数获取本会话上一次调用序列对象所产生的值。 ++ 使用 `LASTVAL()` 函数获取本会话上一次调用序列对象所产生的值。 {{< copyable "sql" >}} ```sql - SELECT lastval(seq); + SELECT LASTVAL(seq); ``` ``` +--------------+ - | lastval(seq) | + | LASTVAL(seq) | +--------------+ | 1 | +--------------+ 1 row in set (0.02 sec) ``` -+ 使用 `setval()` 函数设置序列对象当前值的位置。 ++ 使用 `SETVAL()` 函数设置序列对象当前值的位置。 {{< copyable "sql" >}} ```sql - SELECT setval(seq, 10); + SELECT SETVAL(seq, 10); ``` ``` +-----------------+ - | setval(seq, 10) | + | SETVAL(seq, 10) | +-----------------+ | 10 | +-----------------+ @@ -176,58 +177,58 @@ CREATE [TEMPORARY] SEQUENCE [IF NOT EXISTS] sequence_name Query OK, 0 rows affected (0.01 sec) ``` -+ 当本会话还未使用过序列对象时，`lastval()` 函数返回 NULL 值。 ++ 当本会话还未使用过序列对象时，`LASTVAL()` 函数返回 NULL 值。 {{< copyable "sql" >}} ```sql - SELECT lastval(seq2); + SELECT LASTVAL(seq2); ``` ``` +---------------+ - | lastval(seq2) | + | LASTVAL(seq2) | +---------------+ | NULL | +---------------+ 1 row in set (0.01 sec) ``` -+ 序列对象 `nextval()` 的第一个有效值为 `start` 值。 ++ 序列对象 `NEXTVAL()` 的第一个有效值为 `start` 值。 {{< copyable "sql" >}} ```sql - SELECT nextval(seq2); + SELECT NEXTVAL(seq2); ``` ``` +---------------+ - | nextval(seq2) | + | NEXTVAL(seq2) | +---------------+ | 3 | +---------------+ 1 row in set (0.00 sec) ``` -+ 使用 `setval()` 虽然可以改变序列对象当前值的位置，但是无法改变下一个值的等差规律。 ++ 使用 `SETVAL()` 虽然可以改变序列对象当前值的位置，但是无法改变下一个值的等差规律。 {{< copyable "sql" >}} ```sql - SELECT setval(seq2, 6); + SELECT SETVAL(seq2, 6); ``` ``` +-----------------+ - | setval(seq2, 6) | + | SETVAL(seq2, 6) | +-----------------+ | 6 | +-----------------+ 1 row in set (0.00 sec) ``` -+ 使用 `nextval()` 下一个值获取时，会遵循序列定义的等差规律。 ++ 使用 `NEXTVAL()` 下一个值获取时，会遵循序列定义的等差规律。 {{< copyable "sql" >}} @@ -305,13 +306,15 @@ CREATE [TEMPORARY] SEQUENCE [IF NOT EXISTS] sequence_name ``` 1, 3, 5, ... // 序列遵循起始为 1、步长为 2 的等差关系。 -select setval(seq, 6) // 设置序列的当前值为 6。 +select SETVAL(seq, 6) // 设置序列的当前值为 6。 7, 9, 11, ... // 后续产生值仍会遵循这个等差关系。 ``` -在 `CYCLE` 模式下，序列的起始值第一轮为 `start`，后续轮次将会是 `MinValue` (increment > 0) 或 `MaxValue` (increment < 0)。 +在 `CYCLE` 模式下，序列的起始值第一轮为 `START`，后续轮次将会是 `MinValue` (INCREMENT > 0) 或 `MaxValue` (INCREMENT < 0)。 ## 另请参阅 +* [ALTER SEQUENCE](/sql-statements/sql-statement-alter-sequence.md) * [DROP SEQUENCE](/sql-statements/sql-statement-drop-sequence.md) * [SHOW CREATE SEQUENCE](/sql-statements/sql-statement-show-create-sequence.md) +* [Sequence 函数](/functions-and-operators/sequence-functions.md) diff --git a/sql-statements/sql-statement-drop-sequence.md b/sql-statements/sql-statement-drop-sequence.md index 9019175e3253..76163a1ca24e 100644 --- a/sql-statements/sql-statement-drop-sequence.md +++ b/sql-statements/sql-statement-drop-sequence.md @@ -51,4 +51,5 @@ Query OK, 0 rows affected (0.03 sec) ## 另请参阅 * [CREATE SEQUENCE](/sql-statements/sql-statement-create-sequence.md) +* [ALTER SEQUENCE](/sql-statements/sql-statement-alter-sequence.md) * [SHOW CREATE SEQUENCE](/sql-statements/sql-statement-show-create-sequence.md) diff --git a/sql-statements/sql-statement-show-create-sequence.md b/sql-statements/sql-statement-show-create-sequence.md index f83d61bb513c..e500af44183e 100644 --- a/sql-statements/sql-statement-show-create-sequence.md +++ b/sql-statements/sql-statement-show-create-sequence.md @@ -44,4 +44,5 @@ SHOW CREATE SEQUENCE seq; ## 另请参阅 * [CREATE SEQUENCE](/sql-statements/sql-statement-create-sequence.md) +* [ALTER SEQUENCE](/sql-statements/sql-statement-alter-sequence.md) * [DROP SEQUENCE](/sql-statements/sql-statement-drop-sequence.md)