Skip to content

sql: fix sequence doc #2380

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Mar 11, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions TOC.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,7 @@
- [`COMMIT`](/reference/sql/statements/commit.md)
- [`CREATE DATABASE`](/reference/sql/statements/create-database.md)
- [`CREATE INDEX`](/reference/sql/statements/create-index.md)
- [`CREATE SEQUENCE`](/reference/sql/statements/create-sequence.md)
- [`CREATE TABLE LIKE`](/reference/sql/statements/create-table-like.md)
- [`CREATE TABLE`](/reference/sql/statements/create-table.md)
- [`CREATE USER`](/reference/sql/statements/create-user.md)
Expand All @@ -159,6 +160,7 @@
- [`DROP COLUMN`](/reference/sql/statements/drop-column.md)
- [`DROP DATABASE`](/reference/sql/statements/drop-database.md)
- [`DROP INDEX`](/reference/sql/statements/drop-index.md)
- [`DROP SEQUENCE`](/reference/sql/statements/drop-sequence.md)
- [`DROP TABLE`](/reference/sql/statements/drop-table.md)
- [`DROP USER`](/reference/sql/statements/drop-user.md)
- [`DROP VIEW`](/reference/sql/statements/drop-view.md)
Expand Down Expand Up @@ -188,6 +190,7 @@
- [`SHOW CHARACTER SET`](/reference/sql/statements/show-character-set.md)
- [`SHOW COLLATION`](/reference/sql/statements/show-collation.md)
- [`SHOW [FULL] COLUMNS FROM`](/reference/sql/statements/show-columns-from.md)
- [`SHOW CREATE SEQUENCE`](/reference/sql/statements/show-create-sequence.md)
- [`SHOW CREATE TABLE`](/reference/sql/statements/show-create-table.md)
- [`SHOW CREATE USER`](/reference/sql/statements/show-create-user.md)
- [`SHOW DATABASES`](/reference/sql/statements/show-databases.md)
Expand Down
54 changes: 35 additions & 19 deletions reference/sql/statements/create-sequence.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ category: reference

# CREATE SEQUENCE

`CREATE SEQUENCE` 语句用于在 TiDB 中创建 SEQUENCE 对象。SEQUENCE 是一种与表、视图对象平级的数据库对象,用于进行自定义的序列化 id 生成。
`CREATE SEQUENCE` 语句用于在 TiDB 中创建序列对象。序列是一种与表、视图对象平级的数据库对象,用于进行自定义的序列化 ID 生成。

## 语法图

Expand Down Expand Up @@ -40,6 +40,8 @@ category: reference

## 语法说明

{{< copyable "sql" >}}

