diff --git a/TOC-tidb-cloud.md b/TOC-tidb-cloud.md index 1dbb4039cdf8f..ad9d9236610f3 100644 --- a/TOC-tidb-cloud.md +++ b/TOC-tidb-cloud.md @@ -365,6 +365,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) @@ -518,6 +519,7 @@ - [Miscellaneous Functions](/functions-and-operators/miscellaneous-functions.md) - [Precision Math](/functions-and-operators/precision-math.md) - [Set Operations](/functions-and-operators/set-operators.md) + - [Sequence Functions](/functions-and-operators/sequence-functions.md) - [List of Expressions for Pushdown](/functions-and-operators/expressions-pushed-down.md) - [TiDB Specific Functions](/functions-and-operators/tidb-functions.md) - [Clustered Indexes](/clustered-indexes.md) diff --git a/TOC.md b/TOC.md index 8ce3db5a96be6..24fe80beb3d86 100644 --- a/TOC.md +++ b/TOC.md @@ -729,6 +729,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) @@ -889,6 +890,7 @@ - [Miscellaneous Functions](/functions-and-operators/miscellaneous-functions.md) - [Precision Math](/functions-and-operators/precision-math.md) - [Set Operations](/functions-and-operators/set-operators.md) + - [Sequence Functions](/functions-and-operators/sequence-functions.md) - [List of Expressions for Pushdown](/functions-and-operators/expressions-pushed-down.md) - [TiDB Specific Functions](/functions-and-operators/tidb-functions.md) - [Comparisons between Functions and Syntax of Oracle and TiDB](/oracle-functions-to-tidb.md) diff --git a/error-codes.md b/error-codes.md index af48638d829eb..35f591c0c300d 100644 --- a/error-codes.md +++ b/error-codes.md @@ -463,7 +463,7 @@ TiDB is compatible with the error codes in MySQL, and in most cases returns the * Error Number: 8228 - Unsupported types are specified when using `setval` on Sequence. + Unsupported types are specified when using `SETVAL` on Sequence. See [Sequence documentation](/sql-statements/sql-statement-create-sequence.md#examples) to find the example of the function. diff --git a/functions-and-operators/sequence-functions.md b/functions-and-operators/sequence-functions.md new file mode 100644 index 0000000000000..bbf14b6b2e624 --- /dev/null +++ b/functions-and-operators/sequence-functions.md @@ -0,0 +1,18 @@ +--- +title: Sequence Functions +summary: This document introduces sequence functions supported in TiDB. +--- + +# Sequence Functions + +Sequence functions in TiDB are used to return or set values of sequence objects created using the [`CREATE SEQUENCE`](/sql-statements/sql-statement-create-sequence.md) statement. + +| Function name | Feature description | +| :-------------- | :------------------------------------- | +| `NEXTVAL()` or `NEXT VALUE FOR` | Returns the next value of a sequence | +| `SETVAL()` | Sets the current value of a sequence | +| `LASTVAL()` | Returns the last used value of a sequence | + +## MySQL compatibility + +MySQL does not support the functions and statements for creating and manipulating sequences as defined in [ISO/IEC 9075-2](https://www.iso.org/standard/76584.html). diff --git a/information-schema/information-schema-sequences.md b/information-schema/information-schema-sequences.md index 60a0cb408e2ff..f7e92db6ae99a 100644 --- a/information-schema/information-schema-sequences.md +++ b/information-schema/information-schema-sequences.md @@ -37,7 +37,7 @@ Create a sequence `test.seq` and query the next value of the sequence: ```sql CREATE SEQUENCE test.seq; -SELECT nextval(test.seq); +SELECT NEXTVAL(test.seq); SELECT * FROM sequences\G ``` @@ -45,7 +45,7 @@ The output is as follows: ```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 0000000000000..72f896d467876 --- /dev/null +++ b/sql-statements/sql-statement-alter-sequence.md @@ -0,0 +1,215 @@ +--- +title: ALTER SEQUENCE +summary: An overview of the usage of ALTER SEQUENCE for the TiDB database. +--- + +# ALTER SEQUENCE + +The `ALTER SEQUENCE` statement alters sequence objects in TiDB. The sequence is a database object that is on a par with the `Table` and the `View` object. The sequence is used to generate serialized IDs in a customized way. + +## Synopsis + +```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 )? +``` + +## Syntax + +```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] +``` + +## Parameters + +|Parameters | Default value | Description | +| :-- | :-- | :--| +| `INCREMENT` | `1` | Specifies the increment of a sequence. Its positive or negative values can control the growth direction of the sequence. | +| `MINVALUE` | `1` or `-9223372036854775807` | Specifies the minimum value of a sequence. When `INCREMENT` > `0`, the default value is `1`. When `INCREMENT` < `0`, the default value is `-9223372036854775807`. | +| `MAXVALUE` | `9223372036854775806` or `-1` | Specifies the maximum value of a sequence. When `INCREMENT` > `0`, the default value is `9223372036854775806`. When `INCREMENT` < `0`, the default value is `-1`. | +| `START` | `MINVALUE` or `MAXVALUE`| Specifies the initial value of a sequence. When `INCREMENT` > `0`, the default value is `MINVALUE`. When `INCREMENT` < `0`, the default value is `MAXVALUE`. | +| `CACHE` | `1000` | Specifies the local cache size of a sequence in TiDB. | +| `CYCLE` | `NO CYCLE` | Specifies whether a sequence restarts from the minimum value (or maximum for the descending sequence). When `INCREMENT` > `0`, the default value is `MINVALUE`. When `INCREMENT` < `0`, the default value is `MAXVALUE`. | + +> **Note:** +> +> Changing the `START` value does not affect the generated values until you execute `ALTER SEQUENCE ... RESTART`. + +## `SEQUENCE` function + +You can control a sequence through the following expression functions: + ++ `NEXTVAL` or `NEXT VALUE FOR` + + Essentially, both are the `NEXTVAL()` function that gets the next valid value of a sequence object. The parameter of the `NEXTVAL()` function is the `identifier` of the sequence. + ++ `LASTVAL` + + This function gets the last used value of this session. If the value does not exist, `NULL` is used. The parameter of this function is the `identifier` of the sequence. + ++ `SETVAL` + + This function sets the progression of the current value for a sequence. The first parameter of this function is the `identifier` of the sequence; the second parameter is `num`. + +> **Note:** +> +> In the implementation of a sequence in TiDB, the `SETVAL` function cannot change the initial progression or cycle progression of this sequence. This function only returns the next valid value based on this progression. + +## Examples + +Create a sequence named `s1`: + +```sql +CREATE SEQUENCE s1; +``` + +``` +Query OK, 0 rows affected (0.15 sec) +``` + +Get the next two values from the sequence by executing the following SQL statement twice: + +```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) +``` + +Change the increment of the sequence to `2`: + +```sql +ALTER SEQUENCE s1 INCREMENT=2; +``` + +``` +Query OK, 0 rows affected (0.18 sec) +``` + +Now, get the next two values from the sequence again: + +```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) +``` + +As you can see from the output, the values now increase by two, following the `ALTER SEQUENCE` statement. + +You can also change other parameters of the sequence. For example, you can change the `MAXVALUE` of the sequence as follows: + +```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 compatibility + +This statement is a TiDB extension. The implementation is modeled on sequences available in MariaDB. + +Except for the `SETVAL` function, all other functions have the same _progressions_ as MariaDB. Here "progression" means that the numbers in a sequence follow a certain arithmetic progression rule defined by the sequence. Although you can use `SETVAL` to set the current value of a sequence, the subsequent values of the sequence still follow the original progression rule. + +For example: + +``` +1, 3, 5, ... // The sequence starts from 1 and increments by 2. +SELECT SETVAL(seq, 6) // Sets the current value of a sequence to 6. +7, 9, 11, ... // Subsequent values still follow the progression rule. +``` + +In the `CYCLE` mode, the initial value of a sequence in the first round is the value of the `START` parameter, and the initial value in the subsequent rounds is the value of `MinValue` (`INCREMENT` > 0) or `MaxValue` (`INCREMENT` < 0). + +## See also + +* [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 46b02cfa9128e..9d482399a82b5 100644 --- a/sql-statements/sql-statement-create-sequence.md +++ b/sql-statements/sql-statement-create-sequence.md @@ -11,7 +11,7 @@ The `CREATE SEQUENCE` statement creates sequence objects in TiDB. The sequence i ```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,7 +69,7 @@ You can control a sequence through the following expression functions: + `NEXTVAL` or `NEXT VALUE FOR` - Essentially, both are the `nextval()` function that gets the next valid value of a sequence object. The parameter of the `nextval()` function is the `identifier` of the sequence. + Essentially, both are the `NEXTVAL()` function that gets the next valid value of a sequence object. The parameter of the `NEXTVAL()` function is the `identifier` of the sequence. + `LASTVAL` @@ -96,51 +97,51 @@ You can control a sequence through the following expression functions: Query OK, 0 rows affected (0.06 sec) ``` -+ Use the `nextval()` function to get the next value of the sequence object: ++ Use the `NEXTVAL()` function to get the next value of the sequence object: {{< copyable "sql" >}} ```sql - SELECT nextval(seq); + SELECT NEXTVAL(seq); ``` ``` +--------------+ - | nextval(seq) | + | NEXTVAL(seq) | +--------------+ | 1 | +--------------+ 1 row in set (0.02 sec) ``` -+ Use the `lastval()` function to get the value generated by the last call to a sequence object in this session: ++ Use the `LASTVAL()` function to get the value generated by the last call to a sequence object in this session: {{< copyable "sql" >}} ```sql - SELECT lastval(seq); + SELECT LASTVAL(seq); ``` ``` +--------------+ - | lastval(seq) | + | LASTVAL(seq) | +--------------+ | 1 | +--------------+ 1 row in set (0.02 sec) ``` -+ Use the `setval()` function to set the current value (or the current position) of the sequence object: ++ Use the `SETVAL()` function to set the current value (or the current position) of the sequence object: {{< copyable "sql" >}} ```sql - SELECT setval(seq, 10); + SELECT SETVAL(seq, 10); ``` ``` +-----------------+ - | setval(seq, 10) | + | SETVAL(seq, 10) | +-----------------+ | 10 | +-----------------+ @@ -176,58 +177,58 @@ You can control a sequence through the following expression functions: Query OK, 0 rows affected (0.01 sec) ``` -+ When the sequence object has not been used in this session, the `lastval()` function returns a `NULL` value. ++ When the sequence object has not been used in this session, the `LASTVAL()` function returns a `NULL` value. {{< copyable "sql" >}} ```sql - SELECT lastval(seq2); + SELECT LASTVAL(seq2); ``` ``` +---------------+ - | lastval(seq2) | + | LASTVAL(seq2) | +---------------+ | NULL | +---------------+ 1 row in set (0.01 sec) ``` -+ The first valid value of the `nextval()` function for the sequence object is the value of `START` parameter. ++ The first valid value of the `NEXTVAL()` function for the sequence object is the value of `START` parameter. {{< copyable "sql" >}} ```sql - SELECT nextval(seq2); + SELECT NEXTVAL(seq2); ``` ``` +---------------+ - | nextval(seq2) | + | NEXTVAL(seq2) | +---------------+ | 3 | +---------------+ 1 row in set (0.00 sec) ``` -+ Although the `setval()` function can change the current value of the sequence object, it cannot change the arithmetic progression rule for the next value. ++ Although the `SETVAL()` function can change the current value of the sequence object, it cannot change the arithmetic progression rule for the next value. {{< 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) ``` -+ When you use `nextval()` to get the next value, the next value will follow the arithmetic progression rule defined by the sequence. ++ When you use `NEXTVAL()` to get the next value, the next value will follow the arithmetic progression rule defined by the sequence. {{< copyable "sql" >}} @@ -305,7 +306,7 @@ For example: ``` 1, 3, 5, ... // The sequence starts from 1 and increments by 2. -select setval(seq, 6) // Sets the current value of a sequence to 6. +select SETVAL(seq, 6) // Sets the current value of a sequence to 6. 7, 9, 11, ... // Subsequent values still follow the progression rule. ``` @@ -313,5 +314,7 @@ In the `CYCLE` mode, the initial value of a sequence in the first round is the v ## See also +* [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](/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 130a4fa7a572e..b5f944a6f0bce 100644 --- a/sql-statements/sql-statement-drop-sequence.md +++ b/sql-statements/sql-statement-drop-sequence.md @@ -51,4 +51,5 @@ This statement is a TiDB extension. The implementation is modeled on sequences a ## See also * [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 ac5004146a6c8..74792e4edecd1 100644 --- a/sql-statements/sql-statement-show-create-sequence.md +++ b/sql-statements/sql-statement-show-create-sequence.md @@ -51,4 +51,5 @@ This statement is a TiDB extension. The implementation is modeled on sequences a ## See also * [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)