Sequences

type

sequence

sequence

Auto-incrementing sequence of int64.

This type can be used to create auto-incrementing properties.

scalar type TicketNo extending sequence;
type Ticket {
    property number -> TicketNo {
        constraint exclusive;
    }
}

The sequence is bound to the scalar type, not to the property, so if multiple properties use the same sequence type they will share the same counter. For each distinct counter, a separate scalar type that is extending sequence should be used.

function

sequence_next()

std::sequence_next(seq: schema::ScalarType) -> int64

Advance the sequence to its next value and return that value.

Sequence advancement is done atomically, each concurrent session and transaction will receive a distinct sequence value.

db>

select sequence_next(introspect MySequence);

{11}

function

sequence_reset()

std::sequence_reset(seq: schema::ScalarType) -> int64std::sequence_reset( seq: schema::ScalarType, val: int64) -> int64

Reset the sequence to its initial state or the specified value.

The single-parameter form resets the sequence to its initial state, where the next sequence_next() call will return the first value in sequence. The two-parameters form allows changing the last returned value of the sequence.

db>

select sequence_reset(introspect MySequence);

{1}

db>

select sequence_next(introspect MySequence);

{1}

db>

select sequence_reset(introspect MySequence, 22);

{22}

db>

select sequence_next(introspect MySequence);

{23}

The sequence to be operated on by the functions above is specified by a schema::ScalarType object. If the sequence argument is known ahead of time and does not change, the recommended way to pass it is to use the introspect operator:

select sequence_next(introspect MySequenceType);
# or
select sequence_next(introspect typeof MyObj.seq_prop);

This style will ensure that a reference to a sequence type from an expression is tracked properly to ensure schema referential integrity.

If, on the other hand, the operated sequence type is determined at run time via a query argument, it must be queried from the schema::ScalarType set directly like so:

with
  SeqType := (
    select schema::ScalarType
    filter .name = <str>$seq_type_name
  )
select
  sequence_next(SeqType);

Caution

To work efficiently in high concurrency without lock contention, a sequence_next() operation is never rolled back even if the containing transaction is aborted. This may result in gaps in the generated sequence. Likewise, sequence_reset() is not undone if the transaction is rolled back.