PDO::sqliteCreateAggregate
(PHP 5 >= 5.1.0, PHP 7, PECL pdo_sqlite >= 1.0.0)
PDO::sqliteCreateAggregate — Registers an aggregating User Defined Function for use in SQL statements
Description
$function_name
, callable $step_func
, callable $finalize_func
[, int $num_args
] ) : boolThis function is EXPERIMENTAL. The behaviour of this function, its name, and surrounding documentation may change without notice in a future release of PHP. This function should be used at your own risk.
This method is similar to PDO::sqliteCreateFunction except that it registers functions that can be used to calculate a result aggregated across all the rows of a query.
The key difference between this method and PDO::sqliteCreateFunction is that two functions are required to manage the aggregate.
Parameters
-
function_name -
The name of the function used in SQL statements.
-
step_func -
Callback function called for each row of the result set. Your PHP function should accumulate the result and store it in the aggregation context.
This function need to be defined as:
-
context -
NULLfor the first row; on subsequent rows it will have the value that was previously returned from the step function; you should use this to maintain the aggregate state. -
rownumber -
The current row number.
-
value1 -
The first argument passed to the aggregate.
-
... -
Further arguments passed to the aggregate.
contextargument in the next call of the step or finalize functions. -
-
finalize_func -
Callback function to aggregate the "stepped" data from each row. Once all the rows have been processed, this function will be called and it should then take the data from the aggregation context and return the result. This callback function should return a type understood by SQLite (i.e. scalar type).
This function need to be defined as:
-
context -
Holds the return value from the very last call to the step function.
-
rowcount -
Holds the number of rows over which the aggregate was performed.
-
-
num_args -
Hint to the SQLite parser if the callback function accepts a predetermined number of arguments.
Examples
Example #1 max_length aggregation function example
<?php
$data = array(
'one',
'two',
'three',
'four',
'five',
'six',
'seven',
'eight',
'nine',
'ten',
);
$db = new PDO('sqlite::memory:');
$db->exec("CREATE TABLE strings(a)");
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
foreach ($data as $str) {
$insert->execute(array($str));
}
$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());
?>
In this example, we are creating an aggregating function that will calculate the length of the longest string in one of the columns of the table. For each row, the max_len_step function is called and passed a $context parameter. The context parameter is just like any other PHP variable and be set to hold an array or even an object value. In this example, we are simply using it to hold the maximum length we have seen so far; if the $string has a length longer than the current maximum, we update the context to hold this new maximum length.
After all of the rows have been processed, SQLite calls the max_len_finalize function to determine the aggregate result. Here, we could perform some kind of calculation based on the data found in the $context. In our simple example though, we have been calculating the result as the query progressed, so we simply need to return the context value.
It is NOT recommended for you to store a copy of the values in the context and then process them at the end, as you would cause SQLite to use a lot of memory to process the query - just think of how much memory you would need if a million rows were stored in memory, each containing a string 32 bytes in length.
You can use PDO::sqliteCreateFunction and PDO::sqliteCreateAggregate to override SQLite native SQL functions.
Note:
This method is not available with the SQLite2 driver. Use the old style sqlite API for that instead.
See Also
- PDO::sqliteCreateFunction
- sqlite_create_function() - Registers a "regular" User Defined Function for use in SQL statements
- sqlite_create_aggregate() - Register an aggregating UDF for use in SQL statements
English translation
You have asked to visit this site in English. For now, only the interface is translated, but not all the content yet.If you want to help me in translations, your contribution is welcome. All you need to do is register on the site, and send me a message asking me to add you to the group of translators, which will give you the opportunity to translate the pages you want. A link at the bottom of each translated page indicates that you are the translator, and has a link to your profile.
Thank you in advance.
Document created the 30/01/2003, last modified the 26/10/2018
Source of the printed document:https://www.gaudry.be/en/php-rf-pdo.sqlitecreateaggregate.html
The infobrol is a personal site whose content is my sole responsibility. The text is available under CreativeCommons license (BY-NC-SA). More info on the terms of use and the author.
References
These references and links indicate documents consulted during the writing of this page, or which may provide additional information, but the authors of these sources can not be held responsible for the content of this page.
The author This site is solely responsible for the way in which the various concepts, and the freedoms that are taken with the reference works, are presented here. Remember that you must cross multiple source information to reduce the risk of errors.
