sqlite_create_aggregate

Description

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

sqlite_create_aggregate() is similar to sqlite_create_function() except that it registers functions that can be used to calculate a result aggregated across all the rows of a query.

The key difference between this function and sqlite_create_function() is that two functions are required to manage the aggregate; step_func is called for each row of the result set. Your PHP function should accumulate the result and store it into the aggregation context. Once all the rows have been processed, finalize_func will be called and it should then take the data from the aggregation context and return the result.

Example 1. max_length aggregation function example <?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')); ?>

In this example, we are creating an aggregating function that will calculate the length of the longest string in one of the columns of the table. For each row, the max_len_step function is called and passed a context parameter. The context parameter is just like any other PHP variable and be set to hold an array or even an object value. In this example, we are simply using it to hold the maximum length we have seen so far; if the string has a length longer than the current maximum, we update the context to hold this new maximum length.

After all of the rows have been processed, SQLite calls the max_len_finalize function to determine the aggregate result. Here, we could perform some kind of calculation based on the data found in the context. In our simple example though, we have been calculating the result as the query progressed, so we simply need to return the context value.

See also sqlite_create_function(), sqlite_udf_encode_binary() and sqlite_udf_decode_binary().