9.17. シーケンス操作関数

PostgreSQL 16.0文書
		第9章関数と演算子	誤訳等の報告
前へ	上へ	9.17. シーケンス操作関数	次へ

9.17. シーケンス操作関数 #

<title>Sequence Manipulation Functions</title>

This section describes functions for operating on <firstterm>sequence objects</firstterm>, also called sequence generators or just sequences. Sequence objects are special single-row tables created with <xref linkend="sql-createsequence"/>. Sequence objects are commonly used to generate unique identifiers for rows of a table. The sequence functions, listed in <xref linkend="functions-sequence-table"/>, provide simple, multiuser-safe methods for obtaining successive sequence values from sequence objects. 本節ではシーケンスオブジェクトに対し演算を行う関数について説明します。シーケンスオブジェクトは、シーケンスジェネレータ、あるいは単にシーケンスとも呼ばれます。シーケンスオブジェクトは特殊な一行だけのテーブルで、CREATE SEQUENCEで作成されます。シーケンスオブジェクトは一般的にテーブルの行に一意の識別子を生成するために使用されます。表 9.52に列挙されているシーケンス関数は、シーケンスオブジェクトから連続したシーケンス値を取得するための、簡易でマルチユーザに対応した関数です。

表9.52 シーケンス関数

<title>Sequence Functions</title>

Function 関数 Description 説明
`nextval` ( `regclass` ) → `bigint` Advances the sequence object to its next value and returns that value. This is done atomically: even if multiple sessions execute <function>nextval</function> concurrently, each will safely receive a distinct sequence value. If the sequence object has been created with default parameters, successive <function>nextval</function> calls will return successive values beginning with 1. Other behaviors can be obtained by using appropriate parameters in the <xref linkend="sql-createsequence"/> command. シーケンスを次の値に進めてその値を返します。これは自動的に行われます。複数のセッションが`nextval`を同時に実行しても、各々のシーケンスは異なったシーケンス値を安全に返します。シーケンスオブジェクトがデフォルト値を伴って作成されると、後続の`nextval`呼び出しは1から始まる次の値を返します。それ以外の動作は適切なパラメータをCREATE SEQUENCEコマンドで使うことによって得られます。 This function requires <literal>USAGE</literal> or <literal>UPDATE</literal> privilege on the sequence. この関数はシーケンスオブジェクトの`USAGE`あるいは`UPDATE`権限が必要です。
`setval` ( `regclass`, `bigint` [, `boolean` ] ) → `bigint` Sets the sequence object's current value, and optionally its <literal>is_called</literal> flag. The two-parameter form sets the sequence's <literal>last_value</literal> field to the specified value and sets its <literal>is_called</literal> field to <literal>true</literal>, meaning that the next <function>nextval</function> will advance the sequence before returning a value. The value that will be reported by <function>currval</function> is also set to the specified value. In the three-parameter form, <literal>is_called</literal> can be set to either <literal>true</literal> or <literal>false</literal>. <literal>true</literal> has the same effect as the two-parameter form. If it is set to <literal>false</literal>, the next <function>nextval</function> will return exactly the specified value, and sequence advancement commences with the following <function>nextval</function>. Furthermore, the value reported by <function>currval</function> is not changed in this case. For example, シーケンスオブジェクトの現在の値をセットします。オプションで`is_called`をセットします。 2つのパラメータを持つ形式では、シーケンスの`last_value`フィールドを指定した値にセットし、`is_called`フィールドを`true`に設定します。これは次の`nextval`が値を返す前にシーケンスを増分することを意味します。 `currval`で報告される値も指定した値に設定されます。 3つのパラメータを持つ形式では、`is_called`は`true`あるいは`false`に設定されます。 `true`は2つのパラメータを持つ形式と同じ効果を持ちます。 `false`に設定されていると、次の`nextval`はまさに指定した値を返し、後続の`nextval`がシーケンスの増加を開始します。更に、この場合は`currval`が報告する値は変化しません。たとえば次ようになります。 <programlisting> SELECT setval('myseq', 42); <lineannotation>Next <function>nextval</function> will return 43</lineannotation> SELECT setval('myseq', 42, true); <lineannotation>Same as above</lineannotation> SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</function> will return 42</lineannotation> </programlisting> SELECT setval('myseq', 42); 次の`nextval`は43を返す SELECT setval('myseq', 42, true); 同上 SELECT setval('myseq', 42, false); 次の`nextval`は42を返す The result returned by <function>setval</function> is just the value of its second argument. `setval`が返した値はその2番目の引数と単に同じです。 This function requires <literal>UPDATE</literal> privilege on the sequence. この関数はシーケンスの`UPDATE`権限が必要です。
`currval` ( `regclass` ) → `bigint` Returns the value most recently obtained by <function>nextval</function> for this sequence in the current session. (An error is reported if <function>nextval</function> has never been called for this sequence in this session.) Because this is returning a session-local value, it gives a predictable answer whether or not other sessions have executed <function>nextval</function> since the current session did. 現在のセッションでこのシーケンスに対して直近の`nextval`によって得られた値を返します。（このセッションで`nextval`が呼ばれていなければエラーが報告されます。）これはセッションローカルな値を返すので、他のセッションが`nextval`を呼び出したかどうかに関わらず予測可能な値を返します。 This function requires <literal>USAGE</literal> or <literal>SELECT</literal> privilege on the sequence. この関数はシーケンスの`USAGE`あるいは`SELECT`権限が必要です。
`lastval` () → `bigint` Returns the value most recently returned by <function>nextval</function> in the current session. This function is identical to <function>currval</function>, except that instead of taking the sequence name as an argument it refers to whichever sequence <function>nextval</function> was most recently applied to in the current session. It is an error to call <function>lastval</function> if <function>nextval</function> has not yet been called in the current session. 現在のセッションでこのシーケンスに対して直近の`nextval`によって得られた値を返します。この関数は、現在のセッションで`nextval`が直近に適用されたシーケンス名を参照する引数を取ることを除き、`currval`と同じです。このセッションで`nextval`が呼ばれていないのに`lastval`を呼び出すのはエラーです。 This function requires <literal>USAGE</literal> or <literal>SELECT</literal> privilege on the last used sequence. この関数はシーケンスの`USAGE`あるいは`SELECT`権限が必要です。

