sqlite_create_aggregate

(PHP 5)

sqlite_create_aggregate -- SQLステートメントで使用する集約UDFを登録する

Description

bool sqlite_create_aggregate ( resource db, string function_name, mixed step_func, mixed finalize_func [, int num_args] )

sqlite_create_aggregate()は、 sqlite_create_function()に似ていますが、 クエリの全レコードを通じて集約された結果を計算するために使用される 関数を登録するところが異なります。

この関数と sqlite_create_function() の主な違い は、二つの関数が集約を管理するために必要であることです。 step_funcは、結果セットの各レコードに関して コールされます。PHP関数は、結果を加算し、集約コンテキストに保存する 必要があります。 全レコードが処理された後、 finalize_funcがコールされ、 集約コンテキストからデータが取得され、結果が返されます。

例 1. max_length 集約関数の例

<?php
$data
= array(
   
'one',
   
'two',
   
'three',
   
'four'
   'five'
   'six'
,
   
'seven',
   
'eight',
   
'nine'
   'ten'
   
);
$db = sqlite_open(':memory:');
sqlite_query($db, "CREATE TABLE strings(a)");
foreach (
$data as $str) {
  
sqlite_query($db, "INSERT INTO strings VALUES('" .
    
sqlite_escape_string($str) . "')");
}

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

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

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

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

?>

この例では、テーブルのカラムの中で最も長い文字列の長さを計算する集 約関数を作成しています。各レコードについて、この max_len_step 関数がコールされ、 context パラメータが渡されます。このcontext パラメータは、他のPHP変数と全同じで、配列やオブジェクトを値として代 入することが可能です。この例では、このパラメータを単にこれまでの処 理での最大長を保持するために使用しています。つまり、 string の長さがカレントの最大長よりも長かっ た場合、この新しい最大長を保持するためにcontextを更新します。

全てのレコードが処理された後、SQLite は、集約結果を定義するために max_len_finalize 関数をコールします。 ここで、contextにあるデータに基づき何らかの 計算を行うことができます。しかし、上の簡単な例では、クエリを行った 際に結果は計算されているので、単にcontextの値を返しています。

注意: 上の例は、カラムにバイナリデータが含まれている場合には正しく動作し ません。その理由とバイナリエンコーディングへの対応方法に関しては、 マニュアルの sqlite_udf_decode_binary() のページをご覧ください。

ティップ: contextの中に値のコピーを保存した後、最後にこれらを処理することは 推奨されません。これは、SQLiteがクエリ処理に多くのメモリを使用する ことになるからです。各レコードが32バイト長の文字列を含む百万件のレ コードをメモリに保存するために、どれだけのメモリが必要かを考えてみ てください。

ティップ: SQLiteのネーティブSQL関数をオーバーライドするために sqlite_create_function()および sqlite_create_aggregate()を使用することができ ます。

sqlite_create_function()sqlite_udf_encode_binary()sqlite_udf_decode_binary()も参照してください。