Зарегистрировать функцию PHP в качестве агрегирующей функции SQL

Описание

public SQLite3::createAggregate ( string $name , mixed $step_callback , mixed $final_callback [, int $argument_count = -1 ] ) : bool

Регистрирует функцию PHP или пользовательскую функцию в качестве агрегирующей функции SQL для использования в запросах.

Список параметров

name

Имя агрегирующей функции SQL, которая должна быть создана или переопределена.

step_callback

Функция обратного вызова, которая будет вызвана для каждой строки результирующего набора. Ваша PHP-функция должна аккумулировать результат и хранить его в контексте агрегации.

Эта функция должна быть определена следующим образом:

step ( mixed $context , int $rownumber , mixed $value1 [, mixed $... ] ) : mixed

context: Для первой строки должено равняться NULL; Для всех последующих строк его значение должно быть равно значению, возвращенному на предыдущем шаге; вы должны использовать его для сохранения состояния агрегации.
rownumber: Номер текущей строки.
value1: Первый аргумент переданный агрегатору.
...: Последующие аргументы.

Возвращаемое значение функции будет использовано как параметр context при следующем запуске функции, либо как значение передаваемое финализирующей функции.

final_callback

Функция обратного вызова для вычисление итогового агрегированного значения. Она будет вызвана как только все строки результирующего набора будут обработаны, ей будет передан агрегирующий контекст и она вернет финальное значение. Данная функция должна вернуть значение типа понятного SQLite (т.е. скалярный тип).

Эта функция должна быть определена следующим образом:

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

context: Содержит результат самого последнего вызова агрегирующей функции.
rownumber: Всегда 0.

Возвращаемое значение этой функции будет использовано как возвращаемое значение всего агрегатора.

argument_count

Количество аргументов, которое принимает функция агрегированиия SQL. Если значение отрицательное, то функция может использовать любое количество аргументов.

Возвращаемые значения

Возвращает TRUE или FALSE в зависимости от успешности создания.

Примеры

Пример #1 Пример агрегирующей функции max_length


<?php
$data = array(
   'one',
   'two',
   'three',
   'four',
   'five',
   'six',
   'seven',
   'eight',
   'nine',
   'ten',
   );
$db = new SQLite3(':memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($data as $str) {
    $insert->bindValue(1, $str);
    $insert->execute();
}
$insert = null;

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

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

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

var_dump($db->querySingle('SELECT max_len(a) from strings'));
?>

Результат выполнения данного примера:

int(5)

В этом примере мы написали агрегирующую функцию, которая вычисляет самой длинной строки в одной колонке таблицы. Для каждой строки вызывается функция max_len_step и ей передается параметр $context. Этот параметр ничем не отличается от обычной переменной PHP и спокойно может содержать массив или объект. В этом примере мы используем ее для хранения максимальной найденной длины строки. Если $string будет иметь длину больше, чем текущая сохраненная, то значение контекста будет обновлено.

После того, как все строки обработаны, SQLite вызовет функцию max_len_finalize, для окончательной подготовки результата. Тут мы можем произвести необходимые расчеты на основе данных из $context. В нашем простом примере никакая постобрпботке не нужна и мы просто возвращаем полученное значение.

Подсказка

НЕ рекомендуется хранить копию значений в контексте, а обработку производить в финализирующей функции, так как это может привести к большому потреблению памяти при обработке запроса. Просто представьте, сколько памяти вам понадобится для хранения миллиона строк, по 32 байта каждая, в памяти.

Подсказка

Для переопределения встроенных в SQLite агрегирующих функций вы можете использовать SQLite3::createAggregate().