Function 関数

Description 説明

nextval ( regclass ) → bigint

Advances the sequence object to its next value and returns that value. This is done atomically: even if multiple sessions execute <function>nextval</function> concurrently, each will safely receive a distinct sequence value. If the sequence object has been created with default parameters, successive <function>nextval</function> calls will return successive values beginning with 1. Other behaviors can be obtained by using appropriate parameters in the <xref linkend="sql-createsequence"/> command. シーケンスを次の値に進めてその値を返します。これは自動的に行われます。複数のセッションがnextvalを同時に実行しても、各々のシーケンスは異なったシーケンス値を安全に返します。シーケンスオブジェクトがデフォルト値を伴って作成されると、後続のnextval呼び出しは1から始まる次の値を返します。それ以外の動作は適切なパラメータをCREATE SEQUENCEコマンドで使うことによって得られます。

This function requires <literal>USAGE</literal> or <literal>UPDATE</literal> privilege on the sequence. この関数はシーケンスオブジェクトのUSAGEあるいはUPDATE権限が必要です。

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

Sets the sequence object's current value, and optionally its <literal>is_called</literal> flag. The two-parameter form sets the sequence's <literal>last_value</literal> field to the specified value and sets its <literal>is_called</literal> field to <literal>true</literal>, meaning that the next <function>nextval</function> will advance the sequence before returning a value. The value that will be reported by <function>currval</function> is also set to the specified value. In the three-parameter form, <literal>is_called</literal> can be set to either <literal>true</literal> or <literal>false</literal>. <literal>true</literal> has the same effect as the two-parameter form. If it is set to <literal>false</literal>, the next <function>nextval</function> will return exactly the specified value, and sequence advancement commences with the following <function>nextval</function>. Furthermore, the value reported by <function>currval</function> is not changed in this case. For example, シーケンスオブジェクトの現在の値をセットします。オプションでis_calledをセットします。 2つのパラメータを持つ形式では、シーケンスのlast_valueフィールドを指定した値にセットし、is_calledフィールドをtrueに設定します。これは次のnextvalが値を返す前にシーケンスを増分することを意味します。 currvalで報告される値も指定した値に設定されます。 3つのパラメータを持つ形式では、is_calledはtrueあるいはfalseに設定されます。 trueは2つのパラメータを持つ形式と同じ効果を持ちます。 falseに設定されていると、次のnextvalはまさに指定した値を返し、後続のnextvalがシーケンスの増加を開始します。更に、この場合はcurrvalが報告する値は変化しません。たとえば次ようになります。 <programlisting> SELECT setval('myseq', 42); <lineannotation>Next <function>nextval</function> will return 43</lineannotation> SELECT setval('myseq', 42, true); <lineannotation>Same as above</lineannotation> SELECT setval('myseq', 42, false); <lineannotation>Next <function>nextval</function> will return 42</lineannotation> </programlisting>

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

The result returned by <function>setval</function> is just the value of its second argument. setvalが返した値はその2番目の引数と単に同じです。

This function requires <literal>UPDATE</literal> privilege on the sequence. この関数はシーケンスのUPDATE権限が必要です。

currval ( regclass ) → bigint

