<!--
$Header: /usr/prj/pg/cvsroot/doc/doc/src/sgml/ref/create_sequence.sgml,v 1.4 2001/09/06 09:49:18 i-kaori Exp $
Postgres documentation
-->

<refentry id="SQL-CREATESEQUENCE">
 <refmeta>
  <refentrytitle id="sql-createsequence-title">
   CREATE SEQUENCE
  </refentrytitle>
  <refmiscinfo>SQL -<!-- Language Statements -->言語</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   CREATE SEQUENCE
  </refname>
  <refpurpose>
   <!-- Creates a new sequence number generator -->
    新しいシーケンス番号生成機構を作成します。<indexterm><primary>CREATE SEQUENCE</primary></indexterm><indexterm><primary>SQL</primary><secondary>CREATE SEQUENCE</secondary></indexterm><indexterm><primary sortas="しーけんす">シーケンス</primary><secondary sortas="さくせい">作成</secondary></indexterm>
  </refpurpose>
 </refnamediv> 
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
<synopsis>
CREATE SEQUENCE <replaceable class="parameter">seqname</replaceable> [ INCREMENT <replaceable class="parameter">increment</replaceable> ]
    [ MINVALUE <replaceable class="parameter">minvalue</replaceable> ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> ]
    [ START <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ CYCLE ]
</synopsis>
  
  <refsect2 id="R2-SQL-CREATESEQUENCE-1">
   <refsect2info>
    <date>1998-09-11</date>
   </refsect2info>
   <title>
    <!-- Inputs -->入力
   </title>

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">seqname</replaceable></term>
      <listitem>
       <para>
	<!-- The name of a sequence to be created. -->
        作成されるシーケンスの名前です。

       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">increment</replaceable></term>
      <listitem>
       <para>
	<!-- The
	<option>INCREMENT <replaceable class="parameter">increment</replaceable></option>
	clause is optional. A positive value will make an
	ascending sequence, a negative one a descending sequence.
	The default value is one (1). -->

        <option>INCREMENT <replaceable class="parameter">increment</replaceable></option>句はオプションで、増加量を設定します。正の値は昇順のシーケンス番号、負の値は降順のシーケンス番号を作成します。設定しない場合のデフォルト値は1です

       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">minvalue</replaceable></term>
      <listitem>
       <para>
	<!-- The optional clause <option>MINVALUE
	 <replaceable class="parameter">minvalue</replaceable></option>
	determines the minimum value
	a sequence can generate. The defaults are 1 and -2147483647 for
	ascending and descending sequences, respectively. -->

         <option>MINVALUE<replaceable class="parameter">minvalue</replaceable></option>句もオプションで、シーケンス番号として作成できる最小の値を決定します。昇順と降順のシーケンスのデフォルト値は、それぞれ1と-2,147,483,647です。

       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">maxvalue</replaceable></term>
      <listitem>
       <para>
	<!-- The optional clause <option>MAXVALUE
	 <replaceable class="parameter">maxvalue</replaceable></option>
	determines the maximum
	value for the sequence. The defaults are 2147483647 and -1 for
	ascending and descending sequences, respectively. -->

        オプション句<option>MAXVALUE<replaceable class="parameter">maxvalue</replaceable></option>は、シーケンス番号の最大値を決定します。昇順と降順のそれぞれのシーケンス番号の最大値のデフォルトは、2,147,483,647と-1です。

       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">start</replaceable></term>
      <listitem>
       <para>
	<!-- The optional <option>START
	 <replaceable class="parameter">start</replaceable>
	 clause</option> enables the sequence to begin anywhere.
	The default starting value is
	<replaceable class="parameter">minvalue</replaceable>
	for ascending sequences and
	<replaceable class="parameter">maxvalue</replaceable>
	for descending ones. -->

        オプションの<option>START<replaceable class="parameter">start</replaceable>clause</option>で、シーケンスをどこからでも始めることができます。これを設定しない場合、シーケンス番号が始まる値は、昇順の場合<replaceable class="parameter">minvalue</replaceable>になり、降順の場合<replaceable class="parameter">maxvalue</replaceable>になります。

       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">cache</replaceable></term>
      <listitem>
       <para>
        <!-- 
	The <option>CACHE <replaceable class="parameter">cache</replaceable></option>        option enables sequence numbers to be preallocated
	and stored in memory for faster access. The  minimum
	value is 1 (only one value can be generated at a time, i.e., no cache)
	and this is also the default. -->

        <option>CACHE <replaceable class="parameter">cache</replaceable></option>オプションは、あらかじめシーケンス番号を割り当てておき、それをメモリに格納しておくことでアクセスを速くします。最小値は1（これは1回に付き1つの値だけを生成します。つまりキャッシュはありません）で、これがデフォルトにもなっています。

       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>CYCLE</term>
      <listitem>
       <para>
        <!-- 
 	The optional CYCLE keyword may be used to enable the sequence
	to wrap around when the
	<replaceable class="parameter">maxvalue</replaceable> or
	<replaceable class="parameter">minvalue</replaceable> has been
	reached by
	an ascending or descending sequence respectively. If the limit is
	reached, the next number generated will be the
	<replaceable class="parameter">minvalue</replaceable> or
	<replaceable class="parameter">maxvalue</replaceable>,
	respectively. -->

        オプションのCYCLEキーワードは、昇順、あるいは降順のシーケンス番号が、それぞれ<replaceable class="parameter">maxvalue</replaceable>または<replaceable class="parameter">minvalue</replaceable>の値に達したときに、シーケンスを元に戻すことを可能にするために使えます。もしシーケンス番号の限界値まで行った場合、次に生成される番号はminvalueまたはmaxvalueのどちらかになります。<indexterm><primary>CYCLE</primary></indexterm><indexterm><primary sortas="しーけんす">シーケンス</primary><secondary>CYCLE</secondary></indexterm>

       </para>
      </listitem>
     </varlistentry>
    </variablelist>
  </refsect2>

  <refsect2 id="R2-SQL-CREATESEQUENCE-2">
   <refsect2info>
    <date>1998-09-11</date>
   </refsect2info>
   <title>
    <!-- Outputs -->出力
   </title>

    <variablelist>
     <varlistentry>
      <term><computeroutput>
