9.17. シーケンス操作関数

PostgreSQL 13.1文書
		第9章関数と演算子
前へ	上へ	9.17. シーケンス操作関数	次へ

本節ではシーケンスオブジェクトに対し演算を行う関数について説明します。シーケンスオブジェクトは、シーケンスジェネレータ、あるいは単にシーケンスとも呼ばれます。シーケンスオブジェクトは特殊な一行だけのテーブルで、CREATE SEQUENCEで作成されます。シーケンスオブジェクトは一般的にテーブルの行に一意の識別子を生成するために使用されます。表 9.50に列挙されているシーケンス関数は、シーケンスオブジェクトから連続したシーケンス値を取得するための、簡易でマルチユーザに対応した関数です。

表9.50 シーケンス関数

関数説明
`nextval` ( `regclass` ) → `bigint` シーケンスを次の値に進めてその値を返します。これは自動的に行われます。複数のセッションが`nextval`を同時に実行しても、各々のシーケンスは異なったシーケンス値を安全に返します。シーケンスオブジェクトがデフォルト値を伴って作成されると、後続の`nextval`呼び出しは1から始まる次の値を返します。それ以外の動作は適切なパラメータをCREATE SEQUENCEコマンドで使うことによって得られます。この関数はシーケンスオブジェクトの`USAGE`あるいは`UPDATE`権限が必要です。
`setval` ( `regclass`, `bigint` [, `boolean` ] ) → `bigint` シーケンスオブジェクトの現在の値をセットします。オプションで`is_called`をセットします。 2つのパラメータを持つ形式では、シーケンスの`last_value`フィールドを指定した値にセットし、`is_called`フィールドを`true`に設定します。これは次の`nextval`が値を返す前にシーケンスを増分することを意味します。 `currval`で報告される値も指定した値に設定されます。 3つのパラメータを持つ形式では、`is_called`は`true`あるいは`false`に設定されます。 `true`は2つのパラメータを持つ形式と同じ効果を持ちます。 `false`に設定されていると、次の`nextval`はまさに指定した値を返し、後続の`nextval`がシーケンスの増加を開始します。更に、この場合は`currval`が報告する値は変化しません。たとえば次ようになります。 SELECT setval('myseq', 42); 次の`nextval`は43を返す SELECT setval('myseq', 42, true); 同上 SELECT setval('myseq', 42, false); 次の`nextval`は42を返す `setval`が返した値はその2番目の引数と単に同じです。この関数はシーケンスの`UPDATE`権限が必要です。
`currval` ( `regclass` ) → `bigint` 現在のセッションでこのシーケンスに対して直近の`nextval`によって得られた値を返します。（このセッションで`nextval`が呼ばれていなければエラーが報告されます。）これはセッションローカルな値を返すので、他のセッションが`nextval`を呼び出したかどうかに関わらず予測可能な値を返します。この関数はシーケンスの`USAGE`あるいは`SELECT`権限が必要です。
`lastval` () → `bigint` 現在のセッションでこのシーケンスに対して直近の`nextval`によって得られた値を返します。この関数は、現在のセッションで`nextval`が直近に適用されたシーケンス名を参照する引数を取ることを除き、`currval`と同じです。このセッションで`nextval`が呼ばれていないのに`lastval`を呼び出すのはエラーです。この関数はシーケンスの`USAGE`あるいは`SELECT`権限が必要です。

関数

説明

nextval ( regclass ) → bigint

シーケンスを次の値に進めてその値を返します。これは自動的に行われます。複数のセッションがnextvalを同時に実行しても、各々のシーケンスは異なったシーケンス値を安全に返します。シーケンスオブジェクトがデフォルト値を伴って作成されると、後続のnextval呼び出しは1から始まる次の値を返します。それ以外の動作は適切なパラメータをCREATE SEQUENCEコマンドで使うことによって得られます。

この関数はシーケンスオブジェクトのUSAGEあるいはUPDATE権限が必要です。

setval ( regclass, bigint [, boolean ] ) → bigint

シーケンスオブジェクトの現在の値をセットします。オプションでis_calledをセットします。 2つのパラメータを持つ形式では、シーケンスのlast_valueフィールドを指定した値にセットし、is_calledフィールドをtrueに設定します。これは次のnextvalが値を返す前にシーケンスを増分することを意味します。 currvalで報告される値も指定した値に設定されます。 3つのパラメータを持つ形式では、is_calledはtrueあるいはfalseに設定されます。 trueは2つのパラメータを持つ形式と同じ効果を持ちます。 falseに設定されていると、次のnextvalはまさに指定した値を返し、後続のnextvalがシーケンスの増加を開始します。更に、この場合はcurrvalが報告する値は変化しません。たとえば次ようになります。

