SEQUENCE函数

nextval(regclass)

描述：递增序列并返回新值。

• 为了避免从同一个序列获取值的并发事务被阻塞， nextval操作不会回滚。即一旦值被获取，认为该值已被使用，且不会再被返回。 即使该操作处于事务中，当事务之后中断，或者如果调用查询结束不使用该值，也是如此。这种情况将在指定值的顺序中留下未使用的“空洞”。 因此，GaussDB序列对象不能用于获得“无间隙”序列。
• 如果nextval被下推到DN上时，各个DN会自动连接GTM，请求next values值，例如（INSERT INTO t1 SELECT xxx，t1某一列需要调用nextval函数），由于GTM上有最大连接数为8192的限制，而这类下推语句会导致消耗过多的GTM连接数，因此对于这类语句的并发数目限制为7000（其它语句需要占用部分连接）/集群DN数目。

• 如果插入语句中同时包含SRF（Set-Retruning-Functions）函数和序列自增列，则序列的值会跳数一位。SRF函数以generate_series为例：

  CREATE TABLE t1 (a int, b serial);
  INSERT INTO t1(a) VALUES(generate_series(1,1)); -- 插入数据b列为1
  INSERT INTO t1(a) VALUES(generate_series(1,1));  -- 插入数据b列为3，跳号2

返回类型：numeric

nextval函数有两种调用方式（其中第二种调用方式兼容ORA的语法，目前不支持Sequence命名中有特殊字符"."的情况），如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

gaussdb=# CREATE SEQUENCE seqDemo;

--示例1：
gaussdb=# SELECT nextval('seqDemo'); 
 nextval
---------
       1
(1 row)

--示例2：
gaussdb=# SELECT seqDemo.nextval; 
 nextval
---------
       2
(1 row)
gaussdb=# DROP SEQUENCE seqDemo;

currval(regclass)

描述：返回当前会话中最近一次nextval返回的数值。如果当前会话还没有调用过指定的sequence的nextval，那么调用currval将会报错。

需要注意的是，该函数在默认情况下是不支持的，需要通过设置enable_beta_features为true之后，才能使用该函数。同时在设置enable_beta_features为true之后，nextval()函数将不支持下推。

返回类型：numeric

currval函数有两种调用方式（其中第二种调用方式兼容ORA的语法，目前不支持Sequence命名中有特殊字符"."的情况），如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

gaussdb=# CREATE SEQUENCE seq1;
gaussdb=# SELECT nextval('seq1'); 
gaussdb=# SET enable_beta_features = true;

--示例1：
gaussdb=# SELECT currval('seq1'); 
 currval
---------
       1
(1 row)

--示例2：
gaussdb=# SELECT seq1.currval seq1; 
 seq1
------
    1
(1 row)
gaussdb=# DROP SEQUENCE seq1;
gaussdb=# SET enable_beta_features = false;

lastval()

描述：返回当前会话里最近一次nextval返回的数值。该函数等效于currval，但无需将序列名为参数，它会获取当前会话中最近一次nextval使用的序列。如果当前会话尚未调用过nextval，则调用lastval将会报错。

需要注意的是，该函数在默认情况下是不支持的，需要通过设置enable_beta_features或者lastval_supported为true之后，才能使用。同时这种情况下，nextval()函数将不支持下推。

返回类型：numeric

示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

gaussdb=# CREATE SEQUENCE seq1;
gaussdb=# SELECT nextval('seq1'); 
gaussdb=# SET enable_beta_features = true;
gaussdb=# SELECT lastval(); 
 lastval
---------
       1
(1 row)
gaussdb=# DROP SEQUENCE seq1;
gaussdb=# SET enable_beta_features = false;

setval(regclass, bigint)

描述：设置序列的当前数值。

返回类型：numeric

示例：

1
2
3
4
5
6
7
8

gaussdb=# CREATE SEQUENCE seqDemo;
gaussdb=# SELECT nextval('seqDemo'); 
gaussdb=# SELECT setval('seqDemo',3);
 setval
--------
      3
(1 row)
gaussdb=# DROP SEQUENCE seqDemo;

setval(regclass, numeric, Boolean)

描述：设置序列的当前数值以及is_called标志。

返回类型：numeric

示例：

1
2
3
4
5
6
7
8

gaussdb=# CREATE SEQUENCE seqDemo;
gaussdb=# SELECT nextval('seqDemo'); 
gaussdb=# SELECT setval('seqDemo',5,true);
 setval
--------
      5
(1 row)
gaussdb=# DROP SEQUENCE seqDemo;

执行setval函数后当前会话及GTM上的序列值会立刻生效，但如果其他会话有缓存的序列值，只能等到缓存值用尽后，才能感知setval函数的作用。因此，为了避免序列值冲突，使用setval函数时应谨慎。由于序列是非事务的，使用setval函数造成的改变不会因事务的回滚而撤销。

pg_sequence_last_value(sequence_oid oid, OUT cache_value int16, OUT last_value int16)

描述：获取指定sequence的参数，包含缓存值和当前值。

返回类型：int16、int16

gs_get_sequence_parameters(sequence_oid)

描述：获取指定sequence的参数，包含起始值、最小值、最大值和递增值等。

返回类型：int16、int16、int16、int16、Boolean

gs_get_sequence_last_value(sequence_oid oid, OUT cache_value int16, OUT last_value int16)

描述：获取指定sequence的参数，包含缓存值以及当前值。

返回类型：int16、int16

get_global_last_value_from_gtm(sequence_regclass regclass, OUT is_called boolean, OUT last_value numeric)

描述：从GTM获取序列是否调用过的标记位和已申请的序列最新值。

参数：表示待查询序列的序列名或OID。

返回类型：Boolean、numeric

• 从不支持get_global_last_value_from_gtm的版本升级到支持get_global_last_value_from_gtm的版本时，在升级观察期期间，不可使用此函数。
• get_global_last_value_from_gtm函数每次调用都需要与GTM进行通信，不建议频繁执行。
• 序列已申请的最新值，不一定表示已使用的最大值。如果序列的cache大于1，且节点申请的序列值没有用完，这种情况将会留下未使用的“空洞”。