archived-doc-ja/reference/sqlite/functions/sqlite-create-aggregate.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 5faa7a6747bca628b3bdcc9f93aec5603b65581f Maintainer: takagi Status: ready -->
<!-- CREDITS: hirokawa,shimooka -->
<refentry xml:id="function.sqlite-create-aggregate" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>sqlite_create_aggregate</refname>
  <refname>SQLiteDatabase::createAggregate</refname>
  <refpurpose>SQLステートメントで使用する集約UDFを登録する</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>void</type><methodname>sqlite_create_aggregate</methodname>
   <methodparam><type>resource</type><parameter>dbhandle</parameter></methodparam>
   <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
   <methodparam><type>callable</type><parameter>step_func</parameter></methodparam>
   <methodparam><type>callable</type><parameter>finalize_func</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>num_args</parameter><initializer>-1</initializer></methodparam>
  </methodsynopsis>
  <para>&style.oop; (メソッド):</para>
  <methodsynopsis>
   <type>void</type><methodname>SQLiteDatabase::createAggregate</methodname>
   <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
   <methodparam><type>callable</type><parameter>step_func</parameter></methodparam>
   <methodparam><type>callable</type><parameter>finalize_func</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>num_args</parameter><initializer>-1</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>sqlite_create_aggregate</function> は、
   <function>sqlite_create_function</function> に似ていますが、
   クエリの全レコードを通じて集約された結果を計算するために使用される
   関数を登録するところが異なります。
  </para>
  <para>
   この関数と <function>sqlite_create_function</function> の主な違い
   は、二つの関数が集約を管理するために必要であることです。
   <parameter>step_func</parameter>は、結果セットの各レコードに関して
   コールされます。PHP関数は、結果を加算し、集約コンテキストに保存する
   必要があります。
   全レコードが処理された後、
   <parameter>finalize_func</parameter>がコールされ、
   集約コンテキストからデータが取得され、結果が返されます。
   コールバック関数は SQLite が認識可能な型 (すなわち
   <link linkend="language.types.intro">スカラー型</link>)
   を返す必要があります。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>dbhandle</parameter></term>
     <listitem>
      <para>
       SQLite データベースリソース。手続きに従って、
       <function>sqlite_open</function> から返されます。
       このパラメータは、
       オブジェクト指向言語型メソッドを使用する場合は不要です。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>function_name</parameter></term>
     <listitem>
      <para>
       SQL ステートメントで使用される関数名
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>step_func</parameter></term>
     <listitem>
      <para>
       結果セットの各レコードに対してコールされるコールバック関数。
       この関数のパラメータは <literal>&amp;$context, $value, ...</literal> です。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>finalize_func</parameter></term>
     <listitem>
      <para>
       各レコードからの "段階的な" データを集約するためのコールバック関数。
       この関数のパラメータは <literal>&amp;$context</literal> で、
       集約の最終的な結果を返さなければなりません。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>num_args</parameter></term>
     <listitem>
      <para>
       見積もられた引数の数をコールバック関数が受け入れる場合に
       SQLite パーサへ渡すヒント
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>max_length 集約関数の例</title>
    <programlisting role="php">
<![CDATA[
<?php
$data = array(
   'one',
   'two',
   'three',
   'four',
   'five',
   'six',
   'seven',
   'eight',
   'nine',
   'ten',
   );
$dbhandle = sqlite_open(':memory:');
sqlite_query($dbhandle, "CREATE TABLE strings(a)");
foreach ($data as $str) {
    $str = sqlite_escape_string($str);
    sqlite_query($dbhandle, "INSERT INTO strings VALUES ('$str')");
}

function max_len_step(&$context, $string)
{
    if (strlen($string) > $context) {
        $context = strlen($string);
    }
}

function max_len_finalize(&$context)
{
    return $context;
}

sqlite_create_aggregate($dbhandle, 'max_len', 'max_len_step', 'max_len_finalize');

var_dump(sqlite_array_query($dbhandle, 'SELECT max_len(a) from strings'));

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   この例では、テーブルのあるカラムに存在する最長な文字列長を計算する
   集約関数を生成します。各レコードに対して <literal>max_len_step</literal>
   関数がコールされ、<parameter>context</parameter> パラメータが渡されます。
   コンテキストパラメータは他の PHP 変数と同様で、
   配列もしくはオブジェクト値を保持するよう設定されます。
   この例では、単純にこれまでの最大長を保持するために使用しています。
   もし <parameter>string</parameter> が現在の最大長よりも長い場合、
   新しい最大長を保持するためにコンテキストを更新します。
  </para>
  <para>
   全てのレコードが処理された後、SQLite は集約結果を決定するために
   <literal>max_len_finalize</literal> 関数をコールします。
   ここで、<parameter>context</parameter> 内に見つかったデータに基づいた
   計算のような処理を実行することができます。
   ただ、この簡単な例では、クエリの処理が進むと共に結果を計算しているので、
   単純にコンテキストの値を返す必要があります。
  </para>
  <note>
   <para>
    上記の例は、カラムがバイナリデータを含む場合に正しく動作しません。
    なぜそうなるか、またどのようにバイナリエンコーディングを考慮するか
    についてはマニュアルページの
    <function>sqlite_udf_decode_binary</function>
    を参照ください。
   </para>
  </note>
  <tip>
   <para>
    SQLite がクエリを処理するために大量のメモリを使用する原因になるので、
    コンテキストの値のコピーをストアした後でそれらを処理することは
    推奨されません。
    もし 32 バイトの文字列を含む 100 万レコードがメモリにストアされた場合、
    どの程度のメモリが必要になるか考えてみてください。
   </para>
  </tip>
  <tip>
   <para>
    <function>sqlite_create_function</function> や
    <function>sqlite_create_aggregate</function> を用いることで、
    SQLite のネイティブな SQL 関数をオーバーライドすることが可能です。
   </para>
  </tip>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>sqlite_create_function</function></member>
    <member><function>sqlite_udf_encode_binary</function></member>
    <member><function>sqlite_udf_decode_binary</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-omittag:t
 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:"~/.phpdoc/manual.ced"
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
 vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
 -->