OpenText Analytics Database 26.2.x – Sequences

Admin: Sequence types compared

Mon, 01 Jan 0001 00:00:00 +0000

The following table lists the differences between the two sequence types:

Supported Behavior	Named Sequence	IDENTITY
Default cache value 250K	•	•
Set initial cache	•	•
Define start value	•	•
Specify increment unit	•	•
Exists as an independent object	•
Exists only as part of table		•
Create as column constraint		•
Requires name	•
Use in expressions	•
Unique across tables	•
Change parameters	•
Move to different schema	•
Set to increment or decrement	•
Grant privileges to object	•
Specify minimum value	•
Specify maximum value	•

Admin: Named sequences

Mon, 01 Jan 0001 00:00:00 +0000

Named sequences are sequences that are defined by CREATE SEQUENCE. Unlike IDENTITY sequences, which are defined in a table's DDL, you create a named sequence as an independent object, and then set it as the default value of a table column.

Named sequences are used most often when an application requires a unique identifier in a table or an expression. After a named sequence returns a value, it never returns the same value again in the same session.

Admin: IDENTITY sequences

Mon, 01 Jan 0001 00:00:00 +0000

IDENTITY (synonymous with AUTO_INCREMENT) columns are defined with a sequence that automatically increments column values as new rows are added. You define an IDENTITY column in a table as follows:

