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
Aviso

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

Exemplo #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.

Dica

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.

Dica

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

Veja Também

add a note add a note

User Contributed Notes

There are no user contributed notes for this page.
To Top