<!--
$Header: /usr/prj/pg/cvsroot/doc/doc/src/sgml/ref/create_aggregate.sgml,v 1.6 2001/09/06 10:26:03 i-kaori Exp $
Postgres documentation
-->

<refentry id="SQL-CREATEAGGREGATE">
 <refmeta>
  <refentrytitle id="sql-createaggregate-title">
   CREATE AGGREGATE
  </refentrytitle>
  <refmiscinfo>SQL - <!-- Language Statements-->言語</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>
   CREATE AGGREGATE
  </refname>
  <refpurpose>
   <!-- Defines a new aggregate function -->新しい集約関数を定義します。<indexterm><primary>CREATE AGGREGATE</primary></indexterm><indexterm><primary>SQL</primary><secondary>CREATE AGGREGATE</secondary></indexterm><indexterm><primary sortas="しゅうやく">集約</primary><secondary sortas="かんすうのていぎ">関数の定義</secondary></indexterm><indexterm><primary sortas="かんすう">関数</primary><secondary sortas="しゅうやく">集約</secondary></indexterm>
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>2000-07-16</date>
  </refsynopsisdivinfo>
<synopsis>
CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>,
    SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>, STYPE = <replaceable class="PARAMETER">state_type</replaceable>
    [ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
    [ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ] )
</synopsis>

  <refsect2 id="R2-SQL-CREATEAGGREGATE-1">
   <refsect2info>
    <date>2000-07-16</date>
   </refsect2info>
   <title>
    <!-- Inputs -->入力
   </title>
    <variablelist>
     <varlistentry>
      <term><replaceable class="PARAMETER">name</replaceable></term>
      <listitem>
       <para>
	<!-- The name of an aggregate function to create. -->
        作成する集約関数の名前です。
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="PARAMETER">input_data_type</replaceable></term>
      <listitem>
       <para>
        <!-- 
	The input data type on which this aggregate function operates.
	This can be specified as ANY for an aggregate that does not
	examine its input values
	(an example is <function>count(*)</function>). -->

        この集約関数が演算する入力データ型です。これは、入力値を検査しない集約にはANYとして指定することができます（たとえば<function>count(*)</function>）。

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

     <varlistentry>
      <term><replaceable class="PARAMETER">sfunc</replaceable></term>
      <listitem>
       <para>
	<!-- The name of the state transition function
	to be called for each input data value.
	This is normally a function of two arguments, the first being of
	type <replaceable class="PARAMETER">state_type</replaceable>
	and the second of
	type <replaceable class="PARAMETER">input_data_type</replaceable>.
	Alternatively, for an aggregate that does not examine its input
	values, the function takes just one argument of
	type <replaceable class="PARAMETER">state_type</replaceable>.
	In either case the function must return a value of
	type <replaceable class="PARAMETER">state_type</replaceable>.
	This function takes the current state value and the current
	input data item, and returns the next state value. -->

        それぞれの入力データ値に呼び出される状態遷移関数の名前です。これは通常は2つの引数を持ち、最初の引数は<replaceable class="PARAMETER">state_type</replaceable>型で2番目は<replaceable class="PARAMETER">input_data_type</replaceable>型です。代わりに、入力値を検査しない集約にはこの関数は<replaceable class="PARAMETER">state_type</replaceable>型の引数を1つだけとります。どちらの場合でも、この関数は<replaceable class="PARAMETER">state_type</replaceable>型の値を返さなければなりません。この関数は現在の状態値と現在の入力データ項目を受け取り、次の状態値を返します。

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

     <varlistentry>
      <term><replaceable class="PARAMETER">state_type</replaceable></term>
      <listitem>
       <para>
	<!-- The data type for the aggregate's state value. -->
        集約の状態値のデータ型です。
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="PARAMETER">ffunc</replaceable></term>
      <listitem>
       <para>
        <!-- 
	The name of the final function called to compute the aggregate's
	result after all input data has been traversed.  The function
	must take a single argument of type
	<replaceable class="PARAMETER">state_type</replaceable>.
	The output data type of the aggregate is defined as the return
	type of this function.
	If <replaceable class="PARAMETER">ffunc</replaceable>
	is not specified, then the ending state value is used as the
	aggregate's result, and the output type is
	<replaceable class="PARAMETER">state_type</replaceable>.
        -->

        すべての入力データを検索し終わってから集約の結果を計算するために呼ばれる最後の関数の名前です。関数は<replaceable class="PARAMETER">state_type</replaceable>型の引数を1つとらなくてはいけません。集約の出力データ型はこの関数の返り値として定義されます。<replaceable class="PARAMETER">ffunc</replaceable>が指定されない場合には、終了状態値が集約の結果として使われ、出力型は<replaceable class="PARAMETER">state_type</replaceable>になります。

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

     <varlistentry>
      <term><replaceable class="PARAMETER">initial_condition</replaceable></term>
      <listitem>
       <para>
        <!--
	The initial setting for the state value.  This must be a literal
	constant in the form accepted for the data type
	<replaceable class="PARAMETER">state_type</replaceable>.
	If not specified, the state value starts out NULL. -->

        状態値の初期設定です。これはデータ型<replaceable class="PARAMETER">state_type</replaceable>として受け入れられるリテラル定数でなければいけません。もし指定されないと、状態値はNULLとして始まります。

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

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

    <variablelist>
     <varlistentry>
      <term><computeroutput>