```
CREATE [TEMPORARY] SEQUENCE [IF NOT EXISTS] sequence_name
[ INCREMENT [ BY | = ] increment ]
Expand All @@ -54,32 +56,34 @@ CREATE [TEMPORARY] SEQUENCE [IF NOT EXISTS] sequence_name

## 参数说明

参数 | 默认值 | 描述
-|-|-
INCREMENT | 1 | 指定序列的步长,其正负值可以控制 SEQUENCE 的增长方向。
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 本地缓存序列的大小,默认值为 1000。
CYCLE | false | 指定序列用完之后的是否循环使用。在 CYCLE 的情况下,当 INCREMENT > 0 时,默认值为 MINVALUE;当 INCREMENT < 0 时,默认值为 MAXVALUE
|参数 | 默认值 | 描述 |
| :-- | :-- | :--|
| `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` | `false` | 指定序列用完之后是否要循环使用。在 `CYCLE` 的情况下,当 `INCREMENT` > `0` 时,后续起始值为 `MINVALUE`;当 `INCREMENT` < `0` 时,后续起始值为 `MAXVALUE`。|

## SEQUENCE 函数
## `SEQUENCE` 函数

SEQUENCE 的使用主要通过表达式函数来操纵
主要通过表达式函数来操纵序列的使用。

**NEXTVAL / NEXT VALUE FOR**
+ `NEXTVAL` 或 `NEXT VALUE FOR`

本质上都是 nextval() 函数, 获取 SEQUENCE 对象的下一个有效值,其参数为 SEQUENCE 序列的 identifier。
本质上都是 `nextval()` 函数,获取序列对象的下一个有效值,其参数为序列的 `identifier`

**LASTVAL**
+ `LASTVAL`

lastval() 函数,用于获取本会话上一个使用过的值,如果没有则为 NULL, 其参数为 SEQUENCE 序列的 identifier。
`lastval()` 函数,用于获取本会话上一个使用过的值。如果没有值,则为 `NULL`,其参数为序列的 `identifier`

**SETVAL**
+ `SETVAL`

setval() 函数,用于设置序列的增长,其第一参数为 SEQUENCE 序列的 identifier,第二个参数为 num。
`setval()` 函数,用于设置序列的增长。其第一参数为序列的 `identifier`,第二个参数为 `num`

> 注意:在 TiDB SEQUENCE 的实现中,setval 函数并不能改变序列增长的初始步调/循环步调,在 setval 之后只会返回符合步调规律的下一个有效的序列值。
> **注意:**
>
> 在 TiDB 序列的实现中,`SETVAL` 函数并不能改变序列增长的初始步调或循环步调。在 `SETVAL` 之后只会返回符合步调规律的下一个有效的序列值。

## 示例

Expand Down Expand Up @@ -270,7 +274,19 @@ ERROR 4135 (HY000): Sequence 'test.seq2' has run out

## MySQL 兼容性

* MySQL 暂无 SEQUENCE 选项。TiDB Sequence 借鉴自 MariaDB,但是 setval 会保持原有的步调。
MySQL 暂无序列选项。TiDB 序列借鉴自 MariaDB。`SETVAL` 函数的步调是 TiDB 特有的,其他函数的步调与 MariaDB 保持一致。

这里的步调是指,序列中的数在定义之后会产生一定的等差关系。`SETVAL` 虽然可以将序列的当前值进行移动设置,但是后续出现的值仍会遵循原有的等差关系。

示例如下:

```
1, 3, 5, ... // 序列遵循起始为 1、步长为 2 的等差关系。
select setval(seq, 6) // 设置序列的当前值为 6。
7, 9, 11, ... // 后续产生值仍会遵循这个等差关系。
```

在 `CYCLE` 模式下,序列的起始值第一轮为 `start`,后续轮次将会是 `MinValue` (increment > 0) 或 `MaxValue` (increment < 0)。

## 另请参阅

Expand Down
4 changes: 2 additions & 2 deletions reference/sql/statements/drop-sequence.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ category: reference

# DROP SEQUENCE

`DROP SEQUENCE` 语句用于删除 SEQUENCE 对象
`DROP SEQUENCE` 语句用于删除序列对象

## 语法图

Expand Down Expand Up @@ -50,7 +50,7 @@ Query OK, 0 rows affected (0.03 sec)

## MySQL 兼容性

* MySQL 暂无 SEQUENCE 选项。TiDB Sequence 借鉴自 MariaDB,但是 setval 会保持原有的步调
MySQL 暂无序列选项。TiDB 序列借鉴自 MariaDB。`SETVAL` 函数的步调是 TiDB 特有的,其他函数的步调与 MariaDB 保持一致

## 另请参阅

Expand Down
4 changes: 2 additions & 2 deletions reference/sql/statements/show-create-sequence.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ category: reference

# SHOW CREATE SEQUENCE

`SHOW CREATE SEQUENCE` 语句用于查看一个 SEQUENCE 的详细信息,类似于 `SHOW CREATE TABLE` 语句。
`SHOW CREATE SEQUENCE` 语句用于查看一个序列的详细信息,类似于 `SHOW CREATE TABLE` 语句。

## 语法图

Expand Down Expand Up @@ -47,7 +47,7 @@ SHOW CREATE SEQUENCE seq;

## MySQL 兼容性

* MySQL 暂无 SEQUENCE 选项。TiDB Sequence 借鉴自 MariaDB,但是 setval 会保持原有的步调
MySQL 暂无序列选项。TiDB 序列借鉴自 MariaDB。`SETVAL` 函数的步调是 TiDB 特有的,其他函数的步调与 MariaDB 保持一致

## 另请参阅

Expand Down