(PHP 5 < 5.4.0, PECL sqlite >= 1.0.0)
sqlite_create_aggregate — Registra uma função agregada UDF para usar em SQLs
$dbhandle
, string $function_name
, mixed $step_func
, mixed $finalize_func
[, int $num_args
] ) : boolsqlite_create_aggregate() é similar a sqlite_create_function() com a diferença que registra funções que podem ser usadas para calcular um resultado através de todas as linhas de uma query.
A diferença chave entre esta função e
sqlite_create_function() é que duas funções são requeridas
para gerenciar a agregada; step_func
é
executada para cada linha do conjunto de resultados. Sua função PHP
deve acumular o resultado e guardar no contexto da agregação.
Uma vez que todas as linhas tenham sido processadas,
finalize_func
será chamada e deve então
pegar os dados do contexto de agregação e então retornar o resultado.
Exemplo #1 Exemplo de agregação
<?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'));
?>
Neste exemplo, nós estamos criando uma função agregada que irá calcular
o tamanho da maior string de uma das colunas da tabela.
Para cada linha, max_len_step
é executada e passado o
parâmetro context
. O parâmetro contexto é
igual a qualquer outra variavel PHP e pode guardar uma matriz ou um objeto.
Neste exemplo, nós estamos usando simplesmente para guardar o tamanho
da maior string que nós vimos até aqui, se
string
tiver um tamanho maior do que o máximo atual,
nós atualizamos o contexto para guardar este novo tamanho máximo.
Depois que todas as linhas tiverem sido processadas, SQLite chama a função
max_len_finalize
para determinar o resultado agregado.
Aqui você pode fazer algum tipo de calculo baseado nos dados encontrados em
context
. No nosso exemplo simples,
nós já calculamos o resultado de acordo com o progresso da query, então nós
precisamos apenas retornar o valor de contexto.
Nota:
O exemplo acima não irá funcionar corretamente se a coluna conter dados binários. De uma olhada na pagina do manual para a função sqlite_udf_decode_binary() para uma explicação do porque é assim, e um exemplo de como fazer respeitar a codificação binária.
NÃO é recomendado que você guarde uma copia dos valores no contexto e então processe no final, já que você pode fazer com que o SQLite use uma grande quantidade de memória para processar a query - pense quanta memória você vai necessitar se tiver um milhão de linhas, cada uma contendo uma string de 32 bytes de tamanho.
Você pode usar sqlite_create_function() e sqlite_create_aggregate() para sobrescrever as funções nativas de SQL do SQLite.
Veja também sqlite_create_function(), sqlite_udf_encode_binary() e sqlite_udf_decode_binary().