#include <Wt/DboQuery>
Public Member Functions | |
Query () | |
Default constructor. | |
~Query () | |
Destructor. | |
Query (const Query &other) | |
Copy constructor. | |
Query & | operator= (const Query &other) |
Assignment operator. | |
std::vector< FieldInfo > | fields () const |
Returns the result fields. | |
template<typename T> | |
Query< Result, BindStrategy > & | bind (const T &value) |
Binds a value to the next positional marker. | |
Result | resultValue () const |
Returns a unique result value. | |
collection< Result > | resultList () const |
Returns a result list. | |
operator Result () const | |
Returns a unique result value. | |
operator collection< Result > () const | |
Returns a result list. | |
Methods for composing a query (DynamicBinding only) | |
Query< Result, BindStrategy > & | where (const std::string &condition) |
Adds a query condition. | |
Query< Result, BindStrategy > & | orderBy (const std::string &fieldName) |
Sets the result order. | |
Query< Result, BindStrategy > & | groupBy (const std::string &fields) |
Sets the grouping field(s). | |
Query< Result, BindStrategy > & | offset (int count) |
Sets a result offset. | |
Query< Result, BindStrategy > & | limit (int count) |
Sets a result limit. |
The query fetches results of type Result
from the database. This can be any type for which query_result_traits are properly implemented. The library provides these implementations for primitive values (see sql_value_traits), database objects (ptr) and boost::tuple
.
Simple queries can be done using Session::find(), while more elaborate queries (with arbitrary result types) using Session::query().
You may insert positional holders for parameters (in the conditional where part) using '?', and bind these to actual values using bind().
The query result may be fetched using resultValue() or resultList().
Usage example:
typedef Wt::Dbo::ptr<Account> AccountPtr; typedef Wt::Dbo::collection<AccountPtr> Accounts; Wt::Dbo::Query<AccountPtr> query = session.find<Account>().where("balance > ?").bind(100000); Accounts accounts = query.resultList(); for (Accounts::const_iterator i = accounts.begin(); i != accounts.end(); ++i) std::cerr << "Name: " << i->name << std::end;
The BindStrategy
specifies how you want to bind parameters to your query (if any).
When using DynamicBinding (which is the default), parameter binding to an actual sql statement is deferred until the query is run. This has the advantage that you can compose the query definition using helper methods provided in the query object (where(), orderBy() and groupBy()), possibly intermixing this with parameter binding, and you can keep the query around and run the query multiple times, perhaps with different parameter values or to scroll through the query results.
When using DirectBinding, parameters are directly bound to an underlying sql statement. Therefore, the query must be specified entirely when created. Because of this reliance on an sql statement, it can be run only once (one call to resultValue() or resultList()) after which it should be discarded. You should not try to keep a query object around when using this parameter binding strategy (that will amost always not do what you would hope it to do).
Query<Result, BindStrategy>& Wt::Dbo::Query< Result, BindStrategy >::bind | ( | const T & | value | ) | [inline] |
Binds a value to the next positional marker.
This binds the value
to the next positional marker in the query condition.
Result Wt::Dbo::Query< Result, BindStrategy >::resultValue | ( | ) | const |
Returns a unique result value.
You can use this method if you are expecting the query to return at most one result. If the query returns more than one result a NoUniqueResultException is thrown.
When using a DynamicBinding bind strategy, after a result has been fetched, the query can no longer be used.
collection< Result > Wt::Dbo::Query< Result, BindStrategy >::resultList | ( | ) | const |
Returns a result list.
This returns a collection which is backed by the underlying query. The query is not actually run until this collection is traversed or its size is asked.
When using a DynamicBinding bind strategy, after a result has been fetched, the query can no longer be used.
Wt::Dbo::Query< Result, BindStrategy >::operator Result | ( | ) | const |
Returns a unique result value.
This is a convenience conversion operator that calls resultValue().
Wt::Dbo::Query< Result, BindStrategy >::operator collection< Result > | ( | ) | const |
Returns a result list.
This is a convenience conversion operator that calls resultList().
Query<Result, BindStrategy>& Wt::Dbo::Query< Result, BindStrategy >::where | ( | const std::string & | condition | ) |
Adds a query condition.
The condition must be a valid SQL condition expression.
Multiple conditions may be provided, which must each be fulfilled, and are concatenated together using 'and').
A condition may contain positional markers '?' to which values may be bound using bind().
This provides the where part of an SQL query.
Query<Result, BindStrategy>& Wt::Dbo::Query< Result, BindStrategy >::orderBy | ( | const std::string & | fieldName | ) |
Sets the result order.
Orders the results based on the given field name (or multiple names, comma-separated).
This provides the order by part of an SQL query.
Query<Result, BindStrategy>& Wt::Dbo::Query< Result, BindStrategy >::groupBy | ( | const std::string & | fields | ) |
Sets the grouping field(s).
Groups results based on unique values of the indicated field(s), which is a comma separated list of fields. Only fields on which you group and aggregate functions can be selected by a query.
A field that refers to a database object that is selected by the query is expanded to all the corresponding fields of that database object (as in the select statement).
This provides the group by part of an SQL query.
Query<Result, BindStrategy>& Wt::Dbo::Query< Result, BindStrategy >::offset | ( | int | count | ) |
Sets a result offset.
Sets a result offset. This has the effect that the next resultList() call will skip as many results as the offset indicates. Use -1 to indicate no offset.
This provides the (non standard) offset part of an SQL query.
Query<Result, BindStrategy>& Wt::Dbo::Query< Result, BindStrategy >::limit | ( | int | count | ) |
Sets a result limit.
Sets a result limit. This has the effect that the next resultList() call will return up to count
results. Use -1 to indicate no limit.
This provides the (non standard) limit part of an SQL query.