CREATE
       </computeroutput></term>
      <listitem>
       <para>
	<!-- Message returned if the command completes successfully.
        -->
        コマンドが問題なく処理された場合に返されるメッセージです。
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-CREATEAGGREGATE-1">
  <refsect1info>
   <date>2000-07-16</date>
  </refsect1info>
  <title>
   <!-- Description -->説明
  </title>
  <para>
   <!-- <command>CREATE AGGREGATE</command> 
   allows a user or programmer to extend 
   <productname>Postgres</productname> functionality by defining 
   new aggregate functions. Some aggregate functions
   for base types such as <function>min(integer)</function>
   and <function>avg(double precision)</function> are already 
   provided in the base distribution. If one defines new types 
   or needs an aggregate function not already provided, then 
   <command>CREATE AGGREGATE</command>
   can be used to provide the desired features. -->

   <command>CREATE AGGREGATE</command>は、ユーザーやプログラマが新しい集約関数を定義することで<productname>Postgres</productname>の機能性を拡張することを可能にします。<function>min(integer)</function>や<function>avg(double precision)</function>のような基本型の集約関数はすでに基本配布物の中で提供されています。もし新しい型を定義するかまだ提供されていない集約関数が必要な場合、必要な機能を提供するために<command>CREATE AGGREGATE</command>を使うことができます。


  </para>
  <para>
   <!-- 
   An  aggregate  function is identified by its name and input data type.
   Two aggregates can have the same name if they operate on different
   input types.  To avoid confusion, do not make an ordinary function
   of the same name and input data type as an aggregate. -->

   集約関数は名前と入力データ型によって識別されます。2つの集約が異なる入力型の演算をする場合は同じ名前でも構いません。混乱を避けるために、通常の関数を同じ名前で作り、入力データ型を集約にはしないでください。

  </para>
  <para>
   <!-- An  aggregate function is made from one or two ordinary
   functions: 

   a state transition function
   <replaceable class="PARAMETER">sfunc</replaceable>,
   and an optional final calculation function
   <replaceable class="PARAMETER">ffunc</replaceable>.
   These are used as follows: -->

   集約関数は1つか2つの通常の関数から作られます。状態遷移関数<replaceable class="PARAMETER">sfunc</replaceable>とオプションの最終計算関数<replaceable class="PARAMETER">ffunc</replaceable>です。これらは以下のように使われます。
</para>

