Persistence Module: Pipeline Functions

Detailed Description

The persistence module if loaded exposes some methods to pipelines to enable control of the persistence of data.

Note

The methods in this package are only available if the persistence module is loaded.

Functions
	persist.query (var table, var query, var args, var row_cb, var ordering, var limit)
	Query the Database for matching values. More...
	persist.store (var table, var keys, var data)
	Store a value in the persistence Database. More...
	persist.remove (var table, var selector)
	Remove a value in the persistence Database. More...
	persist.get (var table, var selector, var row_cb, var ordering, var limit)
	Retrieve a value from the persistence Database. More...
	persist.call (var procedure, var args, var output_params_cb)
	Call a stored procedure in the persistence Database. More...

Function Documentation

persist.call	(	var	procedure,
		var	args,
		var	output_params_cb
	)

Call a stored procedure in the persistence Database.

Parameters

procedure	procedure to be called
args	ordered array of input arguments to be passed to be provided as input parameters to the procedure call
output_params_cb	function to be called with the returned list of output parameters. The callback functions takes one argument containing a map with all the column-value pairs for the output parameters. Keys are always uppercase.

Return values

-1

on error.

Returns

1 on success.

This function calls a stored procedure and returns any output parameters as key-value pairs from the parameter name to its string value. The input arguments provided are added as input parameters to the procedure call in the order they are provided.

Keys in the map passed to the callback are always uppercase for DMBS independence.

Example:

persist.call("MY_PROCEDURE", {"a", "10"}, function ( output_params )
     -- do something with entries in map row, keys are always uppercase
     print(output_params["b"])
end);

persist.get	(	var	table,
		var	selector,
		var	row_cb,
		var	ordering,
		var	limit
	)

Retrieve a value from the persistence Database.

Parameters

table	table to be queried
selector	table containing all the colums with their keys, e.g. { firstname="bob", lastname="bar" }
row_cb	function to be called for every row returned by the query. The callback functions takes one argument containing a map with all the column-value pairs for a row.
ordering	optional map of the form { age="ASC", mark="DESC" } where "ASC" and "DESC" are the only two allowed values
limit	optional max number of rows to be returned

Return values

-1

on error.

Returns

Otherwise the number of rows returned by the query.

This function executes a query against a database table and returns the rows returned in the result set. The key-value pairs in selector are built into a where clause where every key-value pair represents column/value combinations in the database table and are used in conjunction. A resulting SQL query for a selector { a="10", b="20" } would look like select * from table where a = 10 and b = 20

Keys in the map passed to the callback are always uppercase for DMBS independence.

Example:

persist.get("MY_TABLE", { a=10 }, fn ( row )
     -- do something with entries in map row, keys are always uppercase
     print(row["A"])
end);

persist.query	(	var	table,
		var	query,
		var	args,
		var	row_cb,
		var	ordering,
		var	limit
	)

Query the Database for matching values.

Parameters

table	table to be queried
query	sql where clause in the format "a=? or b>?" or null for all rows
args	array of arguments to be bound to the '?' characters in the query, in the form '{ arg1, arg2, arg3 }'
row_cb	function to be called for every row returned by the query. The callback functions takes one argument containing a map with all the column-value pairs for a row.
ordering	optional map of the form { age="ASC", mark="DESC" } where "ASC" and "DESC" are the only two allowed values
limit	optional max number of rows to be returned

Returns

the number of matched rows

This function executes a query against a database and calls row_cb for every row returned by the query. If this function is called with a query like "a=? and b<?" and an args list of ["foo", "20"] then the resulting sql query would look like: select * from table where a="foo" and b<20

Keys in the map passed to the callback are always uppercase for DMBS independence.

Example:

persist.query("MY_TABLE", "a=?", { 10 }, fn ( row )
     -- do something with entries in map row, keys are always uppercase
     print(row["A"])
end);

persist.remove	(	var	table,
		var	selector
	)

Remove a value in the persistence Database.

Parameters

table	table to delete rows from
selector	array of key-value pairs to restrict the rows to be deleted.

Return values

-1

on error.

Returns

Otherwise the number of deleted rows.

This function attempts to delete rows where all columns specified as keys in selector match the values in selector. A call to this function with a map like { firstname="bob", lastname="bar" } would result in a sql query similar to delete from table table where firstname = bob and lastname = bar;

persist.store	(	var	table,
		var	keys,
		var	data
	)

Store a value in the persistence Database.

Parameters

table	table update or insert should be executed against
keys	table containing key-value pairs to be used in the where clause for the update
data	table containing key-value pairs that should be put

Return values

-1

on error.

Returns

Otherwise the number of stored rows.

This function attempts to update rows where all key-value pairs given in keys match column/value pairs in the database. If this operation results in 0 affected rows, then a merged version of keys and data is inserted into the table. If keys and data share columns then the value of the data map will be taken and the value of keys is ignored.