The query builder also provides a variety of aggregate methods such as count, max, min, and sum. These methods take the headache out of setting up these common aggregate functions.

When executing any of the aggregate functions, any where restrictions on your query will still be applied.

Instead of returning a query, these methods return a simple value.

exists

Returns true if the query returns any rows. Returns false otherwise.

query.from( "users" ).where( "username", "like", "jon%" ).exists();

SELECT COUNT(*) AS aggregate FROM `users` WHERE `username` LIKE 'jon%'

count

Returns an integer number of rows returned by the query.

query.from( "users" ).count();

SELECT COUNT(*) AS aggregate FROM `users`

SELECT COUNT(*) FROM [users]

max

Returns the maximum value for the given column.

query.from( "users" ).max( "age" );

SELECT MAX(age) AS aggregate FROM `users`

min

Returns the minimum value for the given column.

query.from( "users" ).min( "age" );

SELECT MIN(age) AS aggregate FROM `users`

sum

Returns the sum of all returned rows for the given column.

query.from( "employees" ).sum( "salary" );

SELECT SUM(salary) AS aggregate FROM `employees`

get

The get method is the most common method used for retrieving results. It executes using the configured QueryBuilder and returns the results.

query.from( "users" ).get();

SELECT * FROM `users`

get can also take a list or array of columns to use as a shortcut. If any are passed, those columns will be used instead of any columns previously set on the QueryBuilder.

query.from( "users" ).get( [ "id", "name" ] );

SELECT `id`, `name` FROM `users`

first

If you just need to retrieve a single row from the database table, you may use the first method. This method will return a single record (a Struct by default). If no row is found an empty Struct will be returned by default.

query.from( "users" ).first();

SELECT * FROM `users`
 LIMIT(1)

values

If you don't even need an entire row, you may extract a single value from each record using the values method. The values method will return the column of your choosing as a simple array.

query.from( "users" ).values( "firstName" );

[ "jon", "jane", "jill", ... ]

An expression can also be passed to values:

qb.from( "users" ).values( qb.raw( "CONCAT(fname, ' ', lname) AS fullName" ) );

valuesRaw

The values method will return the expression given for each row as a simple array.

query.from( "users" ).valuesRaw( "CONCAT(fname, ' ', lname) AS fullName" );

value

This method is similar to values except it only returns a single, simple value. Where values calls get under the hood, this method calls first.

query.from( "users" ).value( "firstName" );

"jon"

If no records are returned from the query, one of two things will happen. If the throwWhenNotFound boolean is set to true, a RecordCountException will be thrown. Otherwise the defaultValue provided to the method will be returned.

An expression can also be passed to value:

qb.from( "users" ).value( qb.raw( "CONCAT(fname, ' ', lname) AS fullName" ) );

valueRaw

The value method will return the expression given for the first row found.

query.from( "users" ).valueRaw( "CONCAT(fname, ' ', lname) AS fullName" );

chunk

Large datasets can be broken up and retrieved in chunks. This allows you to work with a subset of results at once to keep your memory footprint under control.

chunk can be called on any query like you would call get. You can stop the retrieving and processing early by returning false from the callback.

query.from( "users" ).chunk( 100, function( users ) {
    // Process the users here
    // Returning false from the callback stops processing
} );

paginate

Generates a pagination struct along with the results of the executed query. It does this by calling both count and forPage.

query.from( "users" )
    .paginate();

{
    "pagination": {
        "maxRows": 25,
        "offset": 0,
        "page": 1,
        "totalPages": 2,
        "totalRecords": 45
    },
    "results": [ { /* ... */ }, ]
}

simplePaginate

Generates a simple pagination struct along with the results of the executed query. It does so without getting a count of the number of records the query would return. This can be desirable for performance reasons if your query count is rather large. It instead determines if there are more records by asking for one more row that your specified maxRows. If the number of rows returned exceeds your specified maxRows then the pagination returns hasMore: true. The results will always contain your specified maxRows (or less, if there aren't enough records).

query.from( "users" )
    .simplePaginate();

{
    "pagination": {
        "maxRows": 25,
        "offset": 0,
        "page": 1,
        "hasMore": true
    },
    "results": [ { /* ... */ }, ]
}

Custom Pagination Collectors

A pagination collector is the name given to the struct returned from calling the paginate method. It can be a struct or a component. It needs one function defined and will be passed the following parameters.

generateWithResults

You can set your custom pagination collector either in the constructor using the paginationCollector argument or by calling setPaginationCollector on a query builder instance.

By default, qb ships with cbpaginator as its pagination collector. The return format of cbpaginator is the example shown above.

In qb 8.4.0 the simplePaginate method was added. This uses a new method on the paginationCollector.

generateSimpleWithResults

The following methods all have the same return value:

insert

You can insert a single record by passing a struct:

Raw values can be supplied to an insert statement.

Multiple rows can be inserted in a batch by passing an array of structs to insert.

returning

Specifies columns to be returned from the insert query.

update

Updates a table with a struct of column and value pairs.

You can update a column based on another column using a raw expression.

Updating Null values

Null values can be inserted by using queryparam syntax:

if you are using full null support the following (easier) syntax is also allowed:

Updating with Subselects

Subselects can be used to update values by passing a closure as the value

You can also pass a builder instance in place of the closure.

Updating with Joins

qb will correctly format JOIN clauses in your UPDATE statements for your database grammar.

addUpdate

updateOrInsert

Performs an update statement if the configured query returns true for exists. Otherwise, performs an insert statement.

If an update statement is performed qb applies a limit( 1 ) to the update statement.

If the configured query returns 0 records, then an insert statement is performed.

upsert

An upsert is a batch operation that either inserts or updates a row depending on if a target match is found. If a row is matched with the target column(s), then the matched row is updated. Otherwise a new row is inserted.

The update clause in a upsert can also accept raw values, making it very useful for tracking data like statistics.

delete

Deletes all records that the query returns.

The id argument is a convenience to delete a single record by id.