SELECT setval('myseq', 42);           次のnextvalは43を返す
SELECT setval('myseq', 42, true);     同上
SELECT setval('myseq', 42, false);    次のnextvalは42を返す

setvalが返した値はその2番目の引数と単に同じです。

この関数はシーケンスのUPDATE権限が必要です。

currval ( regclass ) → bigint

現在のセッションでこのシーケンスに対して直近のnextvalによって得られた値を返します。（このセッションでnextvalが呼ばれていなければエラーが報告されます。）これはセッションローカルな値を返すので、他のセッションがnextvalを呼び出したかどうかに関わらず予測可能な値を返します。

この関数はシーケンスのUSAGEあるいはSELECT権限が必要です。

lastval () → bigint

現在のセッションでこのシーケンスに対して直近のnextvalによって得られた値を返します。この関数は、現在のセッションでnextvalが直近に適用されたシーケンス名を参照する引数を取ることを除き、currvalと同じです。このセッションでnextvalが呼ばれていないのにlastvalを呼び出すのはエラーです。

この関数はシーケンスのUSAGEあるいはSELECT権限が必要です。

注意

同一のシーケンスから数値を取得する同時実行トランザクション同士のブロックを防止するため、nextval演算は決してロールバックされません。つまり、値が一度取り出されたら、それは使用されたものと見なされ、同じ値が再び返されることはありません。これは、それを取り囲むトランザクションが後にアボートした場合でも、あるいは呼び出し側の問い合わせがその値を使用せずに終わった場合でも当てはまります。例えばON CONFLICT句のあるINSERTでは、挿入される予定のタプルについて、必要となるすべてのnextvalの呼び出しも含めて計算し、その後でON CONFLICTのルールを代わりに使用することになる競合について検知します。このような場合には、割り当てられた値のシーケンス内に未使用の「欠損」を残すことになります。従って、PostgreSQLのシーケンスオブジェクトは「欠番のない」シーケンスを得るために使うことはできません。

同様に、setvalが行ったシーケンス状態の変更はトランザクションがロールバックしても元には戻りません。

シーケンス関数により操作されるシーケンスはregclass引数で指定されますが、それはpg_classシステムカタログ内にある、そのシーケンスの単なるOIDです。しかしながら、手作業でOIDを検索する必要はなく、regclassデータ型の入力変換器が代わってその作業を行ってくれます。単一引用符で括られたシーケンス名を記述するだけで良いので、リテラル定数のように見えます。通常のSQLの名称での操作との互換のため、文字列はシーケンス名が二重引用符で括られていなければ、小文字に変換されます。よって、以下のようになります。

nextval('foo')      シーケンスfooの操作
nextval('FOO')      シーケンスfooの操作
nextval('"Foo"')    シーケンスFooの操作

必要であれば、以下のようにシーケンス名をスキーマで修飾することができます。

nextval('myschema.foo')     myschema.fooの操作
nextval('"myschema".foo')   上と同じ
nextval('foo')              fooを検索パスで探す

regclassに関してのより詳細な情報は8.19を参照してください。

注記

PostgreSQLの8.1より前においては、シーケンス関数の引数はregclass型ではなく、text型で、そして上記のテキスト文字列からOID値への変換はそれぞれの呼び出し実行時に起こりました。後方互換性のため、この仕組みはまだ存在しますが、内部的には関数が実行される前にtextからregclassへの暗黙的強制型変換として現在処理されています。

ありのままのリテラル文字列としてシーケンス関数の引数を記述すると、regclassデータ型の定数になります。これは単なるOIDなので、後で名前付けが再び行われたとか、スキーマの再割り振りとかに関わらず、最初に特定されたシーケンスを引き継ぎます。この「初期束縛」の動作は、列のデフォルトやビューからシーケンスを参照する場合は望ましいことが多いでしょう。しかし、実行時にシーケンス参照が解決されるような「動的束縛」が望まれる場合もあります。動的束縛の動作を得るには、その定数をregclassではなくtext定数として保存させます。

nextval('foo'::text)      fooは実行時に検索される

PostgreSQLのリリース8.1より前では動的束縛のみがサポートされる動作だったので、旧来のアプリケーションのセマンティクスを保ちたい場合このようにする必要があるかもしれません。

もちろん、シーケンス関数の引数は定数だけでなく、評価式とすることも可能です。テキスト式の場合は暗黙的型変換により、実行時検索が行われます。

前へ	上へ	次へ
9.16. JSON関数と演算子	ホーム	9.18. 条件式