CREATE
       </computeroutput></term>
      <listitem>
       <para>
	<!-- Message returned if the command is successful. -->
        コマンドに成功した場合に返されるメッセージです。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
ERROR:  Relation '<replaceable class="parameter">seqname</replaceable>' already exists
       </computeroutput></term>
      <listitem>
       <para>
	<!-- If the sequence specified already exists. -->
        指定したシーケンスがすでに存在している場合のメッセージです。 
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
ERROR:  DefineSequence: MINVALUE (<replaceable class="parameter">start</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)
       </computeroutput></term>
      <listitem>
       <para>
	<!-- If the specified starting value is out of range. -->
        範囲外の初期値が設定された場合です（最大値以上の値が設定されました）。
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
ERROR:  DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">min</replaceable>)
       </computeroutput></term>
      <listitem>
       <para>
	<!-- If the specified starting value is out of range. -->
        範囲外の初期値が設定されました（最小値より小さい値が設定されました）。

       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
ERROR:  DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)
       </computeroutput></term>
      <listitem>
       <para>
	<!-- If the minimum and maximum values are inconsistent. -->
        最小値、最大値の設定が矛盾しています（最小値が、最大値より大きい値に設定されました）。


       </para>
      </listitem>
     </varlistentry>
    </variablelist>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-CREATESEQUENCE-1">
  <refsect1info>
   <date>1998-09-11</date>
  </refsect1info>
  <title>
   <!-- Description -->説明
  </title>
  <para>
   <!--  
   <command>CREATE SEQUENCE</command> will enter a new sequence number generator
   into the current data base. This involves creating and initializing a
   new single-row
   table with the name <replaceable class="parameter">seqname</replaceable>.
   The generator will be owned by the user issuing the command. -->

   <command>CREATE SEQUENCE</command>は、新しいシーケンス番号生成機構を現在のデータベースの中に登録します。これは、<replaceable class="parameter">seqname</replaceable>という名前を持った一列だけの新しいテーブルの作成と初期化を行います。シーケンス番号生成機構は、CREATE SEQUENCEコマンドを実行したユーザーによって所有されます。

  </para>

  <para>
   <!--  
   After a sequence is created, you may use the function
   <function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>
   to get a new number from the sequence.
   The function
   <function>currval('<replaceable class="parameter">seqname</replaceable>')</function>
   may be used to determine the number returned by the last call to
   <function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>
   for the specified sequence in the current session.
   The function
   <function>setval('<replaceable class="parameter">seqname</replaceable>',
   <replaceable class="parameter">newvalue</replaceable>)</function>
   may be used to set the current value of the specified sequence.
   The next call to 
   <function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>
   will return the given value plus the sequence increment. -->

   シーケンスが作られた後、シーケンスから新しい値を取得するために、<function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>という関数を使うことができます。<function>currval('<replaceable class="parameter">seqname</replaceable>')</function>という関数は、現在の接続の中で指定のシーケンスが最後に<function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>が呼び出されたときの返り値を知るために使われます。<function>setval('<replaceable class="parameter">seqname</replaceable>',<replaceable class="parameter">newvalue</replaceable>)</function>という関数は、指定のシーケンスの現在値を設定し直すために使います。この関数で設定を行った後、次に<function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>が呼び出された場合、設定した値に増加量を加えた値を返します。

  </para>

  <para>
   <!-- Use a query like -->
   シーケンステーブルに対する問い合わせは、以下のようにします。 
