PDO::sqliteCreateAggregate

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateAggregate — Registra uma função de agregação definida pelo usuário para uso em declarações SQL

Descrição

public PDO::sqliteCreateAggregate(
    string $function_name,
    callable $step_func,
    callable $finalize_func,
    int $num_args = ?
): bool
Warning

Esta função é EXPERIMENTAL. O comportamento desta função, seu nome e documentação poderão mudar sem aviso prévio em futuras versões do PHP. Use por sua conta e risco.

Este método é semelhante a PDO::sqliteCreateFunction, exceto que registra funções que podem ser usadas para calcular um resultado agregado através de todas as linhas de uma consulta.

A principal diferença entre este método e PDO::sqliteCreateFunction é que duas funções são necessárias para gerenciar a agregação.

Parâmetros

function_name

O nome da função usada nas declarações SQL.

step_func

Função callback chamada para cada linha do conjunto de resultados. A função PHP deve acumular o resultado e armazená-lo no contexto de agregação.

Esta função precisa ser definida como:

step(
    mixed $context,
    int $rownumber,
    mixed $value,
    mixed ...$values
): mixed
context

null para a primeira linha; nas linhas subsequentes terá o valor que foi retornado anteriormente da função step; isso deve ser usado para manter o estado de agregação.

rownumber

O número da linha atual.

value

O primeiro argumento passado para a agregação.

values

Outros argumentos passados para a agregação.

O valor retornado desta função será usado como o argumento context na próxima chamada das funções step ou finalize.
finalize_func

Função de chamada de retorno para agregar os dados "passados" de cada linha. Depois que todas as linhas forem processadas, esta função será chamada e deverá então pegar os dados do contexto de agregação e retornar o resultado. Esta função deve retornar um tipo reconhecido pelo SQLite (ou seja, um tipo escalar).

Esta função precisa ser definida como:

fini(mixed $context, int $rowcount): mixed
context

Contém o valor retornado da última chamada à função step.

rowcount

Contém o número de linhas nas quais a agregação foi executada.

O valor retornado desta função será usado como valor retornado da agregação.
num_args

Indica ao analisador SQLite se a função callback aceita um número predeterminado de argumentos.

Valor Retornado

Retorna true em caso de sucesso ou false em caso de falha.

Exemplos

Example #1 Exemplo de função de agregação max_length

<?php
$dados = array(
   'um',
   'dois',
   'três',
   'quatro',
   'cinco',
   'seis',
   'sete',
   'oito',
   'nove',
   'dez',
   );
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($dados as $string) {
    $insert->execute(array($string));
}
$insert = null;

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

function max_len_finalize($context, $rowcount)
{
    return $context === null ? 0 : $context;
}

$db->sqliteCreateAggregate('max_len', 'max_len_step', 'max_len_finalize');

var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());

?>

Neste exemplo, está sendo criada uma função de agregação que irá calcular o comprimento da string mais longa de uma das colunas da tabela. Para cada linha, a função max_len_step é chamada e recebe um parâmetro $context. O parâmetro de contexto é como qualquer outra variável PHP e pode conter um array ou até mesmo um valor de objeto. Neste exemplo, ele está sendo usado apenas para manter o comprimento máximo visto até agora; se a $string tiver um comprimento maior que o máximo atual, o contexto será atualizado para conter esse novo comprimento máximo.

Após todas as linhas terem sido processadas, o SQLite chama a função max_len_finalize para determinar o resultado agregado. Aqui, algum tipo de cálculo poderia ser realizado com base nos dados encontrados no parâmetro $context. Porém, neste exemplo simples, o resultado foi calculado à medida que a consulta avançava, portanto é necessário apenas retornar o valor do contexto.

Tip

NÃO é recomendado armazenar uma cópia dos valores no contexto e depois processá-los no final, pois isso faria com que o SQLite usasse muita memória para processar a consulta - basta pensar em quanta memória seria necessária se um milhão linhas fossem armazenadas na memória, cada uma contendo uma string de 32 bytes de comprimento.

Tip

PDO::sqliteCreateFunction e PDO::sqliteCreateAggregate podem ser usados para substituir funções SQL nativas do SQLite.

Veja Também