db:create_aggregate
Creates an aggregate callback function
Prototype
db:create_aggregate(name,nargs,step,final)Description
This function creates an aggregate callback function. Aggregates perform an operation over all rows in a query. name is a string with the name of the aggregate function as given in an SQL statement; nargs is the number of arguments this call will provide. step is the actual Lua function that gets called once for every row; it should accept a function context (see below for callback contexts) plus the same number of parameters as given in nargs. final is a function that is called once after all rows have been processed; it receives one argument, the function context.
The function context can be used inside the two callback functions to communicate with SQLite3. Here is a simple example:
db:exec[=[
CREATE TABLE numbers(num1,num2);
INSERT INTO numbers VALUES(1,11);
INSERT INTO numbers VALUES(2,22);
INSERT INTO numbers VALUES(3,33);
]=]
local num_sum=0
local function oneRow(context,num) -- add one column in all rows
num_sum=num_sum+num
end
local function afterLast(context) -- return sum after last row has been processed
context:result_number(num_sum)
num_sum=0
end
db:create_aggregate("do_the_sums",1,oneRow,afterLast)
for sum in db:urows('SELECT do_the_sums(num1) FROM numbers') do print("Sum of col 1:",sum) end
for sum in db:urows('SELECT do_the_sums(num2) FROM numbers') do print("Sum of col 2:",sum) end
This prints:
Sum of col 1: 6
Sum of col 2: 66
CALLBACK CONTEXTS
A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.
The various context functions are:
context:aggregate_count
context:get_aggregate_data
context:result
context:result_blob
context:result_error
context:result_int
context:result_null
context:result_number
context:result_text
context:set_aggregate_data
context:user_data
The function context can be used inside the two callback functions to communicate with SQLite3. Here is a simple example:
db:exec[=[
CREATE TABLE numbers(num1,num2);
INSERT INTO numbers VALUES(1,11);
INSERT INTO numbers VALUES(2,22);
INSERT INTO numbers VALUES(3,33);
]=]
local num_sum=0
local function oneRow(context,num) -- add one column in all rows
num_sum=num_sum+num
end
local function afterLast(context) -- return sum after last row has been processed
context:result_number(num_sum)
num_sum=0
end
db:create_aggregate("do_the_sums",1,oneRow,afterLast)
for sum in db:urows('SELECT do_the_sums(num1) FROM numbers') do print("Sum of col 1:",sum) end
for sum in db:urows('SELECT do_the_sums(num2) FROM numbers') do print("Sum of col 2:",sum) end
This prints:
Sum of col 1: 6
Sum of col 2: 66
CALLBACK CONTEXTS
A callback context is available as a parameter inside the callback functions db:create_aggregate() and db:create_function(). It can be used to get further information about the state of a query.
The various context functions are:
context:aggregate_count
context:get_aggregate_data
context:result
context:result_blob
context:result_error
context:result_int
context:result_null
context:result_number
context:result_text
context:set_aggregate_data
context:user_data
Lua functions
- context:aggregate_count - Returns the number of calls to the aggregate step function.
- context:get_aggregate_data - Returns the user-definable data field for callback functions.
- context:result - This function sets the result of a callback function to res.
- context:result_blob - This function sets the result of a callback function to the binary string in blob.
- context:result_error - This function sets the result of a callback function to the error value in err.
- context:result_int - This function sets the result of a callback function to the integer value in number
- context:result_null - This function sets the result of a callback function to nil.
- context:result_number - This function sets the result of a callback function to the value number.
- context:result_text - This function sets the result of a callback function to the string in str.
- context:set_aggregate_data - Set the user-definable data field for callback functions to udata.
- context:user_data - Returns the userdata parameter given in the call to install the callback function.
- db:busy_handler - Sets or removes a busy handler for a database
- db:busy_timeout - Sets a busy handler
- db:changes - Returns number of changes by the most recent SQL statement
- db:close - Closes a database
- db:close_vm - Finalizes all statements that have not been explicitly finalized
- db:create_collation - Creates a collation callback
- db:create_function - Creates a callback function
- db:errcode - Returns the most recent result code
- db:errmsg - Returns the most recent error message
- db:exec - Executes SQL statements
- db:interrupt - Interrupts any pending operation
- db:isopen - Tests if the database is open
- db:last_insert_rowid - Returns the key of the most recent insert into the database
- db:nrows - Creates an iterator that returns a table of rows from a SELECT - keyed by name
- db:prepare - Compiles an SQL statement
- db:progress_handler - Installs a progress callback function
- db:rows - Creates an iterator that returns a table of rows from a SELECT - numerically keyed
- db:total_changes - Returns total number of changes
- db:trace - Installs debug trace callback
- db:urows - Creates an iterator that returns the rows from a SELECT
- sqlite3.complete - Checks for a complete SQL statement
- sqlite3.open - Opens or creates a database
- sqlite3.open_memory - Opens a database in memory
- sqlite3.version - Returns the SQLite version
- stmt:bind - Binds a value to a parameter
- stmt:bind_blob - Binds a blob to a parameter
- stmt:bind_names - Binds values in a table to parameters
- stmt:bind_parameter_count - Returns the largest parameter index
- stmt:bind_parameter_name - Returns the name of the n'th paremeter
- stmt:bind_values - Binds values to parameters
- stmt:columns - Returns number of columns in the result set
- stmt:finalize - Frees a prepared statement
- stmt:get_name - Returns the name of a column in a result set
- stmt:get_named_types - Returns a table of names and types for the columns in a result set
- stmt:get_named_values - Returns a table of names and values for the columns in a result set
- stmt:get_names - Returns a table of the names of all columns in a result set
- stmt:get_type - Returns the type of a column in a result set
- stmt:get_types - Returns a table of the types of all columns in a result set
- stmt:get_unames - Returns a list of names of the columns in a result set
- stmt:get_utypes - Returns a list of types of the columns in a result set
- stmt:get_uvalues - Returns a list of values of the columns in a result set
- stmt:get_value - Returns the value of a column in a result set
- stmt:get_values - Returns a table of the values of all columns in a result set
- stmt:isopen - Checks if the statement is open
- stmt:nrows - Creates an iterator that returns a table of rows from a SELECT - keyed by name
- stmt:reset - Resets an SQL statement, so it can be executed again
- stmt:rows - Creates an iterator that returns a table of rows from a SELECT - numerically keyed
- stmt:step - Executes a previously-prepared SQL statement
- stmt:urows - Creates an iterator that returns the rows from a SELECT