</para>

<programlisting>
SELECT * FROM <replaceable>seqname</replaceable>;
</programlisting>

<para>
   <!-- to examine the parameters of a sequence.

   As an alternative to fetching the
   parameters from the original definition as above, you can use -->

   上記コマンドで、シーケンスのパラメータを検査することができます。上記のように元の定義からパラメータを取りだす代替案として、バックエンドから割り当てられた最後の値を得るために下記を使うことができます。
</para>

<programlisting>
SELECT last_value FROM <replaceable>seqname</replaceable>;
</programlisting>

<para>
   <!-- to obtain the last value allocated by any backend. -->
   
  </para>

  <para>
   <!-- To avoid blocking of concurrent transactions
   that obtain numbers from the same sequence, a nextval operation
   is never rolled back; that is, once a value has been fetched it is
   considered used, even if the transaction that did the nextval later
   aborts.  This means that aborted transactions may leave unused "holes"
   in the sequence of assigned values.  setval operations are never
   rolled back, either. -->

   同じシーケンスから数を取得するといった同時トランザクションの障害を避けるために、nextval演算はロールバックされることがありません。つまり一度値が取りだされると、もしそのnextvalを行ったトランザクションを後で中止しても、その値は使用済みであると仮定されます。これは中止されたトランザクションは未使用の「穴」を割り振られた値のシーケンスに残す可能性があります。setval演算もロールバックされることはありません。

  </para>

  <caution>
   <para>
    <!-- 
    Unexpected results may be obtained if a cache setting greater than one
    is used for a sequence object that will be used concurrently by multiple
    backends.  Each backend will allocate and cache successive sequence values
    during one access to the sequence object and increase the sequence
    object's last_value accordingly.  Then, the next cache-1 uses of nextval
    within that backend simply return the preallocated values without touching
    the shared object.  So, numbers allocated but not used in the current session
    will be lost.  Furthermore, although multiple backends are guaranteed to
    allocate distinct sequence values, the values may be generated out of
    sequence when all the backends are considered.  (For example, with a cache
    setting of 10, backend A might reserve values 1..10 and return nextval=1, 
    then
    backend B might reserve values 11..20 and return nextval=11 before backend
    A has generated nextval=2.)  Thus, with a cache setting of one it is safe
    to assume that nextval values are generated sequentially; with a cache
    setting greater than one you should only assume that the nextval values
    are all distinct, not that they are generated purely sequentially.
    Also, last_value will reflect the latest value reserved by any backend,
    whether or not it has yet been returned by nextval.
    Another consideration is that a setval executed on such a sequence
    will not be noticed by other backends until they have used up any
    preallocated values they have cached. -->

    もし、複数のバックエンドによって同時に使用される可能性のあるシーケンスオブジェクトに対しキャッシュ設定が1よりも大きい場合、予想外の結果となることがあります。それぞれのバックエンドはシーケンスオブジェクトにアクセスするたびに連続したシーケンスの値を割り当て、キャッシュし、それに応じてシーケンスオブジェクトのlast_valueを増やします。次に、引き続くcache-1はバックエンド内でのnextvalを使用して、共有オブジェクトに触ることなく、事前に割り当てられた値を返します。したがって、割り当てられても、指定されたセッションで使われなかった（シーケンス）番号は破棄されます。さらに、複数のバックエンドは別個のシーケンス番号を付加してよいことになっていますが、その値はすべてのバックエンドを対象にした場合、順列に付いているかは定かでありません（たとえば、キャッシュ設定が10となっていて、バックエンドAが1...10までの値を予約していて、それに従って、バックエンドBが11...20の値を予約してバックエンドAがnextval=2を生成する前にnextval=11を返すことがあります）。従って、キャッシュ設定が1の場合、nextvalの値は連続的に生成されると想定することは安全ですが、キャッシュ設定が1より大きいときは、nextvalの値はすべて重複しない値になりますが、それらは純粋に連続的に生成されるというわけではありません。同様に、last_valueは、nextvalによってどんな値が返されるかということにかかわらず、バックエンドによって一番最近に予約された値を反映しています。このようにして、ある1つの対象にキャッシュを設定することは、nextvalが順序だって生成されることが重要です。もう1つ考慮するべき点は、そのようなシーケンスで実行されたsetvalはキャッシュしている前もって割り当てられた値を使い切るまで他のバックエンドには認識されないということです。

   </para>
  </caution>

  <refsect2 id="R2-SQL-CREATESEQUENCE-3">
   <refsect2info>
    <date>1998-09-11</date>
   </refsect2info>
   <title>
    <!-- Notes -->注釈
   </title>
   <para>
    <!-- Use <command>DROP SEQUENCE</command> to remove a sequence. -->
    シーケンスを削除するには<command>DROP SEQUENCE</command>を使います。

   </para>
   <para>
    <!-- 
    Each backend uses its own cache to store preallocated numbers.
    Numbers that are cached but not used in the current session will be
    lost, resulting in "holes" in the sequence. -->

    それぞれのバックエンドは、前もって割り当てられた番号を格納するために自身の独自のキャッシュを使います。キャッシュされていて現在のセッションでは使われていない番号は消えてしまうため、そのシーケンスには「穴」が空いてしまいます。

   </para>
  </refsect2>
 </refsect1>

 <refsect1 id="R1-SQL-CREATESEQUENCE-2">
  <title>
   <!-- Usage -->使用方法
  </title>
  <para>
   <!-- Create an ascending sequence called <literal>serial</literal>, 
   starting at 101: -->

   101から始まる<literal>serial</literal>という名前の昇順シーケンスを作るには以下のようにします。

  </para>
<programlisting>
CREATE SEQUENCE serial START 101;
</programlisting>
  <para>
   <!-- Select the next number from this sequence: -->
   このシーケンスから次の番号を選択するには以下のようにします。
</para>

<programlisting>
SELECT NEXTVAL ('serial');
    
nextval
-------
    114
</programlisting>

  <para>
   <!-- Use this sequence in an INSERT: -->
   INSERTでこのシーケンスを使うには以下のようにします。
</para>

<programlisting>
INSERT INTO distributors VALUES (NEXTVAL('serial'),'nothing');
</programlisting>

  <para>
   <!-- Set the sequence value after a COPY FROM: -->
   COPY FROMの後でシーケンス値を設定するには以下のようにします。
</para>

<programlisting>
CREATE FUNCTION distributors_id_max() RETURNS INT4
    AS 'SELECT max(id) FROM distributors' 
    LANGUAGE 'sql';
BEGIN;
    COPY distributors FROM 'input_file';
    SELECT setval('serial', distributors_id_max());
END;
</programlisting>
 </refsect1>

 <refsect1 id="R1-SQL-CREATESEQUENCE-3">
  <title>
   <!-- Compatibility -->互換性
  </title>

  <refsect2 id="R2-SQL-CREATESEQUENCE-4">
   <refsect2info>
    <date>1998-09-11</date>
   </refsect2info>
   <title>
    SQL92
   </title>

   <para>
    <!-- <command>CREATE SEQUENCE</command> is a 
    <productname>Postgres</productname>
    language extension.
    There is no <command>CREATE SEQUENCE</command> statement
    in <acronym>SQL92</acronym>. -->

    <command>CREATE SEQUENCE</command>は<productname>Postgres</productname>言語拡張です。<acronym>SQL92</acronym>には<command>CREATE SEQUENCE</command>文はありません。

   </para>
  </refsect2>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->