CREATE TABLE table-name...
  (column-name {IDENTITY | AUTO_INCREMENT}
      ( [ cache-size | start, increment [, cache-size ] ] )

Settings

start

First value to set for this column.

Default: 1

increment

Positive or negative integer that specifies how much to increment or decrement the sequence on each new row insertion from the previous row value, by default set to 1. To decrement sequence values, specify a negative value.

Note

The actual amount by which column values are incremented or decremented might be larger than the increment setting, unless sequence caching is disabled.

Default: 1

cache-size

How many unique numbers each node caches per session. A value of 0 or 1 disables sequence caching. For details, see Sequence caching.

Default: 250,000

Managing settings

Like named sequences, you can manage an IDENTITY column with ALTER SEQUENCE—for example, reset its start integer. Two exceptions apply: because the sequence is defined as part of a table column, you cannot change the sequence name or schema. You can query the SEQUENCES system table for the name of an IDENTITY column's sequence. This name is automatically created when you define the table, and conforms to the following convention:

table-name_col-name_seq

For example, you can change the maximum value of an IDENTITY column that is defined in the testAutoId table:

=> SELECT * FROM sequences WHERE identity_table_name  = 'testAutoId';
-[ RECORD 1 ]-------+-------------------------
sequence_schema     | public
sequence_name       | testAutoId_autoIdCol_seq
owner_name          | dbadmin
identity_table_name | testAutoId
session_cache_count | 250000
allow_cycle         | f
output_ordered      | f
increment_by        | 1
minimum             | 1
maximum             | 1000
current_value       | 1
sequence_schema_id  | 45035996273704980
sequence_id         | 45035996274278950
owner_id            | 45035996273704962
identity_table_id   | 45035996274278948

=> ALTER SEQUENCE testAutoId_autoIdCol_seq maxvalue 10000;
ALTER SEQUENCE

This change, like other changes to a sequence, take effect only when you start a new database session. One exception applies: changes to the sequence owner take effect immediately.

You can obtain the last value generated for an IDENTITY column by calling LAST_INSERT_ID.

Restrictions

The following restrictions apply to IDENTITY columns:

A table can contain only one IDENTITY column.
IDENTITY column values automatically increment before the current transaction is committed; rolling back the transaction does not revert the change.
You cannot change the value of an IDENTITY column.

Examples

The following example shows how to use the IDENTITY column-constraint to create a table with an ID column. The ID column has an initial value of 1. It is incremented by 1 every time a row is inserted.

Create table Premium_Customer:

=> CREATE TABLE Premium_Customer(
     ID IDENTITY(1,1),
     lname VARCHAR(25),
     fname VARCHAR(25),
     store_membership_card INTEGER
);
=> INSERT INTO Premium_Customer (lname, fname, store_membership_card )
     VALUES ('Gupta', 'Saleem', 475987);

The IDENTITY column has a seed of 1, which specifies the value for the first row loaded into the table, and an increment of 1, which specifies the value that is added to the IDENTITY value of the previous row.

Confirm the row you added and see the ID value:

=> SELECT * FROM Premium_Customer;
 ID | lname | fname  | store_membership_card
----+-------+--------+-----------------------
  1 | Gupta | Saleem |                475987
(1 row)

Add another row:

=> INSERT INTO Premium_Customer (lname, fname, store_membership_card)
   VALUES ('Lee', 'Chen', 598742);

Call the function LAST_INSERT_ID. The function returns value 2 because you previously inserted a new customer (Chen Lee), and this value is incremented each time a row is inserted:
```
=> SELECT LAST_INSERT_ID();
 last_insert_id
----------------
               2
(1 row)
```

View all the ID values in the Premium_Customer table:

=> SELECT * FROM Premium_Customer;
 ID | lname | fname  | store_membership_card
----+-------+--------+-----------------------
  1 | Gupta | Saleem |                475987
  2 | Lee   | Chen   |                598742
(2 rows)

The next three examples illustrate the three valid ways to use IDENTITY arguments.

The first example uses a cache of 100, and the defaults for start value (1) and increment value (1):

=> CREATE TABLE t1(x IDENTITY(100), y INT);

The next example specifies the start and increment values as 1, and defaults to a cache value of 250,000:

=> CREATE TABLE t2(y IDENTITY(1,1), x INT);

The third example specifies start and increment values of 1, and a cache value of 100:

=> CREATE TABLE t3(z IDENTITY(1,1,100), zx INT);

Admin: Sequence caching

Mon, 01 Jan 0001 00:00:00 +0000

Caching is similar for all sequence types: named sequences and IDENTITY column sequences. To allocate cache among the nodes in a cluster for a given sequence, the database uses the following process.

By default, when a session begins, the cluster initiator node requests cache for itself and other nodes in the cluster.
The initiator node distributes cache to other nodes when it distributes the execution plan.
Because the initiator node requests caching for all nodes, only the initiator locks the global catalog for the cache request.

This approach is optimal for handling large INSERT-SELECT and COPY operations. The following figure shows how the initiator request and distributes cache for a named sequence in a three-node cluster, where caching for that sequence is set to 250 K:

Nodes run out of cache at different times. While executing the same query, nodes individually request additional cache as needed.

For new queries in the same session, the initiator might have an empty cache if it used all of its cache to execute the previous query execution. In this case, the initiator requests cache for all nodes.

Configuring sequence caching

You can change how nodes obtain sequence caches by setting the configuration parameter ClusterSequenceCacheMode to 0 (disabled). When this parameter is set to 0, all nodes in the cluster request their own cache and catalog lock. However, for initial large INSERT-SELECT and COPY operations, when the cache is empty for all nodes, each node requests cache at the same time. These multiple requests result in simultaneous locks on the global catalog, which can adversely affect performance. For this reason, ClusterSequenceCacheMode should remain set to its default value of 1 (enabled).

The following example compares how different settings of ClusterSequenceCacheMode affect how the database manages sequence caching. The example assumes a three-node cluster, 250 K caches for each node (the default), and sequence ID values that increment by 1.

Workflow step	ClusterSequenceCacheMode = 1	ClusterSequenceCacheMode = 0
1	Cache is empty for all nodes. Initiator node requests 250 K cache for each node.	Cache is empty for all nodes. Each node, including initiator, requests its own 250 K cache.
2	Blocks of cache are distributed to each node as follows: Node 1: 0–250 K Node 2: 250 K + 1 to 500 K Node 3: 500 K + 1 to 750 K Each node begins to use its cache as it processes sequence updates.
3	Initiator node and node 3 run out of cache. Node 2 only uses 250 K +1 to 400 K, 100 K of cache remains from 400 K +1 to 500 K.
4	Executing same statement: As each node uses up its cache, it requests a new cache allocation. If node 2 never uses its cache, the 100-K unused cache becomes a gap in sequence IDs. Executing a new statement in same session, if initiator node cache is empty: It requests and distributes new cache blocks for all nodes. Nodes receive a new cache before the old cache is used, creating a gap in ID sequencing.	Executing same or new statement: As each node uses up its cache, it requests a new cache allocation. If node 2 never uses its cache, the 100 K unused cache becomes a gap in sequence IDs.