sqlite_create_aggregate

SQLiteDatabase::createAggregate

(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)

sqlite_create_aggregate -- SQLiteDatabase::createAggregate — Registrar FDU totalizadora para usarla en sentencias SQL

Descripción

sqlite_create_aggregate ( resource $dbhandle , string $function_name , callable $step_func , callable $finalize_func [, int $num_args = -1 ] ) : void

Estilo orientado a objetos (method):

public SQLiteDatabase::createAggregate ( string $function_name , callable $step_func , callable $finalize_func [, int $num_args = -1 ] ) : void

sqlite_create_aggregate() es similar a sqlite_create_function() excepto que registra funciones que pueden ser usadas para calcular un resultado totalizador de todas las filas de una consulta.

La diferencia principal entre esta función y sqlite_create_function() es que se necesitan dos funciones para administrar la totalización; step_func es llamada para cada fila del conjunto de resultados. La función de PHP debería acumular el resultado y almacenarlo en un contexto totalizador. Una vez que se han procesado todas las filas, finalize_func será llamada y entonces debería tomar los datos desde el contexto totalizador y devolver el resultado. Las funciones de llamada de retorno deberían un tipo comprendido por SQLite (esto es, un tipo escalar).

Parámetros

dbhandle

El recurso de Base de datos de SQLite; devuelto por sqlite_open() cuando se usa procedimentalmente. Este parámetro no es necesario cuando se usa el método orientado a objetos.

function_name

El nombre de la función utlizada en las sentencias SQL.

step_func

Función de llamada de retorno llamada para cada fila del conjunto de resultados. Los parámetros de la función son &$context, $value, ....

finalize_func

Función de llamada de retorno para totalizar los datos "escalonados" de cada fila. El parámero de la función es &$context y la función debería devolver el resultado final de la totalización.

num_args

Alusión al analizador de SQLite si la función de llamada de retorno acepta un número predeterminado de argumentos.

Valores devueltos

No devuelve ningún valor.

Ejemplos

Ejemplo #1 Ejemplo de función totalizadora max_length

<?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'));

?>

En este ejemplo creamos una función totalizadora que calculará la longitud de la cadena más larga en una de las columnas de la tabla. Para cada fila, la función max_len_step es llamada y se le pasa un parámetro context. El parámetro context es como cualquier otra variable de PHP y es establecido para contener un array o incluso un valor de un objeto. En este ejemplo, simplemente estamos usándolo para que contenga la longitud máxima que hemos estado viendo; si el parámetro string tiene una longitud mayor que el máximo actual, actualizamos el contexto para que contenga esta nueva longitud máxima.

Después de que todas las filas se hayan procesado, SQLite llama a la función max_len_finalize para determinar el resultado total. Aquí, podríamos llevar a cabo algún tipo de cálculo basado en los datos encontrados en context. Aunque en nuestro sencillo ejemplo hemos ido calculando el resultado mientras la consulta progresaba, por lo que simplemente necesitamos devolver el valor de contex.

Nota:

El ejemplo de arrbia no funcionará correctamente si la columna contiene datos binarios. Échele un vistazo a la página del manual de sqlite_udf_decode_binary() para una explicación de por qué esto es así, y un ejemplo de cómo hacerlo respecto a la codificación binaria.

Sugerencia

NO se recomienda almacenar una copia de los valores de context y despúes procesarlos al final, ya que causaría que SQLite usara un montoón de memoria para procesar la consulta - simplemente piense en cúanta memoria se necesitaría si estuviesen almacenadas en memoria un millón de filas, cada una conteniendo una cadena de 32 bytes de longitud.

Sugerencia

Se puede usar sqlite_create_function() y sqlite_create_aggregate() para sobrescribir las funciones SQL nativas de SQLite.

Ver también