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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: lapistano Status: ready -->
<refentry xml:id="function.sqlite-create-aggregate" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>sqlite_create_aggregate</refname>
  <refname>SQLiteDatabase->createAggregate</refname>
  <refpurpose>
   Registriert eine benutzerdefinierte Funktion, um SQL-Abfragen zu aggregieren
  </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>callback</type><parameter>step_func</parameter></methodparam>
   <methodparam><type>callback</type><parameter>finalize_func</parameter></methodparam>
   <methodparam choice="opt">
    <type>int</type>
    <parameter>num_args</parameter>
    <initializer>-1</initializer>
   </methodparam>
  </methodsynopsis>
  <para>Objektorientierter Stil (Methode):</para>
  <classsynopsis>
   <ooclass><classname>SQLiteDatabase</classname></ooclass>
   <methodsynopsis>
    <type>void</type><methodname>createAggregate</methodname>
    <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
    <methodparam><type>callback</type><parameter>step_func</parameter></methodparam>
    <methodparam><type>callback</type><parameter>finalize_func</parameter></methodparam>
    <methodparam choice="opt">
     <type>int</type>
     <parameter>num_args</parameter>
     <initializer>-1</initializer>
    </methodparam>
   </methodsynopsis>
  </classsynopsis>
  <para>
   <function>sqlite_create_aggregate</function> funktioniert wie
   <function>sqlite_create_function</function>, ausser dass es Funktionen
   registriert, die benutzt werden, um ein Ergebnis aggregiert über alle Zeilen
   der Abfrage zu berechnen.
  </para>
  <para>
   Der größte Unterschied in dieser Funktion und
   <function>sqlite_create_function</function> liegt darin, das man zwei
   Funktionen registrieren muss, um zu aggregieren;
   <parameter>step_func</parameter> wird für jede Zeile des Abfrageergebnisses
   aufgerufen. Ihre PHP-Funktion (<parameter>function_name</parameter>)
   sollte das Ergebnis akkumulieren und dieses im Aggregatkontext speichern. 
   Sobald alle Zeilen verarbeitet wurden, wird
   <parameter>finalize_func</parameter> aufgerufen. Diese Funktion sollte die
   Daten aus dem Aggregatkontext nehmen und als Ergebnis zurückgeben.
   Callback-Funktionen sollten einen Typ liefern, der von SQLite verstanden wird
   (z.B. <link linkend="language.types.intro">Skalartypen</link>).
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>dbhandle</parameter></term>
     <listitem>
      <para>
       Die Ressource der SQLite-Datenbank, die bei prozeduraler Benutzung von
       <function>sqlite_open</function> zurückgegeben wurden. Der Parameter
       wird bei der objektorientierten Methode nicht benötigt.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>function_name</parameter></term>
     <listitem>
      <para>
       Der Name der Funktion, der in SQL-Abfragen benutzt wird.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>step_func</parameter></term>
     <listitem>
      <para>
       Callback-Funktion mit der jede Zeile des Abfrageergebnisses aufgerufen
       wird.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>finalize_func</parameter></term>
     <listitem>
      <para>
       Callback-Funktion, die die durchlaufenen Daten aggregiert.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>num_args</parameter></term>
     <listitem>
      <para>
       Hinweis für den SQLite-Parser, ob die Callback-Funktion eine
       vordefinierte Anzahl von Argumenten annimmt.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

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

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>aggregierte max_length-Funktion</title>
    <programlisting role="php">
<![CDATA[
<?php
$data = array(
   'eins',
   'zwei',
   'drei',
   'vier',
   'fuenf',
   'sechs',
   'sieben',
   'acht',
   'neun',
   'zehn',
   );
$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>
   In diesem Beispiel haben wir eine Aggregatfunktion erstellt, die die Länge
   des längsten Strings einer Tabellenspalte berechnet. Jede Zeile wird mit
   der Funktion <literal>max_len_step</literal> mit dem Parameter
   <parameter>context</parameter> aufgerufen. Der Parameter context ist wie jede
   andere PHP-Variable und sollte ein Array oder auch ein Objekt speichern
   können. In diesem Beispiel benutzen wird ihn lediglich dazu, die bisherige
   maximale Länge zu speichern; sollte <parameter>string</parameter> größer
   sein, als das aktuelle Maximum, aktuallisieren wir den Wert mit der neuen
   maximalen Länge.
  </para>
  <para>
   Wenn alle Zeilen durchlaufen sind, ruft SQLite die Funktion
   <literal>max_len_finalize</literal> auf, um das aggregierte Ergebnis
   auszuwerten. Hier könnten wir einige Berechnungen anstellen, basierend auf
   den Daten, die in <parameter>context</parameter> stehen. In unserem einfachen
   Beispiel haben wir das Ergebnis bereits während der Abfrage berechnet, sodass
   wir einfach nur den Wert in context zurückgeben können.
  </para>
  <note>
   <para>
    Das oben aufgeführte Beispiel funktioniert nicht akkurat, wenn die Spalte
    Binärdaten enthalten würde. Eine Erklärung dafür liefert die Dokumentation
    unter <function>sqlite_udf_decode_binary</function>, genauso wie ein
    Beispiel dafür, wie man die Binärkodierung berücksichtigt.
   </para>
  </note>
  <tip>
   <para>
    Es wird NICHT empfohlen eine Kopie der Werte in context zu speichern und
    diese erst am Schluss zu verarbeiten. Dadurch würde SQLite viel Speicher
    verbrauchen, um die Abfrage zu bearbeiten. Man muß sich nur vorstellen,
    wieviel Speicher man brauchen würde, um eine Million Zeilen, jede mit
    einer Länge von 32 Byte, im Speicher zu halten.
   </para>
  </tip>
  <tip>
   <para>
    Man kann <function>sqlite_create_function</function> und
    <function>sqlite_create_aggregate</function> nutzen, um native
    SQL-Funktionen im SQLite zu überschreiben.
   </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
 -->