<programlisting>
<replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-item ) ---> next-internal-state
<replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value
</programlisting>

  <para>
   <!-- 
   <productname>Postgres</productname> creates a temporary variable
   of data type <replaceable class="PARAMETER">stype</replaceable>
   to hold the current internal state of the aggregate.  At each input
   data item,
   the state transition function is invoked to calculate a new
   internal state value.  After all the data has been processed,
   the final function is invoked once to calculate the aggregate's output
   value.  If there is no final function then the ending state value
   is returned as-is. -->

   <productname>Postgres</productname>は、集約の現在の内部状態を保持するデータ型の一時変数<replaceable class="PARAMETER">stype</replaceable>を作成します。それぞれの入力データ項目で、状態遷移関数は新しい内部状態値を計算するために呼び出されます。すべてのデータが処理されると、最後の関数は集約の出力値を計算するために1回呼び出されます。もし最後の関数がなければ終了状態値がそのまま返されます。

  </para>
  
  <para>
   <!-- 
   An aggregate function may provide an initial condition,
   that is, an initial value for the internal state value.
   This is specified and stored in the database as a field of type
   <type>text</type>, but it must be a valid external representation
   of a constant of the state value data type.  If it is not supplied
   then the state value starts out NULL. -->

   集約関数は、内部状態値のための初期値である、初期状態を提供することができます。これは<type>text</type>型のフィールドとして指定されてデータベースに格納されますが、状態値データ型の定数の有効な外部表現でなければいけません。もし初期状態が供給されないと、NULLとして始まります。

  </para>
  
  <para>
   <!-- 
   If the state transition function is declared "strict" in 
   pg_proc, then it cannot be called with NULL inputs.  With 
   such a transition function, aggregate execution behaves 
   as follows.  NULL input values are ignored (the function 
   is not called and the previous state value is retained).  
    If the initial state value is NULL, then the first
   non-NULL input value replaces the state value, and the 
   transition function is invoked beginning with the second 
   non-NULL input value.
   This is handy for implementing aggregates like 
   <function>max</function>.
   Note that this behavior is only available when
   <replaceable class="PARAMETER">state_type</replaceable>
   is the same as
   <replaceable class="PARAMETER">input_data_type</replaceable>.
   When these types are different, you must supply a non-NULL 
   initial condition or use a non-strict transition function.
   -->

   もし状態遷移関数がpg_procで「厳格」と宣言されると、NULL入力で呼び出すことはできません。そのような遷移関数では、集約の実行は以下のようになります。NULL入力値が無視されます（その関数は呼び出されず前の状態値が持存します）。もし初期状態値がNULLだと、最初の非NULL入力値が状態値を置き換え、遷移関数は2番目の非NULL入力値から呼び出しが始まります。これは<function>max</function>のような集約の実装には便利です。このような動作は<replaceable class="PARAMETER">state_type</replaceable>が<replaceable class="PARAMETER">input_data_type</replaceable>と同じときにのみ有効になります。これらの型が異なるときは、非NULL初期値を供給するか非厳格でない遷移関数を使わなければいけません。<indexterm><primary>NULL</primary></indexterm>

  </para>
  
  <para>
   <!--  
   If the state transition function is not strict, then it 
   will be called unconditionally at each input value, and 
   must deal with NULL inputs and NULL transition values for itself.  
   This allows the aggregate author to have full control over the 
   aggregate's handling of NULLs. -->

   状態遷移関数が厳格ではない場合、それぞれの入力値で無条件に呼び出され、NULL入力とNULL遷移値を自分で処理しなければいけません。これは集約の作成者が集約のNULLの扱いについて完全に管理することを可能にします。

  </para>
  
  <para>
   <!-- 
   If the final function is declared "strict", then it will not
   be called when the ending state value is NULL; instead a NULL result
   will be output automatically.  (Of course this is just the normal
   behavior of strict functions.)  In any case the final function has
   the option of returning NULL.  For example, the final function for
   <function>avg</function> returns NULL when it sees there were zero
   input tuples. -->

   もし最後の関数が「厳格」と宣言されると、終了状態値がNULLの場合には呼び出されません。代わりにNULLの結果が自動的に出力になります（もちろんこれは厳格な関数のただ一般的な動作でしかありません）。どのような場合でも最後の関数はNULLを返す選択があります。たとえば、<function>avg</function>の最後の関数は入力タプルが0だとわかるとNULLを返します。

  </para>
  
  <refsect2 id="R2-SQL-CREATEAGGREGATE-3">
   <refsect2info>
    <date>2000-07-16</date>
   </refsect2info>
   <title>
    <!-- Notes -->注釈
   </title>
   <para>
    <!-- Use <command>DROP AGGREGATE</command>
    to drop aggregate functions. -->

    集約関数を削除するには<command>DROP AGGREGATE</command>を使います。

   </para>

   <para>
    <!-- 
    The parameters of <command>CREATE AGGREGATE</command> 
    can be written in any order, not just the order illustrated above.
    -->

    <command>CREATE AGGREGATE</command>のパラメータは、上記で示されるものだけではなくどのような順番で書かれても構いません。

   </para>

  </refsect2>
 </refsect1>

 <refsect1 id="R1-SQL-CREATEAGGREGATE-2">
  <title>
   <!-- Usage -->使用方法
  </title>
  <para>
   <!-- Refer to the chapter on aggregate functions
   in the <citetitle>PostgreSQL Programmer's Guide</citetitle> for
   complete examples of usage. -->

   使用方法の完全な例は<citetitle>&programmer-guide;</citetitle>の集約関数の章を参照してください。

  </para>
 </refsect1>

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

  <refsect2 id="R2-SQL-CREATEAGGREGATE-4">
   <refsect2info>
    <date>1998-09-09</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para>
    <!-- <command>CREATE AGGREGATE</command> 
    is a <productname>Postgres</productname> language extension.
    There is no <command>CREATE AGGREGATE</command> in SQL92.
    -->

    <command>CREATE AGGREGATE</command>は<productname>Postgres</productname>言語拡張です。SQL92には<command>CREATE AGGREGATE</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:
-->
