From aa5cbe300124afcea681f2fcba97d712a1ee6bdf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Fri, 31 May 2024 15:40:04 +0200 Subject: [PATCH 1/6] Update sequence functions docs --- functions-and-operators/sequence-functions.md | 142 +++++++++++++++++- 1 file changed, 139 insertions(+), 3 deletions(-) diff --git a/functions-and-operators/sequence-functions.md b/functions-and-operators/sequence-functions.md index bbf14b6b2e624..0783ac807f56f 100644 --- a/functions-and-operators/sequence-functions.md +++ b/functions-and-operators/sequence-functions.md @@ -9,9 +9,145 @@ Sequence functions in TiDB are used to return or set values of sequence objects | 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 | +| [`NEXTVAL()`](#nextval) | Returns the next value of a sequence | +| [`NEXT VALUE FOR`](#next-value-for) | Returns the next value of a sequence | +| [`SETVAL()`](#setval) | Sets the current value of a sequence | +| [`LASTVAL()`](#lastval) | Returns the last used value of a sequence | + +## `NEXTVAL()` + +The `NEXTVAL()` functions returns the next value from the sequence + +Example: + +We create a sequence called `s1`. + +```sql +CREATE SEQUENCE s1; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +Then we request the next value from `s1`. + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 1 | ++-------------+ +1 row in set (0.00 sec) +``` +## `NEXT VALUE FOR` + +An alias for [`NEXTVAL()`](#nextval) + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 13 | ++-------------+ +1 row in set (0.00 sec) +``` + +```sql +SELECT NEXT VALUE FOR s1; +``` + +``` ++-------------------+ +| NEXT VALUE FOR s1 | ++-------------------+ +| 14 | ++-------------------+ +1 row in set (0.00 sec) +``` + +## `SETVAL()` + +The `SETVAL(n)` function can be use to set a sequence to a specific value. + +```sql +CREATE SEQUENCE s1; +``` + +``` +Query OK, 0 rows affected (0.01 sec) +``` + +Then we request the next value from `s1`. + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 1 | ++-------------+ +1 row in set (0.00 sec) +``` + +Now we set the value to `10`. + +```sql +SELECT SETVAL(s1, 10); +``` + +``` ++----------------+ +| SETVAL(s1, 10) | ++----------------+ +| 10 | ++----------------+ +1 row in set (0.00 sec) +``` + +And now we can see that the next value (the value after `10`) is `11`. + +```sql +SELECT NEXTVAL(s1); +``` + +``` ++-------------+ +| NEXTVAL(s1) | ++-------------+ +| 11 | ++-------------+ +1 row in set (0.00 sec) +``` + +## `LASTVAL()` + +The `LASTVAL()` function returns the last value that was generated by the sequence. + +```sql +SELECT LASTVAL(s1); +``` + +``` ++-------------+ +| LASTVAL(s1) | ++-------------+ +| 12 | ++-------------+ +1 row in set (0.00 sec) +``` + ## MySQL compatibility From a245997641ee9351cc86d2589b0edc246ba18b3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Sun, 2 Jun 2024 19:40:07 +0200 Subject: [PATCH 2/6] Fixes --- functions-and-operators/sequence-functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/functions-and-operators/sequence-functions.md b/functions-and-operators/sequence-functions.md index 0783ac807f56f..e04b9b26424b9 100644 --- a/functions-and-operators/sequence-functions.md +++ b/functions-and-operators/sequence-functions.md @@ -44,6 +44,7 @@ SELECT NEXTVAL(s1); +-------------+ 1 row in set (0.00 sec) ``` + ## `NEXT VALUE FOR` An alias for [`NEXTVAL()`](#nextval) @@ -148,7 +149,6 @@ SELECT LASTVAL(s1); 1 row in set (0.00 sec) ``` - ## 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). From 32bd22a3e9fbca4eab5087e71cda72ea52d449ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Mon, 3 Jun 2024 15:35:23 +0200 Subject: [PATCH 3/6] Update based on review --- functions-and-operators/sequence-functions.md | 20 ++++++------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/functions-and-operators/sequence-functions.md b/functions-and-operators/sequence-functions.md index e04b9b26424b9..a7268301a72f4 100644 --- a/functions-and-operators/sequence-functions.md +++ b/functions-and-operators/sequence-functions.md @@ -57,7 +57,7 @@ SELECT NEXTVAL(s1); +-------------+ | NEXTVAL(s1) | +-------------+ -| 13 | +| 2 | +-------------+ 1 row in set (0.00 sec) ``` @@ -70,7 +70,7 @@ SELECT NEXT VALUE FOR s1; +-------------------+ | NEXT VALUE FOR s1 | +-------------------+ -| 14 | +| 3 | +-------------------+ 1 row in set (0.00 sec) ``` @@ -79,15 +79,7 @@ SELECT NEXT VALUE FOR s1; The `SETVAL(n)` function can be use to set a sequence to a specific value. -```sql -CREATE SEQUENCE s1; -``` - -``` -Query OK, 0 rows affected (0.01 sec) -``` - -Then we request the next value from `s1`. +We request the next value from `s1`. ```sql SELECT NEXTVAL(s1); @@ -97,7 +89,7 @@ SELECT NEXTVAL(s1); +-------------+ | NEXTVAL(s1) | +-------------+ -| 1 | +| 4 | +-------------+ 1 row in set (0.00 sec) ``` @@ -134,7 +126,7 @@ SELECT NEXTVAL(s1); ## `LASTVAL()` -The `LASTVAL()` function returns the last value that was generated by the sequence. +The `LASTVAL()` function returns the last value that was generated by the sequence in **this session**. ```sql SELECT LASTVAL(s1); @@ -144,7 +136,7 @@ SELECT LASTVAL(s1); +-------------+ | LASTVAL(s1) | +-------------+ -| 12 | +| 11 | +-------------+ 1 row in set (0.00 sec) ``` From 0da159bb8bd151efe3ac70abecfd2698c50419ff Mon Sep 17 00:00:00 2001 From: Aolin Date: Fri, 7 Jun 2024 12:18:02 +0800 Subject: [PATCH 4/6] Sequence functions: refine wording --- functions-and-operators/sequence-functions.md | 58 +++++++++++++------ 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/functions-and-operators/sequence-functions.md b/functions-and-operators/sequence-functions.md index a7268301a72f4..1618c6d7921db 100644 --- a/functions-and-operators/sequence-functions.md +++ b/functions-and-operators/sequence-functions.md @@ -7,35 +7,33 @@ summary: This document introduces sequence functions supported in TiDB. 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 | +| Function name | Description | | :-------------- | :------------------------------------- | -| [`NEXTVAL()`](#nextval) | Returns the next value of a sequence | -| [`NEXT VALUE FOR`](#next-value-for) | Returns the next value of a sequence | -| [`SETVAL()`](#setval) | Sets the current value of a sequence | -| [`LASTVAL()`](#lastval) | Returns the last used value of a sequence | +| [`NEXTVAL()`](#nextval) | Returns the next value of a sequence. | +| [`NEXT VALUE FOR`](#next-value-for) | Returns the next value of a sequence (alias for `NEXTVAL()`). | +| [`SETVAL()`](#setval) | Sets the current value of a sequence. | +| [`LASTVAL()`](#lastval) | Returns the last used value of a sequence in the current session. | ## `NEXTVAL()` -The `NEXTVAL()` functions returns the next value from the sequence +The `NEXTVAL()` function returns the next value of a sequence. Example: -We create a sequence called `s1`. +Create a sequence named `s1`: ```sql CREATE SEQUENCE s1; ``` -``` -Query OK, 0 rows affected (0.01 sec) -``` - -Then we request the next value from `s1`. +Get the next value from `s1`: ```sql SELECT NEXTVAL(s1); ``` +The output is as follows: + ``` +-------------+ | NEXTVAL(s1) | @@ -47,12 +45,18 @@ SELECT NEXTVAL(s1); ## `NEXT VALUE FOR` -An alias for [`NEXTVAL()`](#nextval) +The `NEXT VALUE FOR` function is an alias for [`NEXTVAL()`](#nextval). + +Example: + +Get the next value from `s1` using `NEXTVAL()`: ```sql SELECT NEXTVAL(s1); ``` +The output is as follows: + ``` +-------------+ | NEXTVAL(s1) | @@ -62,10 +66,14 @@ SELECT NEXTVAL(s1); 1 row in set (0.00 sec) ``` +Get the next value from `s1` using `NEXT VALUE FOR`: + ```sql SELECT NEXT VALUE FOR s1; ``` +The output is as follows: + ``` +-------------------+ | NEXT VALUE FOR s1 | @@ -77,14 +85,18 @@ SELECT NEXT VALUE FOR s1; ## `SETVAL()` -The `SETVAL(n)` function can be use to set a sequence to a specific value. +The `SETVAL(n)` function sets the current value of a sequence. -We request the next value from `s1`. +Example: + +Get the next value from `s1`: ```sql SELECT NEXTVAL(s1); ``` +The output is as follows: + ``` +-------------+ | NEXTVAL(s1) | @@ -94,12 +106,14 @@ SELECT NEXTVAL(s1); 1 row in set (0.00 sec) ``` -Now we set the value to `10`. +Set the current value of `s1` to `10`: ```sql SELECT SETVAL(s1, 10); ``` +The output is as follows: + ``` +----------------+ | SETVAL(s1, 10) | @@ -109,12 +123,14 @@ SELECT SETVAL(s1, 10); 1 row in set (0.00 sec) ``` -And now we can see that the next value (the value after `10`) is `11`. +Verify the next value after setting it to `10`: ```sql SELECT NEXTVAL(s1); ``` +The output is as follows: + ``` +-------------+ | NEXTVAL(s1) | @@ -126,12 +142,18 @@ SELECT NEXTVAL(s1); ## `LASTVAL()` -The `LASTVAL()` function returns the last value that was generated by the sequence in **this session**. +The `LASTVAL()` function returns the last value generated by the sequence **in the current session**. + +Example: + +Get the next value from `s1`: ```sql SELECT LASTVAL(s1); ``` +The output is as follows: + ``` +-------------+ | LASTVAL(s1) | From 374a78717b2846fabf23e8f28ba0324c3a7cf63d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Tue, 11 Jun 2024 10:26:37 +0200 Subject: [PATCH 5/6] Update functions-and-operators/sequence-functions.md Co-authored-by: Aolin --- functions-and-operators/sequence-functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/functions-and-operators/sequence-functions.md b/functions-and-operators/sequence-functions.md index 1618c6d7921db..610fec39e9b6a 100644 --- a/functions-and-operators/sequence-functions.md +++ b/functions-and-operators/sequence-functions.md @@ -146,7 +146,7 @@ The `LASTVAL()` function returns the last value generated by the sequence **in t Example: -Get the next value from `s1`: +Get the last value generated by `s1` in the current session: ```sql SELECT LASTVAL(s1); From 01824c606626af696294ebf8380d42719a8b2637 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Fri, 14 Jun 2024 11:20:33 +0200 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Grace Cai --- functions-and-operators/sequence-functions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/functions-and-operators/sequence-functions.md b/functions-and-operators/sequence-functions.md index 610fec39e9b6a..f610a982f1719 100644 --- a/functions-and-operators/sequence-functions.md +++ b/functions-and-operators/sequence-functions.md @@ -12,7 +12,7 @@ Sequence functions in TiDB are used to return or set values of sequence objects | [`NEXTVAL()`](#nextval) | Returns the next value of a sequence. | | [`NEXT VALUE FOR`](#next-value-for) | Returns the next value of a sequence (alias for `NEXTVAL()`). | | [`SETVAL()`](#setval) | Sets the current value of a sequence. | -| [`LASTVAL()`](#lastval) | Returns the last used value of a sequence in the current session. | +| [`LASTVAL()`](#lastval) | Returns the last value generated by a sequence in the current session. | ## `NEXTVAL()` @@ -142,7 +142,7 @@ The output is as follows: ## `LASTVAL()` -The `LASTVAL()` function returns the last value generated by the sequence **in the current session**. +The `LASTVAL()` function returns the last value generated by a sequence **in the current session**. Example: