T
- the type of Entity bean this query will fetch.public interface Query<T>
Example: Create the query using the API.
List<Order> orderList = DB.find(Order.class)
.where()
.like("customer.name","rob%")
.gt("orderDate",lastWeek)
.orderBy("customer.id, id desc")
.setMaxRows(50)
.findList();
...
Example: The same query using the query language
String oql =
+" where customer.name like :custName and orderDate > :minOrderDate "
+" order by customer.id, id desc "
+" limit 50 ";
List<Order> orderList = DB.createQuery(Order.class, oql)
.setParameter("custName", "Rob%")
.setParameter("minOrderDate", lastWeek)
.findList();
...
Ebean has built in support for "AutoTune". This is a mechanism where a query can be automatically tuned based on profiling information that is collected.
This is effectively the same as automatically using select() and fetch() to build a query that will fetch all the data required by the application and no more.
It is expected that AutoTune will be the default approach for many queries in a system. It is possibly not as useful where the result of a query is sent to a remote client or where there is some requirement for "Read Consistency" guarantees.
Partial Objects
The find and fetch clauses support specifying a list of properties to fetch. This results in objects that are "partially populated". If you try to get a property that was not populated a "lazy loading" query will automatically fire and load the rest of the properties of the bean (This is very similar behaviour as a reference object being "lazy loaded").
Partial objects can be saved just like fully populated objects. If you do this you should remember to include the "Version" property in the initial fetch. If you do not include a version property then optimistic concurrency checking will occur but only include the fetched properties. Refer to "ALL Properties/Columns" mode of Optimistic Concurrency checking.
[ select [ ( * | {fetch properties} ) ] ]
[ fetch {path} [ ( * | {fetch properties} ) ] ]
[ where {predicates} ]
[ order by {order by properties} ]
[ limit {max rows} [ offset {first row} ] ]
SELECT [ ( * | {fetch properties} ) ]
With the select you can specify a list of properties to fetch.
FETCH {path} [ ( * | {fetch properties} ) ]
With the fetch you specify the associated property to fetch and populate. The path is a OneToOne, ManyToOne, OneToMany or ManyToMany property.
For fetch of a path we can optionally specify a list of properties to fetch. If you do not specify a list of properties ALL the properties for that bean type are fetched.
WHERE {list of predicates}
The list of predicates which are joined by AND OR NOT ( and ). They can
include named (or positioned) bind parameters. These parameters will need to
be bound by setParameter(String, Object)
.
ORDER BY {order by properties}
The list of properties to order the result. You can include ASC (ascending) and DESC (descending) in the order by clause.
LIMIT {max rows} [ OFFSET {first row} ]
The limit offset specifies the max rows and first row to fetch. The offset is optional.
Find orders fetching its id, shipDate and status properties. Note that the id property is always fetched even if it is not included in the list of fetch properties.
select (shipDate, status)
Find orders with a named bind variable (that will need to be bound via
setParameter(String, Object)
).
where customer.name like :custLike
Find orders and also fetch the customer with a named bind parameter. This will fetch and populate both the order and customer objects.
fetch customer
where customer.id = :custId
Find orders and also fetch the customer, customer shippingAddress, order details and related product. Note that customer and product objects will be "Partial Objects" with only some of their properties populated. The customer objects will have their id, name and shipping address populated. The product objects (associated with each order detail) will have their id, sku and name populated.
fetch customer (name)
fetch customer.shippingAddress
fetch details
fetch details.product (sku, name)
Modifier and Type | Interface and Description |
---|---|
static class |
Query.ForUpdate
For update mode.
|
Modifier and Type | Method and Description |
---|---|
Query<T> |
alias(String alias)
Set root table alias.
|
Query<T> |
apply(FetchPath fetchPath)
Apply the path properties replacing the select and fetch clauses.
|
Query<T> |
asDraft()
Execute the query against the draft set of tables.
|
<D> DtoQuery<D> |
asDto(Class<D> dtoClass)
Convert the query to a DTO bean query.
|
Query<T> |
asOf(Timestamp asOf)
Perform an 'As of' query using history tables to return the object graph
as of a time in the past.
|
UpdateQuery<T> |
asUpdate()
Convert the query to a UpdateQuery.
|
void |
cancel()
Cancel the query execution if supported by the underlying database and
driver.
|
Query<T> |
copy()
Return a copy of the query.
|
int |
delete()
Execute as a delete query deleting the 'root level' beans that match the predicates
in the query.
|
int |
delete(Transaction transaction)
Execute as a delete query returning the number of rows deleted using the given transaction.
|
boolean |
exists()
Execute the query returning true if a row is found.
|
Query<T> |
fetch(String path)
Specify a path to fetch eagerly including all its properties.
|
Query<T> |
fetch(String path,
FetchConfig fetchConfig)
Additionally specify a JoinConfig to specify a "query join" and or define
the lazy loading query.
|
Query<T> |
fetch(String path,
String fetchProperties)
Specify a path to fetch eagerly including specific properties.
|
Query<T> |
fetch(String path,
String fetchProperties,
FetchConfig fetchConfig)
Additionally specify a FetchConfig to use a separate query or lazy loading
to load this path.
|
Query<T> |
fetchLazy(String path)
Fetch the path lazily (via batch lazy loading).
|
Query<T> |
fetchLazy(String path,
String fetchProperties)
Fetch the path and properties lazily (via batch lazy loading).
|
Query<T> |
fetchQuery(String path)
Fetch the path eagerly using a "query join" (separate SQL query).
|
Query<T> |
fetchQuery(String path,
String fetchProperties)
Fetch the path and properties using a "query join" (separate SQL query).
|
ExpressionList<T> |
filterMany(String propertyName)
This applies a filter on the 'many' property list rather than the root
level objects.
|
int |
findCount()
Return the count of entities this query should return.
|
void |
findEach(java.util.function.Consumer<T> consumer)
Execute the query processing the beans one at a time.
|
void |
findEachWhile(java.util.function.Predicate<T> consumer)
Execute the query using callbacks to a visitor to process the resulting
beans one at a time.
|
FutureRowCount<T> |
findFutureCount()
Execute find row count query in a background thread.
|
FutureIds<T> |
findFutureIds()
Execute find Id's query in a background thread.
|
FutureList<T> |
findFutureList()
Execute find list query in a background thread.
|
<A> List<A> |
findIds()
Execute the query returning the list of Id's.
|
QueryIterator<T> |
findIterate()
Execute the query iterating over the results.
|
List<T> |
findList()
Execute the query returning the list of objects.
|
<K> Map<K,T> |
findMap()
Execute the query returning a map of the objects.
|
T |
findOne()
Execute the query returning either a single bean or null (if no matching
bean is found).
|
Optional<T> |
findOneOrEmpty()
Execute the query returning an optional bean.
|
PagedList<T> |
findPagedList()
Return a PagedList for this query using firstRow and maxRows.
|
Set<T> |
findSet()
Execute the query returning the set of objects.
|
<A> A |
findSingleAttribute()
Execute a query returning a single value of a single property/column.
|
<A> List<A> |
findSingleAttributeList()
Execute the query returning a list of values for a single property.
|
List<Version<T>> |
findVersions()
Return versions of a @History entity bean.
|
List<Version<T>> |
findVersionsBetween(Timestamp start,
Timestamp end)
Return versions of a @History entity bean between the 2 timestamps.
|
Query<T> |
forUpdate()
Execute using "for update" clause which results in the DB locking the record.
|
Query<T> |
forUpdateNoWait()
Execute using "for update" clause with "no wait" option.
|
Query<T> |
forUpdateSkipLocked()
Execute using "for update" clause with "skip locked" option.
|
Class<T> |
getBeanType()
Return the type of beans being queried.
|
ExpressionFactory |
getExpressionFactory()
Return the ExpressionFactory used by this query.
|
int |
getFirstRow()
Return the first row value.
|
Query.ForUpdate |
getForUpdateMode()
Return the "for update" mode to use.
|
String |
getGeneratedSql()
Return the sql that was generated for executing this query.
|
Object |
getId()
Return the Id value.
|
Class<? extends T> |
getInheritType()
Returns the inherit type.
|
int |
getMaxRows()
Return the max rows for this query.
|
QueryType |
getQueryType()
Return the type of query being executed.
|
ExpressionList<T> |
having()
Add Expressions to the Having clause return the ExpressionList.
|
Query<T> |
having(Expression addExpressionToHaving)
Add an expression to the having clause returning the query.
|
boolean |
isAutoTuned()
Returns true if this query was tuned by autoTune.
|
boolean |
isCountDistinct()
Return true if this is countDistinct query.
|
boolean |
isForUpdate()
Return true if this query has forUpdate set.
|
OrderBy<T> |
order()
Return the OrderBy so that you can append an ascending or descending
property to the order by clause.
|
Query<T> |
order(String orderByClause)
Set the order by clause replacing the existing order by clause if there is
one.
|
OrderBy<T> |
orderBy()
Return the OrderBy so that you can append an ascending or descending
property to the order by clause.
|
Query<T> |
orderBy(String orderByClause)
Set the order by clause replacing the existing order by clause if there is
one.
|
Query<T> |
orderById(boolean orderById)
Controls, if paginated queries should always append an 'order by id' statement at the end to
guarantee a deterministic sort result.
|
Query<T> |
select(FetchGroup<T> fetchGroup)
Apply the fetchGroup which defines what part of the object graph to load.
|
Query<T> |
select(String fetchProperties)
Specify the properties to fetch on the root level entity bean in comma delimited format.
|
Query<T> |
setAllowLoadErrors()
Execute the query allowing properties with invalid JSON to be collected and not fail the query.
|
Query<T> |
setAutoTune(boolean autoTune)
Explicitly specify whether to use AutoTune for this query.
|
Query<T> |
setBaseTable(String baseTable)
Set the base table to use for this query.
|
Query<T> |
setBeanCacheMode(CacheMode beanCacheMode)
Set the mode to use the bean cache when executing this query.
|
Query<T> |
setBufferFetchSizeHint(int fetchSize)
A hint which for JDBC translates to the Statement.fetchSize().
|
Query<T> |
setCountDistinct(CountDistinctOrder orderBy)
Extended version for setDistinct in conjunction with "findSingleAttributeList";
|
Query<T> |
setDisableLazyLoading(boolean disableLazyLoading)
Set true if you want to disable lazy loading.
|
Query<T> |
setDisableReadAuditing()
Disable read auditing for this query.
|
Query<T> |
setDistinct(boolean isDistinct)
Set whether this query uses DISTINCT.
|
Query<T> |
setDocIndexName(String indexName)
Set the index(es) to search for a document store which uses partitions.
|
Query<T> |
setFirstRow(int firstRow)
Set the first row to return for this query.
|
Query<T> |
setId(Object id)
Set the Id value to query.
|
Query<T> |
setIncludeSoftDeletes()
Execute the query including soft deleted rows.
|
Query<T> |
setInheritType(Class<? extends T> type)
Restrict the query to only return subtypes of the given inherit type.
|
Query<T> |
setLabel(String label)
Set a label on the query.
|
Query<T> |
setLazyLoadBatchSize(int lazyLoadBatchSize)
Set the default lazy loading batch size to use.
|
Query<T> |
setLoadBeanCache(boolean loadBeanCache)
Will be deprecated - migrate to use setBeanCacheMode(CacheMode.RECACHE).
|
Query<T> |
setMapKey(String mapKey)
Set the property to use as keys for a map.
|
Query<T> |
setMaxRows(int maxRows)
Set the maximum number of rows to return in the query.
|
Query<T> |
setOrder(OrderBy<T> orderBy)
Set an OrderBy object to replace any existing OrderBy clause.
|
Query<T> |
setOrderBy(OrderBy<T> orderBy)
Set an OrderBy object to replace any existing OrderBy clause.
|
Query<T> |
setParameter(int position,
Object value)
Set an ordered bind parameter according to its position.
|
Query<T> |
setParameter(String name,
Object value)
Set a named bind parameter.
|
Query<T> |
setPersistenceContextScope(PersistenceContextScope scope)
Specify the PersistenceContextScope to use for this query.
|
Query<T> |
setProfileId(int profileId)
Set an id to identify this query for profiling purposes.
|
Query<T> |
setProfileLocation(ProfileLocation profileLocation)
Set the profile location of this query.
|
Query<T> |
setRawSql(RawSql rawSql)
Set RawSql to use for this query.
|
Query<T> |
setReadOnly(boolean readOnly)
When set to true when you want the returned beans to be read only.
|
Query<T> |
setTimeout(int secs)
Set a timeout on this query.
|
default Query<T> |
setUseCache(boolean useCache)
Set this to false to not use the bean cache.
|
Query<T> |
setUseDocStore(boolean useDocStore)
Set to true if this query should execute against the doc store.
|
default Query<T> |
setUseQueryCache(boolean enabled)
|
Query<T> |
setUseQueryCache(CacheMode queryCacheMode)
Set the
CacheMode to use the query for executing this query. |
ExpressionList<T> |
text()
Add Full text search expressions for Document store queries.
|
int |
update()
Execute the UpdateQuery returning the number of rows updated.
|
int |
update(Transaction transaction)
Execute the UpdateQuery returning the number of rows updated using the given transaction.
|
Set<String> |
validate()
Returns the set of properties or paths that are unknown (do not map to known properties or paths).
|
ExpressionList<T> |
where()
Add Expressions to the where clause with the ability to chain on the
ExpressionList.
|
Query<T> |
where(Expression expression)
Add a single Expression to the where clause returning the query.
|
Query<T> asOf(Timestamp asOf)
To perform this query the DB must have underlying history tables.
asOf
- the date time in the past at which you want to view the data<D> DtoQuery<D> asDto(Class<D> dtoClass)
We effectively use the underlying ORM query to build the SQL and then execute and map it into DTO beans.
UpdateQuery<T> asUpdate()
Typically this is used with query beans to covert a query bean query into an UpdateQuery like the examples below.
int rowsUpdated = new QCustomer()
.name.startsWith("Rob")
.asUpdate()
.set("active", false)
.update();;
int rowsUpdated = new QContact()
.notes.note.startsWith("Make Inactive")
.email.endsWith("@foo.com")
.customer.id.equalTo(42)
.asUpdate()
.set("inactive", true)
.setRaw("email = lower(email)")
.update();
void cancel()
This must be called from a different thread to the query executor.
Query<T> copy()
This is so that you can use a Query as a "prototype" for creating other query instances. You could create a Query with various where expressions and use that as a "prototype" - using this copy() method to create a new instance that you can then add other expressions then execute.
Query<T> setPersistenceContextScope(PersistenceContextScope scope)
ServerConfig.setPersistenceContextScope(PersistenceContextScope)
is used - this value defaults to PersistenceContextScope.TRANSACTION
.
Note that the same persistence Context is used for subsequent lazy loading and query join queries.
Note that #findEach uses a 'per object graph' PersistenceContext so this scope is ignored for
queries executed as #findIterate, #findEach, #findEachWhile.scope
- The scope to use for this query and subsequent lazy loading.Query<T> setDocIndexName(String indexName)
For example, when executing a query against ElasticSearch with daily indexes we can explicitly specify the indexes to search against.
// explicitly specify the indexes to search
query.setDocIndexName("logstash-2016.11.5,logstash-2016.11.6")
// search today's index
query.setDocIndexName("$today")
// search the last 3 days
query.setDocIndexName("$last-3")
If the indexName is specified with ${daily} e.g. "logstash-${daily}" ... then we can use $today and $last-x as the search docIndexName like the examples below.
// search today's index
query.setDocIndexName("$today")
// search the last 3 days
query.setDocIndexName("$last-3")
indexName
- The index or indexes to search againstExpressionFactory getExpressionFactory()
boolean isAutoTuned()
Query<T> setAutoTune(boolean autoTune)
If you do not call this method on a query the "Implicit AutoTune mode" is used to determine if AutoTune should be used for a given query.
AutoTune can add additional fetch paths to the query and specify which properties are included for each path. If you have explicitly defined some fetch paths AutoTune will not remove them.
Query<T> setAllowLoadErrors()
// fetch a bean with JSON content
EBasicJsonList bean= DB.find(EBasicJsonList.class)
.setId(42)
.setAllowLoadErrors() // collect errors into bean state if we have invalid JSON
.findOne();
// get the invalid JSON errors from the bean state
Map<String, Exception> errors = server().getBeanState(bean).getLoadErrors();
// If this map is not empty tell we have invalid JSON
// and should try and fix the JSON content or inform the user
Query<T> setLazyLoadBatchSize(int lazyLoadBatchSize)
When lazy loading is invoked on beans loaded by this query then this sets the batch size used to load those beans.
lazyLoadBatchSize
- the number of beans to lazy load in a single batchQuery<T> setIncludeSoftDeletes()
This means that Ebean will not add any predicates to the query for filtering out soft deleted rows. You can still add your own predicates for the deleted properties and effectively you have full control over the query to include or exclude soft deleted rows as needed for a given use case.
Query<T> setDisableReadAuditing()
This is intended to be used when the query is not a user initiated query and instead part of the internal processing in an application to load a cache or document store etc. In these cases we don't want the query to be part of read auditing.
Query<T> select(String fetchProperties)
The Id property is automatically included in the properties to fetch unless setDistinct(true) is set on the query.
Use fetch(String, String)
to specify specific properties to fetch
on other non-root level paths of the object graph.
List<Customer> customers = DB.find(Customer.class)
// Only fetch the customer id, name and status.
// This is described as a "Partial Object"
.select("name, status")
.where.ilike("name", "rob%")
.findList();
fetchProperties
- the properties to fetch for this bean (* = all properties).Query<T> select(FetchGroup<T> fetchGroup)
Query<T> fetch(String path, String fetchProperties)
Ebean will endeavour to fetch this path using a SQL join. If Ebean determines that it can not use a SQL join (due to maxRows or because it would result in a cartesian product) Ebean will automatically convert this fetch query into a "query join" - i.e. use fetchQuery().
// query orders...
List<Order> orders = DB.find(Order.class)
// fetch the customer...
// ... getting the customers name and phone number
.fetch("customer", "name, phoneNumber")
// ... also fetch the customers billing address (* = all properties)
.fetch("customer.billingAddress", "*")
.findList();
If columns is null or "*" then all columns/properties for that path are fetched.
// fetch customers (their id, name and status)
List<Customer> customers = DB.find(Customer.class)
.select("name, status")
.fetch("contacts", "firstName,lastName,email")
.findList();
path
- the property path we wish to fetch eagerly.fetchProperties
- properties of the associated bean that you want to include in the
fetch (* means all properties, null also means all properties).Query<T> fetchQuery(String path, String fetchProperties)
This is the same as:
fetch(path, fetchProperties, new FetchConfig().query())
This would be used instead of a fetch() when we use a separate SQL query to fetch this part of the object graph rather than a SQL join.
We might typically get a performance benefit when the path to fetch is a OneToMany or ManyToMany, the 'width' of the 'root bean' is wide and the cardinality of the many is high.
path
- the property path we wish to fetch eagerly.fetchProperties
- properties of the associated bean that you want to include in the
fetch (* means all properties, null also means all properties).Query<T> fetchLazy(String path, String fetchProperties)
This is the same as:
fetch(path, fetchProperties, new FetchConfig().lazy())
The reason for using fetchLazy() is to either:
path
- the property path we wish to fetch lazily.fetchProperties
- properties of the associated bean that you want to include in the
fetch (* means all properties, null also means all properties).Query<T> fetch(String path, String fetchProperties, FetchConfig fetchConfig)
// fetch customers (their id, name and status)
List<Customer> customers = DB.find(Customer.class)
.select("name, status")
.fetch("contacts", "firstName,lastName,email", new FetchConfig().lazy(10))
.findList();
path
- the property path we wish to fetch eagerly.Query<T> fetch(String path)
Ebean will endeavour to fetch this path using a SQL join. If Ebean determines that it can not use a SQL join (due to maxRows or because it would result in a cartesian product) Ebean will automatically convert this fetch query into a "query join" - i.e. use fetchQuery().
// fetch customers (their id, name and status)
List<Customer> customers = DB.find(Customer.class)
// eager fetch the contacts
.fetch("contacts")
.findList();
path
- the property path we wish to fetch eagerly.Query<T> fetchQuery(String path)
This is the same as:
fetch(path, new FetchConfig().query())
This would be used instead of a fetch() when we use a separate SQL query to fetch this part of the object graph rather than a SQL join.
We might typically get a performance benefit when the path to fetch is a OneToMany or ManyToMany, the 'width' of the 'root bean' is wide and the cardinality of the many is high.
path
- the property path we wish to fetch eagerlyQuery<T> fetchLazy(String path)
This is the same as:
fetch(path, new FetchConfig().lazy())
The reason for using fetchLazy() is to either:
path
- the property path we wish to fetch lazily.Query<T> fetch(String path, FetchConfig fetchConfig)
// fetch customers (their id, name and status)
List<Customer> customers = DB.find(Customer.class)
// lazy fetch contacts with a batch size of 100
.fetch("contacts", new FetchConfig().lazy(100))
.findList();
Query<T> apply(FetchPath fetchPath)
This is typically used when the FetchPath is applied to both the query and the JSON output.
@Nonnull <A> List<A> findIds()
This query will execute against the EbeanServer that was used to create it.
@Nonnull QueryIterator<T> findIterate()
Note that findIterate (and findEach and findEachWhile) uses a "per graph" persistence context scope and adjusts jdbc fetch buffer size for large queries. As such it is better to use findList for small queries.
Remember that with QueryIterator
you must call QueryIterator.close()
when you have finished iterating the results (typically in a finally block).
findEach() and findEachWhile() are preferred to findIterate() as they ensure the jdbc statement and resultSet are closed at the end of the iteration.
This query will execute against the EbeanServer that was used to create it.
Query<Customer> query = DB.find(Customer.class)
.where().eq("status", Status.NEW)
.order().asc("id");
// use try with resources to ensure QueryIterator is closed
try (QueryIterator<Customer> it = query.findIterate()) {
while (it.hasNext()) {
Customer customer = it.next();
// do something with customer ...
}
}
void findEach(java.util.function.Consumer<T> consumer)
This method is appropriate to process very large query results as the beans are consumed one at a time and do not need to be held in memory (unlike #findList #findSet etc)
Note that findEach (and findEachWhile and findIterate) uses a "per graph" persistence context scope and adjusts jdbc fetch buffer size for large queries. As such it is better to use findList for small queries.
Note that internally Ebean can inform the JDBC driver that it is expecting larger resultSet and specifically for MySQL this hint is required to stop it's JDBC driver from buffering the entire resultSet. As such, for smaller resultSets findList() is generally preferable.
Compared with #findEachWhile this will always process all the beans where as #findEachWhile provides a way to stop processing the query result early before all the beans have been read.
This method is functionally equivalent to findIterate() but instead of using an iterator uses the Consumer interface which is better suited to use with Java8 closures.
DB.find(Customer.class)
.where().eq("status", Status.NEW)
.order().asc("id")
.findEach((Customer customer) -> {
// do something with customer
System.out.println("-- visit " + customer);
});
consumer
- the consumer used to process the queried beans.void findEachWhile(java.util.function.Predicate<T> consumer)
Note that findEachWhile (and findEach and findIterate) uses a "per graph" persistence context scope and adjusts jdbc fetch buffer size for large queries. As such it is better to use findList for small queries.
This method is functionally equivalent to findIterate() but instead of using an iterator uses the Predicate (SAM) interface which is better suited to use with Java8 closures.
DB.find(Customer.class)
.fetch("contacts", new FetchConfig().query(2))
.where().eq("status", Status.NEW)
.order().asc("id")
.setMaxRows(2000)
.findEachWhile((Customer customer) -> {
// do something with customer
System.out.println("-- visit " + customer);
// return true to continue processing or false to stop
return (customer.getId() < 40);
});
consumer
- the consumer used to process the queried beans.@Nonnull List<T> findList()
This query will execute against the EbeanServer that was used to create it.
List<Customer> customers = DB.find(Customer.class)
.where().ilike("name", "rob%")
.findList();
@Nonnull Set<T> findSet()
This query will execute against the EbeanServer that was used to create it.
Set<Customer> customers = DB.find(Customer.class)
.where().ilike("name", "rob%")
.findSet();
@Nonnull <K> Map<K,T> findMap()
This query will execute against the EbeanServer that was used to create it.
You can use setMapKey() so specify the property values to be used as keys on the map. If one is not specified then the id property is used.
Map<String, Product> map = DB.find(Product.class)
.setMapKey("sku")
.findMap();
@Nonnull <A> List<A> findSingleAttributeList()
List<String> names =
DB.find(Customer.class)
.select("name")
.orderBy().asc("name")
.findSingleAttributeList();
List<String> names =
DB.find(Customer.class)
.setDistinct(true)
.select("name")
.where().eq("status", Customer.Status.NEW)
.orderBy().asc("name")
.setMaxRows(100)
.findSingleAttributeList();
<A> A findSingleAttribute()
String name =
DB.find(Customer.class)
.select("name")
.where().eq("id", 42)
.findSingleAttribute();
boolean isCountDistinct()
boolean exists()
The query is executed using max rows of 1 and will only select the id property. This method is really just a convenient way to optimise a query to perform a 'does a row exist in the db' check.
boolean userExists =
new QContact()
.email.equalTo("rob@foo.com")
.exists();
boolean userExists = query()
.where().eq("email", "rob@foo.com")
.exists();
@Nullable T findOne()
If more than 1 row is found for this query then a NonUniqueResultException is thrown.
This is useful when your predicates dictate that your query should only return 0 or 1 results.
// assuming the sku of products is unique...
Product product = DB.find(Product.class)
.where().eq("sku", "aa113")
.findOne();
...
It is also useful with finding objects by their id when you want to specify further join information.
// Fetch order 1 and additionally fetch join its order details...
Order order = DB.find(Order.class)
.setId(1)
.fetch("details")
.findOne();
// the order details were eagerly loaded
List<OrderDetail> details = order.getDetails();
...
javax.persistence.NonUniqueResultException
- if more than one result was found@Nonnull Optional<T> findOneOrEmpty()
@Nonnull List<Version<T>> findVersions()
Note that this query will work against view based history implementations but not sql2011 standards based implementations that require a start and end timestamp to be specified.
Generally this query is expected to be a find by id or unique predicates query. It will execute the query against the history returning the versions of the bean.
@Nonnull List<Version<T>> findVersionsBetween(Timestamp start, Timestamp end)
Generally this query is expected to be a find by id or unique predicates query. It will execute the query against the history returning the versions of the bean.
int delete()
Note that if the query includes joins then the generated delete statement may not be optimal depending on the database platform.
int delete(Transaction transaction)
Note that if the query includes joins then the generated delete statement may not be optimal depending on the database platform.
int update()
int update(Transaction transaction)
int findCount()
This is the number of 'top level' or 'root level' entities.
@Nonnull FutureRowCount<T> findFutureCount()
This returns a Future object which can be used to cancel, check the execution status (isDone etc) and get the value (with or without a timeout).
@Nonnull FutureIds<T> findFutureIds()
This returns a Future object which can be used to cancel, check the execution status (isDone etc) and get the value (with or without a timeout).
@Nonnull FutureList<T> findFutureList()
This query will execute in it's own PersistenceContext and using its own transaction. What that means is that it will not share any bean instances with other queries.
@Nonnull PagedList<T> findPagedList()
The benefit of using this over findList() is that it provides functionality to get the total row count etc.
If maxRows is not set on the query prior to calling findPagedList() then a PersistenceException is thrown.
PagedList<Order> pagedList = DB.find(Order.class)
.setFirstRow(50)
.setMaxRows(20)
.findPagedList();
// fetch the total row count in the background
pagedList.loadRowCount();
List<Order> orders = pagedList.getList();
int totalRowCount = pagedList.getTotalRowCount();
Query<T> setParameter(String name, Object value)
// a query with a named parameter
String oql = "find order where status = :orderStatus";
List<Order> list = DB.find(Order.class, oql)
.setParameter("orderStatus", OrderStatus.NEW)
.findList();
name
- the parameter namevalue
- the parameter valueQuery<T> setParameter(int position, Object value)
// a query with a positioned parameter
String oql = "where status = ? order by id desc";
List<Order> list = DB.createQuery(Order.class, oql)
.setParameter(1, OrderStatus.NEW)
.findList();
position
- the parameter bind position starting from 1 (not 0)value
- the parameter bind value.Query<T> setId(Object id)
You can use this to have further control over the query. For example adding fetch joins.
Order order = DB.find(Order.class)
.setId(1)
.fetch("details")
.findOne();
// the order details were eagerly fetched
List<OrderDetail> details = order.getDetails();
Query<T> where(Expression expression)
List<Order> newOrders = DB.find(Order.class)
.where().eq("status", Order.NEW)
.findList();
...
ExpressionList<T> where()
List<Order> orders = DB.find(Order.class)
.where()
.eq("status", Order.NEW)
.ilike("customer.name","rob%")
.findList();
Expr
ExpressionList<T> text()
This is currently ElasticSearch only and provides the full text expressions such as Match and Multi-Match.
This automatically makes this query a "Doc Store" query and will execute against the document store (ElasticSearch).
Expressions added here are added to the "query" section of an ElasticSearch query rather than the "filter" section.
Expressions added to the where() are added to the "filter" section of an ElasticSearch query.
ExpressionList<T> filterMany(String propertyName)
Typically you will use this in a scenario where the cardinality is high on the 'many' property you wish to join to. Say you want to fetch customers and their associated orders... but instead of getting all the orders for each customer you only want to get the new orders they placed since last week. In this case you can use filterMany() to filter the orders.
List<Customer> list = DB.find(Customer.class)
.fetch("orders")
.where().ilike("name", "rob%")
.filterMany("orders").eq("status", Order.Status.NEW).gt("orderDate", lastWeek)
.findList();
Please note you have to be careful that you add expressions to the correct expression list - as there is one for the 'root level' and one for each filterMany that you have.
propertyName
- the name of the many property that you want to have a filter on.ExpressionList<T> having()
Currently only beans based on raw sql will use the having clause.
Note that this returns the ExpressionList (so you can add multiple expressions to the query in a fluent API way).
Expr
Query<T> having(Expression addExpressionToHaving)
Currently only beans based on raw sql will use the having clause.
This is similar to having()
except it returns the query rather
than the ExpressionList. This is useful when you want to further specify
something on the query.
addExpressionToHaving
- the expression to add to the having clause.Query<T> orderBy(String orderByClause)
This follows SQL syntax using commas between each property with the optional asc and desc keywords representing ascending and descending order respectively.
This is EXACTLY the same as order(String)
.
Query<T> order(String orderByClause)
This follows SQL syntax using commas between each property with the optional asc and desc keywords representing ascending and descending order respectively.
This is EXACTLY the same as orderBy(String)
.
OrderBy<T> order()
This will never return a null. If no order by clause exists then an 'empty' OrderBy object is returned.
This is EXACTLY the same as orderBy()
.
OrderBy<T> orderBy()
This will never return a null. If no order by clause exists then an 'empty' OrderBy object is returned.
This is EXACTLY the same as order()
.
Query<T> setOrder(OrderBy<T> orderBy)
This is EXACTLY the same as setOrderBy(OrderBy)
.
Query<T> setOrderBy(OrderBy<T> orderBy)
This is EXACTLY the same as setOrder(OrderBy)
.
Query<T> setDistinct(boolean isDistinct)
The select() clause MUST be specified when setDistinct(true) is set. The reason for this is that generally ORM queries include the "id" property and this doesn't make sense for distinct queries.
List<Customer> customers =
DB.find(Customer.class)
.setDistinct(true)
.select("name")
.findList();
Query<T> setCountDistinct(CountDistinctOrder orderBy)
List<CountedValue<Order.Status>> orderStatusCount =
DB.find(Order.class)
.select("status")
.where()
.gt("orderDate", LocalDate.now().minusMonths(3))
// fetch as single attribute with a COUNT
.setCountDistinct(CountDistinctOrder.COUNT_DESC_ATTR_ASC)
.findSingleAttributeList();
for (CountedValue<Order.Status> entry : orderStatusCount) {
System.out.println(" count:" + entry.getCount()+" orderStatus:" + entry.getValue() );
}
// produces
count:3 orderStatus:NEW
count:1 orderStatus:SHIPPED
count:1 orderStatus:COMPLETE
int getFirstRow()
Query<T> setFirstRow(int firstRow)
firstRow
- the first row to include in the query result.int getMaxRows()
Query<T> setMaxRows(int maxRows)
maxRows
- the maximum number of rows to return in the query.Query<T> setMapKey(String mapKey)
If no property is set then the id property is used.
// Assuming sku is unique for products...
Map<String,Product> productMap = DB.find(Product.class)
.setMapKey("sku") // sku map keys...
.findMap();
mapKey
- the property to use as keys for a map.default Query<T> setUseCache(boolean useCache)
This method is now superseded by setBeanCacheMode(CacheMode)
which provides more explicit options controlled bean cache use.
This method is likely to be deprecated in the future with migration over to setUseBeanCache().
Query<T> setBeanCacheMode(CacheMode beanCacheMode)
By default "find by id" and "find by natural key" will use the bean cache when bean caching is enabled. Setting this to false means that the query will not use the bean cache and instead hit the database.
By default findList() with natural keys will not use the bean cache. In that case we need to explicitly use the bean cache.
Query<T> setUseQueryCache(CacheMode queryCacheMode)
CacheMode
to use the query for executing this query.default Query<T> setUseQueryCache(boolean enabled)
Query<T> setProfileId(int profileId)
The profileId is expected to be unique for a given bean type.
Note that the profileId is treated as a short internally and has a MAX value of 32,767.
Query<T> setProfileLocation(ProfileLocation profileLocation)
Query<T> setLabel(String label)
This label can be used to help identify query performance metrics but we can also use profile location enhancement on Finders so for some that would be a better option.
Query<T> setUseDocStore(boolean useDocStore)
When setting this you may also consider disabling lazy loading.
Query<T> setReadOnly(boolean readOnly)
Query<T> setLoadBeanCache(boolean loadBeanCache)
When set to true all the beans from this query are loaded into the bean cache.
Query<T> setTimeout(int secs)
This will typically result in a call to setQueryTimeout() on a preparedStatement. If the timeout occurs an exception will be thrown - this will be a SQLException wrapped up in a PersistenceException.
secs
- the query timeout limit in seconds. Zero means there is no limit.Query<T> setBufferFetchSizeHint(int fetchSize)
Gives the JDBC driver a hint as to the number of rows that should be fetched from the database when more rows are needed for ResultSet.
Note that internally findEach and findEachWhile will set the fetch size if it has not already as these queries expect to process a lot of rows. If we didn't then Postgres and MySql for example would eagerly pull back all the row data and potentially consume a lot of memory in the process.
As findEach and findEachWhile automatically set the fetch size we don't have to do so generally but we might still wish to for tuning a specific use case.
String getGeneratedSql()
This is only available after the query has been executed and provided only for informational purposes.
Query<T> forUpdate()
Query<T> forUpdateNoWait()
This is typically a Postgres and Oracle only option at this stage.
Query<T> forUpdateSkipLocked()
This is typically a Postgres and Oracle only option at this stage.
boolean isForUpdate()
Query.ForUpdate getForUpdateMode()
Query<T> setBaseTable(String baseTable)
Typically this is used when a table has partitioning and we wish to specify a specific partition/table to query against.
QOrder()
.setBaseTable("order_2019_05")
.status.equalTo(Status.NEW)
.findList();
Class<T> getBeanType()
Query<T> setInheritType(Class<? extends T> type)
List<Animal> animals =
new QAnimal()
.name.startsWith("Fluffy")
.setInheritType(Cat.class)
.findList();
type
- An inheritance subtype of theClass<? extends T> getInheritType()
QueryType getQueryType()
Query<T> setDisableLazyLoading(boolean disableLazyLoading)
That is, once the object graph is returned further lazy loading is disabled.
Set<String> validate()
Validate the query checking the where and orderBy expression paths to confirm if they represent valid properties or paths for the given bean type.
Query<T> orderById(boolean orderById)
Copyright © 2019. All rights reserved.