update to DB docs (refs #4617)

guide/database/query/builder.md

@@ -148,11 +148,11 @@ This query would generate the following SQL:
 
 ### Database Functions
 
-Eventually you will probably run into a situation where you need to call `COUNT` or some other database function within your query. The query builder supports these functions in two ways. The first is by using quotes within aliases:
+Eventually you will probably run into a situation where you need to call `COUNT` or some other database function within your query. The query builder supports these functions using the `Database_Expression` class:
 
-    $query = DB::select(array('COUNT("username")', 'total_users'))->from('users');
+    $query = DB::select(array(DB::expr('COUNT(`username`)'), 'total_users'))->from('users');
 
-This looks almost exactly the same as a standard `AS` alias, but note how the column name is wrapped in double quotes. Any time a double-quoted value appears inside of a column name, **only** the part inside the double quotes will be escaped. This query would generate the following SQL:
+This looks almost exactly the same as a standard `AS` alias, but note how the column name is put in a call to `DB::expr()`. Any time `DB::expr()` is used, the column name will **not** be escaped. This query would generate the following SQL:
 
     SELECT COUNT(`username`) AS `total_users` FROM `users`
 
@@ -164,14 +164,14 @@ This looks almost exactly the same as a standard `AS` alias, but note how the co
         ->where('posts.created', '>=', $yesterday);
 
     $total = clone $query;
-    $total->select(array('COUNT( DISTINCT "username")', 'unique_users'));
+    $total->select(array(DB::expr('COUNT( DISTINCT `username`)'), 'unique_users'));
     $query->select('posts.username')->distinct();
 
 ### Aggregate Functions
 
 Aggregate functions like `COUNT()`, `SUM()`, `AVG()`, etc. will most likely be used with the `group_by()` and possibly the `having()` methods in order to group and filter the results on a set of columns.
 
-    $query = DB::select('username', array('COUNT("id")', 'total_posts')
+    $query = DB::select('username', array(DB::expr('COUNT(`id`)'), 'total_posts')
         ->from('posts')->group_by('username')->having('total_posts', '>=', 10);
 
 This will generate the following query:
@@ -182,7 +182,7 @@ This will generate the following query:
 
 Query Builder objects can be passed as parameters to many of the methods to create subqueries. Let's take the previous example query and pass it to a new query.
 
-    $sub = DB::select('username', array('COUNT("id")', 'total_posts')
+    $sub = DB::select('username', array(DB::expr('COUNT(`id`)'), 'total_posts')
         ->from('posts')->group_by('username')->having('total_posts', '>=', 10);
 
     $query = DB::select('profiles.*', 'posts.total_posts')->from('profiles')
@@ -196,7 +196,7 @@ This will generate the following query:
 
 Insert queries can also use a select query for the input values
 
-    $sub = DB::select('username', array('COUNT("id")', 'total_posts')
+    $sub = DB::select('username', array(DB::expr('COUNT(`id`)'), 'total_posts')
         ->from('posts')->group_by('username')->having('total_posts', '>=', 10);
 
     $query = DB::insert('post_totals', array('username', 'posts'))->select($sub);