User Guide - query builder

Fleshing out the API reference
Signed-off-by:James L Parry <jim_parry@bcit.ca>

1 files changed, 282 insertions, 15 deletions

diff --git a/user_guide_src/source/database/query_builder_reference.rst b/user_guide_src/source/database/query_builder_reference.rst
index 7c379ae84..21b15431a 100644
--- a/user_guide_src/source/database/query_builder_reference.rst
+++ b/user_guide_src/source/database/query_builder_reference.rst
@@ -214,27 +214,294 @@ Class Reference
 
 		Specify a limit and offset for the query
 
-	.. method:: x
+	.. method:: not_group_start()
 
-		:param	string	$x: x
-		:returns:	x
-		:rtype:	x
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Starts a query group, but NOTs the group
+
+	.. method:: not_like($field, $match = '', $side = 'both', $escape = NULL)
+
+		:param	string	$field: Name of field to compare
+		:param	string	$match: Text portion to match
+		:param	string	$side: Position of a match
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates a NOT LIKE portion of the query.
+                Separates multiple calls with 'AND'.
+
+	.. method:: offset($offset)
+
+		:param	int	$offset: Number of rows to skip in a query
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Sets the OFFSET value
+
+	.. method:: or_group_start()
+
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Starts a query group, but ORs the group
+
+	.. method:: or_having($key, $value = NULL, $escape = NULL)
+
+		:param	string	$key: Key (string) or associative array of values
+		:param	string	$value: Value sought if the key is a string
+		:param	string	$escape: TRUE to escape the content
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Separates multiple calls with 'OR'.
+
+	.. method:: or_like($field, $match = '', $side = 'both', $escape = NULL)
+
+		:param	string	$field: Name of field to compare
+		:param	string	$match: Text portion to match
+		:param	string	$side: Position of a match
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates a %LIKE% portion of the query.
+                Separates multiple calls with 'OR'.
+
+	.. method:: or_not_group_start()
+
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Starts a query group, but OR NOTs the group
+
+	.. method:: or_not_like($field, $match = '', $side = 'both', $escape = NULL)
+
+		:param	string	$field: Name of field to compare
+		:param	string	$match: Text portion to match
+		:param	string	$side: Position of a match
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates a NOT LIKE portion of the query.
+                Separates multiple calls with 'OR'.
+
+	.. method:: or_where($key, $value = NULL, $escape = NULL)
+
+		:param	mixed	$key: Name of field to compare, or associative array
+		:param	mixed	$value: If a single key, compared to this value
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates the WHERE portion of the query.
+                Separates multiple calls with 'OR'.
+
+	.. method:: or_where_in($key = NULL, $values = NULL, $escape = NULL)
+
+		:param	string	$key: The field to search
+		:param	array	$values: The values searched on
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates a WHERE field IN('item', 'item') SQL query,
+                joined with 'OR' if appropriate.
+
+	.. method:: or_where_not_in($key = NULL, $values = NULL, $escape = NULL)
+
+		:param	string	$key: The field to search
+		:param	array	$values: The values searched on
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates a WHERE field NOT IN('item', 'item') SQL query,
+                joined with 'OR' if appropriate.
+
+	.. method:: order_by($orderby, $direction = '', $escape = NULL)
+
+		:param	string	$orderby: The field to order by
+		:param	string	$direction: The order requested - asc, desc or random
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates an ORDER BY clause in the SQL query
+
+	.. method:: replace($table = '', $set = NULL)
+
+		:param	string	$table: The table to query
+		:param	array	$set: Associative array of insert values
+		:returns:	DB_result, FALSE on failure
+		:rtype:	mixed
+
+		Compiles an replace into string and runs the query
+
+	.. method:: reset_query()
+
+		:rtype:	void
+
+		Publicly-visible method to reset the QB values.
+
+	.. method:: select($select = '*', $escape = NULL)
+
+		:param	string	$select: Comma-separated list of fields to select
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates the SELECT portion of the query
+
+	.. method:: select_avg($select = '', $alias = '')
+
+		:param	string	$select: Field to compute the average of
+		:param	string	$alias: Alias for the resulting value
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates a SELECT AVG(field) portion of a query
+
+	.. method:: select_max($select = '', $alias = '')
+
+		:param	string	$select: Field to compute the maximum of
+		:param	string	$alias: Alias for the resulting value
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates a SELECT MAX(field) portion of a query
+
+	.. method:: select_min($select = '', $alias = '')
+
+		:param	string	$select: Field to compute the minimum of
+		:param	string	$alias: Alias for the resulting value
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates a SELECT MIN(field) portion of a query
+
+	.. method:: select_sum($select = '', $alias = '')
+
+		:param	string	$select: Field to compute the sum of
+		:param	string	$alias: Alias for the resulting value
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates a SELECT SUM(field) portion of a query
+
+	.. method:: set($key, $value = '', $escape = NULL)
+
+		:param	mixed	$key: The field to be set, or an array of key/value pairs
+		:param	string	$value: If a single key, its new value
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Allows key/value pairs to be set for inserting or updating
+
+	.. method:: set_dbprefix($prefix = '')
+
+		:param	string	$prefix: The new prefix to use
+		:returns:	The DB prefix in use
+		:rtype:	string
+
+		Set's the DB Prefix to something new without needing to reconnect
+
+	.. method:: set_insert_batch($key, $value = '', $escape = NULL)
+
+		:param	mixed	$key: The field to be set, or an array of key/value pairs
+		:param	string	$value: If a single key, its new value
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
 
