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


SQLiteDatabase::createAggregate

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

sqlite_create_aggregate -- SQLiteDatabase::createAggregateРегистрирует агрегирующую функцию для использования в SQL-запросах

Описание

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

Объектно-ориентированный стиль (метод):

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

sqlite_create_aggregate() похожа на sqlite_create_function(), за исключением того, что регистрирует функцию, которая может быть использована для вычисления результата на основе всех записей результата запроса.

Главное отличие этой функции от sqlite_create_function() состоит в том, что для работы агрегирующей функции неоходимы 2 функции; step_func вызывается для каждой записи из результата запроса. Эта функция должна аккумулировать результат и сохранять его в контекстной переменной. После обработки всех записей, вызывается finalize_func, которая должна обработать данные из контекстной переменной и вернуть результат. Callback-функции должны возвращать тип, который сможет понять SQLite (т.е. скалярный).

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

dbhandle

Ресурс базы данных SQLite, полученный из функции sqlite_open() в случае использования процедурного подхода. Этот параметр не требуется при использовании объектно-ориентированного подхода.

function_name

Имя функции, используемой в SQL-запросах.

step_func

Callback-функция, вызываемая для каждого ряда результирующего набора. Функция принимает параметры &$context, $value, ....

finalize_func

Callback-функция для агрегации собранных данных из каждого ряда. Функция принимает параметр &$context и должна вернуть итоговый результат агрегации.

num_args

Подсказка парсеру SQLite, если callback-функция принимает известное количество параметров.

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

Эта функция не возвращает значения после выполнения.

Примеры

Пример #1 Пример агрегирующей функции 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'));

?>

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

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

Замечание:

Приведенный выше пример будет работать некорректно, если прменить созданную функцию к бинарным данным. Описание функции sqlite_udf_decode_binary() объясняет, почему это происходит и как этого избежать.

Подсказка

НЕ РЕКОМЕНДУЕТСЯ сохранять все полученные значения в контекстной переменной и затем производить все вычисления на последнем шаге, так как при этом SQLite может израсходовать большое количество памяти в процессе обработки запроса - представьте, сколько памяти потребуется, чтобы сохранить в памяти миллион записей, по 32 байта каждая.

Подсказка

sqlite_create_function() и sqlite_create_aggregate() могут быть использованы для переопределения встроенных функций SQLite.

Смотрите также

  • sqlite_create_function() - Регистрирует "стандартную" функцию (UDF) для использования в SQL-запросах
  • sqlite_udf_encode_binary() - Кодирует бинарные данные перед тем как вернуть их из UDF
  • sqlite_udf_decode_binary() - Декодирует бинарные данные, переданные в качестве параметров в UDF