Returns the value most recently obtained by <function>nextval</function> for this sequence in the current session. (An error is reported if <function>nextval</function> has never been called for this sequence in this session.) Because this is returning a session-local value, it gives a predictable answer whether or not other sessions have executed <function>nextval</function> since the current session did. 現在のセッションでこのシーケンスに対して直近のnextvalによって得られた値を返します。（このセッションでnextvalが呼ばれていなければエラーが報告されます。）これはセッションローカルな値を返すので、他のセッションがnextvalを呼び出したかどうかに関わらず予測可能な値を返します。

This function requires <literal>USAGE</literal> or <literal>SELECT</literal> privilege on the sequence. この関数はシーケンスのUSAGEあるいはSELECT権限が必要です。

lastval () → bigint

Returns the value most recently returned by <function>nextval</function> in the current session. This function is identical to <function>currval</function>, except that instead of taking the sequence name as an argument it refers to whichever sequence <function>nextval</function> was most recently applied to in the current session. It is an error to call <function>lastval</function> if <function>nextval</function> has not yet been called in the current session. 現在のセッションでこのシーケンスに対して直近のnextvalによって得られた値を返します。この関数は、現在のセッションでnextvalが直近に適用されたシーケンス名を参照する引数を取ることを除き、currvalと同じです。このセッションでnextvalが呼ばれていないのにlastvalを呼び出すのはエラーです。

This function requires <literal>USAGE</literal> or <literal>SELECT</literal> privilege on the last used sequence. この関数はシーケンスのUSAGEあるいはSELECT権限が必要です。

注意

To avoid blocking concurrent transactions that obtain numbers from the same sequence, the value obtained by <function>nextval</function> is not reclaimed for re-use if the calling transaction later aborts. This means that transaction aborts or database crashes can result in gaps in the sequence of assigned values. That can happen without a transaction abort, too. For example an <command>INSERT</command> with an <literal>ON CONFLICT</literal> clause will compute the to-be-inserted tuple, including doing any required <function>nextval</function> calls, before detecting any conflict that would cause it to follow the <literal>ON CONFLICT</literal> rule instead. Thus, <productname>PostgreSQL</productname> sequence objects <emphasis>cannot be used to obtain <quote>gapless</quote> sequences</emphasis>. 同一のシーケンスから数値を取得する同時実行トランザクション同士のブロックを防止するため、nextvalで得られる値は、呼び出しているトランザクションが後でアボートした際に再利用目的での回収は行われません。これは、トランザクションのアボートあるいはデータベースのクラッシュによって、割り当てられるシーケンスの値に欠番ができることがある、ということを意味します。これはトランザクションのアボートがなくても起こります。例えばON CONFLICT句のあるINSERTでは、挿入される予定のタプルについて、必要となるすべてのnextvalの呼び出しも含めて計算し、その後でON CONFLICTのルールを代わりに使用することになる競合について検知します。従って、PostgreSQLのシーケンスオブジェクトは「欠番のない」シーケンスを得るために使うことはできません。

Likewise, sequence state changes made by <function>setval</function> are immediately visible to other transactions, and are not undone if the calling transaction rolls back. 同様に、setvalが行ったシーケンス状態の変更は直ちに他のトランザクションから可視になり、トランザクションがロールバックしても元には戻りません。

If the database cluster crashes before committing a transaction containing a <function>nextval</function> or <function>setval</function> call, the sequence state change might not have made its way to persistent storage, so that it is uncertain whether the sequence will have its original or updated state after the cluster restarts. This is harmless for usage of the sequence within the database, since other effects of uncommitted transactions will not be visible either. However, if you wish to use a sequence value for persistent outside-the-database purposes, make sure that the <function>nextval</function> call has been committed before doing so. nextvalやsetvalの呼び出しを含むトランザクションがコミットする前にデータベースクラスタがクラッシュすると、そのシーケンスの状態は永続的な記憶装置に格納されないかもしれず、クラスタが再起動した後にそのシーケンスが元の状態のままなのか、更新された状態になっているのかは定かではありません。コミットされていないトランザクションは可視ではないので、これはデータベース内のシーケンスの利用に関して言えば無害です。しかし、シーケンス値をデータベースの外での永続的な利用を目的として使う場合は、nextvalの呼び出しが確実にコミットされてから利用してください。

The sequence to be operated on by a sequence function is specified by a <type>regclass</type> argument, which is simply the OID of the sequence in the <structname>pg_class</structname> system catalog. You do not have to look up the OID by hand, however, since the <type>regclass</type> data type's input converter will do the work for you. See <xref linkend="datatype-oid"/> for details. シーケンス関数により操作されるシーケンスはregclass引数で指定されますが、それはpg_classシステムカタログ内にある、そのシーケンスの単なるOIDです。しかしながら、手作業でOIDを検索する必要はなく、regclassデータ型の入力変換器が代わってその作業を行ってくれます。詳細は8.19を見てください。

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