User Guide - query builder
Removed API stuff from the query builder page.
Added a new API reference page.
Updated the index to include the API ref in the TOC.
Started on the API reference page.
Signed-off-by:James L Parry <jim_parry@bcit.ca>
diff --git a/user_guide_src/source/database/index.rst b/user_guide_src/source/database/index.rst
index 4612daf..14a871a 100644
--- a/user_guide_src/source/database/index.rst
+++ b/user_guide_src/source/database/index.rst
@@ -16,6 +16,7 @@
Generating Query Results <results>
Query Helper Functions <helpers>
Query Builder Class <query_builder>
+ Query Builder API <query_builder_reference>
Transactions <transactions>
Getting MetaData <metadata>
Custom Function Calls <call_function>
diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst
index 3203ff1..701c489 100644
--- a/user_guide_src/source/database/query_builder.rst
+++ b/user_guide_src/source/database/query_builder.rst
@@ -23,14 +23,17 @@
:local:
:depth: 1
+.. note:: This page describes how to use the Query Builder class.
+ API reference information is found on the
+ `Query Builder API <query_builder_reference.html>`_ page.
+
**************
Selecting Data
**************
The following functions allow you to build SQL **SELECT** statements.
-$this->db->get()
-----------------
+**$this->db->get()**
Runs the selection query and returns the result. Can be used by itself
to retrieve all records from a table::
@@ -57,11 +60,7 @@
Please visit the :doc:`result functions <results>` page for a full
discussion regarding result generation.
-:returns: DB_Result for a successful "read",
- TRUE for a successful "write", FALSE if an error
-
-$this->db->get_compiled_select()
---------------------------------
+**$this->db->get_compiled_select()**
Compiles the selection query just like **$this->db->get()** but does not *run*
the query. This method simply returns the SQL query as a string.
@@ -90,10 +89,7 @@
executed using **$this->db->get()** which resets values or reset directly
using **$this->db->reset_query()**.
-:returns: The SQL select string
-
-$this->db->get_where()
-----------------------
+**$this->db->get_where()**
Identical to the above function except that it permits you to add a
"where" clause in the second parameter, instead of using the db->where()
@@ -105,11 +101,7 @@
.. note:: get_where() was formerly known as getwhere(), which has been removed
-:returns: DB_Result for a successful "read",
- TRUE for a successful "write", FALSE if an error
-
-$this->db->select()
--------------------
+**$this->db->select()**
Permits you to write the SELECT portion of your query::
@@ -129,10 +121,7 @@
$this->db->select('(SELECT SUM(payments.amount) FROM payments WHERE payments.invoice_id=4') AS amount_paid', FALSE);
$query = $this->db->get('mytable');
-:returns: The query builder object
-
-$this->db->select_max()
------------------------
+**$this->db->select_max()**
Writes a "SELECT MAX(field)" portion for your query. You can optionally
include a second parameter to rename the resulting field.
@@ -181,11 +170,7 @@
$this->db->select_sum('age');
$query = $this->db->get('members'); // Produces: SELECT SUM(age) as age FROM members
-:returns: The query builder object
-
-
-$this->db->from()
------------------
+**$this->db->from()**
Permits you to write the FROM portion of your query::
@@ -196,10 +181,7 @@
.. note:: As shown earlier, the FROM portion of your query can be specified
in the $this->db->get() function, so use whichever method you prefer.
-:returns: The query builder object
-
-$this->db->join()
------------------
+**$this->db->join()**
Permits you to write the JOIN portion of your query::
@@ -223,14 +205,11 @@
$this->db->join('comments', 'comments.id = blogs.id', 'left');
// Produces: LEFT JOIN comments ON comments.id = blogs.id
-:returns: The query builder object
-
*************************
Looking for Specific Data
*************************
-$this->db->where()
-------------------
+**$this->db->where()**
This function enables you to set **WHERE** clauses using one of four
methods:
@@ -306,10 +285,7 @@
.. note:: or_where() was formerly known as orwhere(), which has been
removed.
-:returns: The query builder object
-
-$this->db->where_in()
----------------------
+**$this->db->where_in()**
Generates a WHERE field IN ('item', 'item') SQL query joined with AND if
appropriate
@@ -332,10 +308,7 @@
$this->db->or_where_in('username', $names);
// Produces: OR username IN ('Frank', 'Todd', 'James')
-:returns: The query builder object
-
-$this->db->where_not_in()
--------------------------
+**$this->db->where_not_in()**
Generates a WHERE field NOT IN ('item', 'item') SQL query joined with
AND if appropriate
@@ -358,15 +331,11 @@
$this->db->or_where_not_in('username', $names);
// Produces: OR username NOT IN ('Frank', 'Todd', 'James')
-:returns: The query builder object
-
-
************************
Looking for Similar Data
************************
-$this->db->like()
------------------
+**$this->db->like()**
This method enables you to generate **LIKE** clauses, useful for doing
searches.
@@ -432,10 +401,7 @@
$this->db->or_not_like('body', 'match');
// WHERE `title` LIKE '%match% OR `body` NOT LIKE '%match%' ESCAPE '!'
-:returns: The query builder object
-
-$this->db->group_by()
----------------------
+**$this->db->group_by()**
Permits you to write the GROUP BY portion of your query::
@@ -448,10 +414,7 @@
.. note:: group_by() was formerly known as groupby(), which has been
removed.
-:returns: The query builder object
-
-$this->db->distinct()
----------------------
+**$this->db->distinct()**
Adds the "DISTINCT" keyword to a query
@@ -460,10 +423,7 @@
$this->db->distinct();
$this->db->get('table'); // Produces: SELECT DISTINCT * FROM table
-:returns: The query builder object
-
-$this->db->having()
--------------------
+**$this->db->having()**
Permits you to write the HAVING portion of your query. There are 2
possible syntaxes, 1 argument or 2::
@@ -491,14 +451,11 @@
Identical to having(), only separates multiple clauses with "OR".
-:returns: The query builder object
-
****************
Ordering results
****************
-$this->db->order_by()
----------------------
+**$this->db->order_by()**
Lets you set an ORDER BY clause.
@@ -542,14 +499,11 @@
.. note:: Random ordering is not currently supported in Oracle and
will default to ASC instead.
-:returns: The query builder object
-
****************************
Limiting or Counting Results
****************************
-$this->db->limit()
-------------------
+**$this->db->limit()**
Lets you limit the number of rows you would like returned by the query::
@@ -561,10 +515,7 @@
$this->db->limit(10, 20); // Produces: LIMIT 20, 10 (in MySQL. Other databases have slightly different syntax)
-:returns: The query builder object
-
-$this->db->count_all_results()
-------------------------------
+**$this->db->count_all_results()**
Permits you to determine the number of rows in a particular Active
Record query. Queries will accept Query Builder restrictors such as
@@ -575,18 +526,13 @@
$this->db->from('my_table');
echo $this->db->count_all_results(); // Produces an integer, like 17
-:returns: Count of all the records returned by a query
-
-$this->db->count_all()
-----------------------
+**$this->db->count_all()**
Permits you to determine the number of rows in a particular table.
Submit the table name in the first parameter. Example::
echo $this->db->count_all('my_table'); // Produces an integer, like 25
-:returns: Count of all the records in the specified table
-
**************
Query grouping
**************
@@ -630,14 +576,11 @@
Ends the current group by adding an closing parenthesis to the WHERE clause of the query.
-:returns: The query builder object
-
**************
Inserting Data
**************
-$this->db->insert()
--------------------
+**$this->db->insert()**
Generates an insert string based on the data you supply, and runs the
query. You can either pass an **array** or an **object** to the
@@ -674,12 +617,9 @@
.. note:: All values are escaped automatically producing safer queries.
-:returns: DB_Query on success, FALSE on failure
+**$this->db->get_compiled_insert()**
-$this->db->get_compiled_insert()
---------------------------------
-
-Compiles the insertion query just like `$this->db->insert()`_ but does not
+Compiles the insertion query just like $this->db->insert() but does not
*run* the query. This method simply returns the SQL query as a string.
Example::
@@ -696,7 +636,7 @@
// Produces string: INSERT INTO mytable (title, name, date) VALUES ('My title', 'My name', 'My date')
The second parameter enables you to set whether or not the query builder query
-will be reset (by default it will be--just like `$this->db->insert()`_)::
+will be reset (by default it will be--just like $this->db->insert())::
echo $this->db->set('title', 'My Title')->get_compiled_insert('mytable', FALSE);
@@ -714,10 +654,7 @@
.. note:: This method doesn't work for batched inserts.
-:returns: The SQL insert string
-
-$this->db->insert_batch()
--------------------------
+**$this->db->insert_batch()**
Generates an insert string based on the data you supply, and runs the
query. You can either pass an **array** or an **object** to the
@@ -744,14 +681,11 @@
.. note:: All values are escaped automatically producing safer queries.
-:returns: Count of the number of records inserted on success, FALSE on failure
-
*************
Updating Data
*************
-$this->db->replace()
---------------------
+**$this->db->replace()**
This method executes a REPLACE statement, which is basically the SQL
standard for (optional) DELETE + INSERT, using *PRIMARY* and *UNIQUE*
@@ -779,10 +713,7 @@
Usage of the ``set()`` method is also allowed and all fields are
automatically escaped, just like with ``insert()``.
-:returns: DB_query object on success, FALSE on failure
-
-$this->db->set()
-----------------
+**$this->db->set()**
This function enables you to set values for inserts or updates.
@@ -840,10 +771,7 @@
$this->db->set($object);
$this->db->insert('mytable');
-:returns: The query builder object
-
-$this->db->update()
--------------------
+**$this->db->update()**
Generates an update string and runs the query based on the data you
supply. You can pass an **array** or an **object** to the function. Here
@@ -889,10 +817,7 @@
You may also use the $this->db->set() function described above when
performing updates.
-:returns: DB_query object on success, FALSE on failure
-
-$this->db->update_batch()
--------------------------
+**$this->db->update_batch()**
Generates an update string based on the data you supply, and runs the query.
You can either pass an **array** or an **object** to the function.
@@ -933,10 +858,7 @@
due to the very nature of how it works. Instead, ``update_batch()``
returns the number of rows affected.
-:returns: Count of the number of records affected on success, FALSE on failure
-
-$this->db->get_compiled_update()
---------------------------------
+**$this->db->get_compiled_update()**
This works exactly the same way as ``$this->db->get_compiled_insert()`` except
that it produces an UPDATE SQL string instead of an INSERT SQL string.
@@ -945,14 +867,11 @@
.. note:: This method doesn't work for batched updates.
-:returns: The SQL update string
-
*************
Deleting Data
*************
-$this->db->delete()
--------------------
+**$this->db->delete()**
Generates a delete SQL string and runs the query.
@@ -985,21 +904,14 @@
If you want to delete all data from a table, you can use the truncate()
function, or empty_table().
-:returns: DB_Query on success, FALSE on failure
-
-$this->db->empty_table()
-------------------------
+**$this->db->empty_table()**
Generates a delete SQL string and runs the
query.::
$this->db->empty_table('mytable'); // Produces: DELETE FROM mytable
-:returns: DB_Query on success, FALSE on failure
-
-
-$this->db->truncate()
----------------------
+**$this->db->truncate()**
Generates a truncate SQL string and runs the query.
@@ -1018,19 +930,12 @@
.. note:: If the TRUNCATE command isn't available, truncate() will
execute as "DELETE FROM table".
-:returns: DB_Query on success, FALSE on failure
-
-$this->db->get_compiled_delete()
---------------------------------
+**$this->db->get_compiled_delete()**
This works exactly the same way as ``$this->db->get_compiled_insert()`` except
that it produces a DELETE SQL string instead of an INSERT SQL string.
-For more information view documentation for `$this->db->get_compiled_insert()`_.
-
-:returns: The SQL delete string
-
-
+For more information view documentation for $this->db->get_compiled_insert().
***************
Method Chaining
@@ -1074,8 +979,6 @@
This function deletes all items from the Query Builder cache.
-:returns: void
-
An example of caching
---------------------
@@ -1105,8 +1008,7 @@
Resetting Query Builder
***********************
-$this->db->reset_query()
-------------------------
+**$this->db->reset_query()**
Resetting Query Builder allows you to start fresh with your query without
executing it first using a method like $this->db->get() or $this->db->insert().
@@ -1135,6 +1037,4 @@
.. note:: Double calls to ``get_compiled_select()`` while you're using the
Query Builder Caching functionality and NOT resetting your queries
will results in the cache being merged twice. That in turn will
- i.e. if you're caching a ``select()`` - select the same field twice.
-
-:returns: void
+ i.e. if you're caching a ``select()`` - select the same field twice.
\ No newline at end of file
diff --git a/user_guide_src/source/database/query_builder_reference.rst b/user_guide_src/source/database/query_builder_reference.rst
new file mode 100644
index 0000000..f20a1e7
--- /dev/null
+++ b/user_guide_src/source/database/query_builder_reference.rst
@@ -0,0 +1,23 @@
+#################
+Query Builder API
+#################
+
+.. note:: This page provides a complete API reference for the Query Builder
+ class. For information on how to use the class, see the
+ `Query Builder Class <query_builder.html>`_ page.
+
+***************
+Class Reference
+***************
+
+.. class:: CI_DB_query_builder
+
+ .. method:: count_all_results($table = '')
+
+ :param string $table: Table name to query
+ :returns: Number of rows in the query result
+ :rtype: int
+
+ Generates a platform-specific query string that counts
+ all records returned by an Query Builder query.
+