-		x
+		The "set_insert_batch" function.  Allows key/value pairs to be set for batch inserts
 
-	.. method:: x
+	.. method:: set_update_batch($key, $value = '', $escape = NULL)
 
-		:param	string	$x: x
-		:returns:	x
-		:rtype:	x
+		:param	mixed	$key: The field to be set, or an array of key/value pairs
+		:param	string	$value: If a single key, its new value
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		The "set_batch_batch" function.  Allows key/value pairs to be set for batch batch
+
+	.. method:: start_cache()
+
+		:rtype:	void
+
+		Start DB caching
+
+	.. method:: stop_cache()
+
+		:rtype:	void
 
-		x
+		Stop DB caching
+
+	.. method:: truncate($table = '')
+
+		:param	string	$table: Name fo the table to truncate
+		:returns:	DB_result
+		:rtype:	object
+
+		Compiles a truncate string and runs the query.
+                If the database does not support the truncate() command
+                This function maps to "DELETE FROM table"
+
+	.. method:: update($table = '', $set = NULL, $where = NULL, $limit = NULL)
+
+		:param	string	$table: The table to insert data into
+		:param	array	$set: An associative array of insert values
+		:param	string	$where: WHERE clause to use
+		:param	string	$limit: LIMIT clause to use
+		:returns:	DB_result
+		:rtype:	object
 
-	.. method:: x
+		Compiles an update string and runs the query.
 
-		:param	string	$x: x
-		:returns:	x
-		:rtype:	x
+	.. method:: update_batch($table = '', $set = NULL, $value = NULL)
 
-		x
+		:param	string	$table: The table to update data in
+		:param	mixed	$set: The field to be set, or an array of key/value pairs
+		:param	string	$value: If a single key, its new value
+		:returns:	DB_result
+		:rtype:	object
+
+		Compiles an update string and runs the query.
+
+	.. method:: where($key, $value = NULL, $escape = NULL)
+
+		:param	mixed	$key: Name of field to compare, or associative array
+		:param	mixed	$value: If a single key, compared to this value
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates the WHERE portion of the query.
+                Separates multiple calls with 'AND'.
+
+	.. method:: where_in($key = NULL, $values = NULL, $escape = NULL)
+
+		:param	string	$key: Name of field to examine
+		:param	array	$values: Array of target values
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
+
+		Generates a WHERE field IN('item', 'item') SQL query,
+                joined with 'AND' if appropriate.
+
+	.. method:: where_not_in($key = NULL, $values = NULL, $escape = NULL)
+
+		:param	string	$key: Name of field to examine
+		:param	array	$values: Array of target values
+		:param	boolean	$escape: Whether to escape values and identifiers
+		:returns:	DB_query_builder instance
+		:rtype:	object
 
+		Generates a WHERE field NOT IN('item', 'item') SQL query,
+                joined with 'AND' if appropriate.
\ No newline at end of file