com.avaje.ebean

Interface Query<T>

Type Parameters:

T - the type of Entity bean this query will fetch.

public interface Query<T>

Object relational query for finding a List, Set, Map or single entity bean.

Example: Create the query using the API.

List<Order> orderList =
  ebeanServer.find(Order.class)
    .fetch("customer")
    .fetch("details")
    .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 =
        +" fetch customer "
        +" fetch details "
        +" where customer.name like :custName and orderDate > :minOrderDate "
        +" order by customer.id, id desc "
        +" limit 50 ";

Query<Order> query = ebeanServer.createQuery(Order.class, oql);
query.setParameter("custName", "Rob%");
query.setParameter("minOrderDate", lastWeek);

List<Order> orderList = query.findList();
...

Example: Using a named query called "with.cust.and.details"

Query<Order> query = ebeanServer.createNamedQuery(Order.class,"with.cust.and.details");
query.setParameter("custName", "Rob%");
query.setParameter("minOrderDate", lastWeek);

List<Order> orderList = query.findList();
...

AutoTune

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.

Query Language

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.

Examples of Ebean's Query Language

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)

Method Summary

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.
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.
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.
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(QueryEachConsumer<T> consumer) Execute the query processing the beans one at a time.
void	findEachWhile(QueryEachWhileConsumer<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.
FutureRowCount<T>	findFutureRowCount() Deprecated.
List<Object>	findIds() Execute the query returning the list of Id's.
List<T>	findList() Execute the query returning the list of objects.
Map<?,T>	findMap() Execute the query returning a map of the objects.
<K> Map<K,T>	findMap(String keyProperty, Class<K> keyType) Return a typed map specifying the key property and type.
PagedList<T>	findPagedList() Return a PagedList for this query using firstRow and maxRows.
int	findRowCount() Deprecated.
Set<T>	findSet() Execute the query returning the set of objects.
T	findUnique() Execute the query returning either a single bean or null (if no matching bean is found).
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.
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.
String	getGeneratedSql() Return the sql that was generated for executing this query.
Object	getId() Return the Id value.
int	getMaxRows() Return the max rows for this query.
RawSql	getRawSql() Return the RawSql that was set to use for this query.
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	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>	select(String fetchProperties) Specify the properties to fetch on the root level entity bean in comma delimited format.
Query<T>	setAutoTune(boolean autoTune) Explicitly specify whether to use AutoTune for this query.
Query<T>	setBufferFetchSizeHint(int fetchSize) A hint which for JDBC translates to the Statement.fetchSize().
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>	setFirstRow(int firstRow) Set the first row to return for this query.
Query<T>	setForUpdate(boolean forUpdate) executed the select with "for update" which should lock the record "on read"
Query<T>	setId(Object id) Set the Id value to query.
Query<T>	setIncludeSoftDeletes() Execute the query including soft deleted rows.
Query<T>	setLazyLoadBatchSize(int lazyLoadBatchSize) Set the default lazy loading batch size to use.
Query<T>	setLoadBeanCache(boolean loadBeanCache) When set to true all the beans from this query are loaded into the bean cache.
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>	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.
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.
Query<T>	setUseQueryCache(boolean useQueryCache) Set this to true to use the query cache.
ExpressionList<T>	text() Add Full text search expressions for Document store queries.
int	update() Execute the UpdateQuery returning the number of rows updated.
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.

Method Detail

getRawSql

RawSql getRawSql()

Return the RawSql that was set to use for this query.

setRawSql

Query<T> setRawSql(RawSql rawSql)

Set RawSql to use for this query.

asOf

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.

To perform this query the DB must have underlying history tables.

Parameters:

asOf - the date time in the past at which you want to view the data

asDraft

Query<T> asDraft()

Execute the query against the draft set of tables.

cancel

void cancel()

Cancel the query execution if supported by the underlying database and driver.

This must be called from a different thread to the query executor.

copy

Query<T> copy()

Return a copy of the query.

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.

setPersistenceContextScope

Query<T> setPersistenceContextScope(PersistenceContextScope scope)

Specify the PersistenceContextScope to use for this query.

When this is not set the 'default' configured on 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.

Parameters:

scope - The scope to use for this query and subsequent lazy loading.

getExpressionFactory

ExpressionFactory getExpressionFactory()

Return the ExpressionFactory used by this query.

isAutoTuned

boolean isAutoTuned()

Returns true if this query was tuned by autoTune.

setAutoTune

Query<T> setAutoTune(boolean autoTune)

Explicitly specify whether to use AutoTune for this query.

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.

setLazyLoadBatchSize

Query<T> setLazyLoadBatchSize(int lazyLoadBatchSize)

Set the default lazy loading batch size to use.

When lazy loading is invoked on beans loaded by this query then this sets the batch size used to load those beans.

Parameters:

lazyLoadBatchSize - the number of beans to lazy load in a single batch

setIncludeSoftDeletes

Query<T> setIncludeSoftDeletes()

Execute the query including soft deleted rows.

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.

setDisableReadAuditing

Query<T> setDisableReadAuditing()

Disable read auditing for this query.

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.

select

Query<T> select(String fetchProperties)

Specify the properties to fetch on the root level entity bean in comma delimited format.

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 =
    ebeanServer.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();

Parameters:

fetchProperties - the properties to fetch for this bean (* = all properties).

fetch

Query<T> fetch(String path,
               String fetchProperties)

Specify a path to fetch eagerly including specific properties.

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 =
    ebeanServer.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 =
    ebeanServer.find(Customer.class)
    .select("name, status")
    .fetch("contacts", "firstName,lastName,email")
    .findList();

Parameters:

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).

fetchQuery

Query<T> fetchQuery(String path,
                    String fetchProperties)

Fetch the path and properties using a "query join" (separate SQL query).

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.

Parameters:

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).

fetchLazy

Query<T> fetchLazy(String path,
                   String fetchProperties)

Fetch the path and properties lazily (via batch lazy loading).

This is the same as:

 fetch(path, fetchProperties, new FetchConfig().lazy())

The reason for using fetchLazy() is to either:

• Control/tune what is fetched as part of lazy loading
• Make use of the L2 cache, build this part of the graph from L2 cache

Parameters:

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).

fetch

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.

// fetch customers (their id, name and status)
List<Customer> customers =
    ebeanServer.find(Customer.class)
    .select("name, status")
    .fetch("contacts", "firstName,lastName,email", new FetchConfig().lazy(10))
    .findList();

Parameters:

path - the property path we wish to fetch eagerly.

fetch

Query<T> fetch(String path)

Specify a path to fetch eagerly including all its properties.

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 =
    ebeanServer.find(Customer.class)
    // eager fetch the contacts
    .fetch("contacts")
    .findList();

Parameters:

path - the property path we wish to fetch eagerly.

fetchQuery

Query<T> fetchQuery(String path)

Fetch the path eagerly using a "query join" (separate SQL query).

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.

Parameters:

path - the property path we wish to fetch eagerly

fetchLazy

Query<T> fetchLazy(String path)

Fetch the path lazily (via batch lazy loading).

This is the same as:

 fetch(path, new FetchConfig().lazy())

The reason for using fetchLazy() is to either:

• Control/tune what is fetched as part of lazy loading
• Make use of the L2 cache, build this part of the graph from L2 cache

Parameters:

path - the property path we wish to fetch lazily.

fetch

Query<T> fetch(String path,
               FetchConfig fetchConfig)

Additionally specify a JoinConfig to specify a "query join" and or define the lazy loading query.

// fetch customers (their id, name and status)
List<Customer> customers =
    ebeanServer.find(Customer.class)
    // lazy fetch contacts with a batch size of 100
    .fetch("contacts", new FetchConfig().lazy(100))
    .findList();

apply

Query<T> apply(FetchPath fetchPath)

Apply the path properties replacing the select and fetch clauses.

This is typically used when the FetchPath is applied to both the query and the JSON output.

findIds

List<Object> findIds()

Execute the query returning the list of Id's.

This query will execute against the EbeanServer that was used to create it.

See Also:

EbeanServer.findIds(Query, Transaction)

findEach

void findEach(QueryEachConsumer<T> consumer)

Execute the query processing the beans one at a time.

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 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 QueryEachConsumer (SAM) interface which is better suited to use with Java8 closures.

 ebeanServer.find(Customer.class)
    .where().eq("status", Status.NEW)
    .order().asc("id")
    .findEach((Customer customer) -> {

      // do something with customer
      System.out.println("-- visit " + customer);
    });

Parameters:

consumer - the consumer used to process the queried beans.

findEachWhile

void findEachWhile(QueryEachWhileConsumer<T> consumer)

Execute the query using callbacks to a visitor to process the resulting beans one at a time.

This method is functionally equivalent to findIterate() but instead of using an iterator uses the QueryEachWhileConsumer (SAM) interface which is better suited to use with Java8 closures.

 ebeanServer.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);
    });

Parameters:

consumer - the consumer used to process the queried beans.

findList

List<T> findList()

Execute the query returning the list of objects.

This query will execute against the EbeanServer that was used to create it.

List<Customer> customers =
    ebeanServer.find(Customer.class)
    .where().ilike("name", "rob%")
    .findList();

See Also:

EbeanServer.findList(Query, Transaction)

findSet

Set<T> findSet()

Execute the query returning the set of objects.

This query will execute against the EbeanServer that was used to create it.

Set<Customer> customers =
    ebeanServer.find(Customer.class)
    .where().ilike("name", "rob%")
    .findSet();

See Also:

EbeanServer.findSet(Query, Transaction)

findMap

Map<?,T> findMap()

Execute the query returning a map of the objects.

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<?, Product> map =
  ebeanServer.find(Product.class)
    .setMapKey("sku")
    .findMap();

See Also:

EbeanServer.findMap(Query, Transaction)

findMap

<K> Map<K,T> findMap(String keyProperty,
                     Class<K> keyType)

Return a typed map specifying the key property and type.

findUnique

@Nullable
T findUnique()

Execute the query returning either a single bean or null (if no matching bean is found).

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 =
    ebeanServer.find(Product.class)
        .where().eq("sku", "aa113")
        .findUnique();
...

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 =
    ebeanServer.find(Order.class)
      .setId(1)
      .fetch("details")
      .findUnique();

// the order details were eagerly loaded
List<OrderDetail> details = order.getDetails();
...

Throws:

javax.persistence.NonUniqueResultException - if more than one result was found

findVersions

List<Version<T>> findVersions()

Return versions of a @History entity bean.

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.

findVersionsBetween

List<Version<T>> findVersionsBetween(Timestamp start,
                                     Timestamp end)

Return versions of a @History entity bean between the 2 timestamps.

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.

delete

int delete()

Execute as a delete query deleting the 'root level' beans that match the predicates in the query.

Note that if the query includes joins then the generated delete statement may not be optimal depending on the database platform.

Returns:

the number of beans/rows that were deleted.

update

int update()

Execute the UpdateQuery returning the number of rows updated.

findCount

int findCount()

Return the count of entities this query should return.

This is the number of 'top level' or 'root level' entities.

findRowCount

int findRowCount()

Deprecated.

Deprecated in favor of findCount().

Return the count of entities this query should return.

findFutureCount

FutureRowCount<T> findFutureCount()

Execute find row count query in a background thread.

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).

Returns:

a Future object for the row count query

findFutureRowCount

FutureRowCount<T> findFutureRowCount()

Deprecated.

Deprecated in favor of findFutureCount().

Execute find row count query in a background thread.

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).

Returns:

a Future object for the row count query

findFutureIds

FutureIds<T> findFutureIds()

Execute find Id's query in a background thread.

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).

Returns:

a Future object for the list of Id's

findFutureList

FutureList<T> findFutureList()

Execute find list query in a background thread.

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.

Returns:

a Future object for the list result of the query

findPagedList

PagedList<T> findPagedList()

Return a PagedList for this query using firstRow and maxRows.

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 = Ebean.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();

Returns:

The PagedList

setParameter

Query<T> setParameter(String name,
                      Object value)

Set a named bind parameter. Named parameters have a colon to prefix the name.

// a query with a named parameter
String oql = "find order where status = :orderStatus";

Query<Order> query = ebeanServer.find(Order.class, oql);

// bind the named parameter
query.bind("orderStatus", OrderStatus.NEW);
List<Order> list = query.findList();

Parameters:

name - the parameter name

value - the parameter value

setParameter

Query<T> setParameter(int position,
                      Object value)

Set an ordered bind parameter according to its position. Note that the position starts at 1 to be consistent with JDBC PreparedStatement. You need to set a parameter value for each ? you have in the query.

// a query with a positioned parameter
String oql = "where status = ? order by id desc";

Query<Order> query = ebeanServer.createQuery(Order.class, oql);

// bind the parameter
query.setParameter(1, OrderStatus.NEW);

List<Order> list = query.findList();

Parameters:

position - the parameter bind position starting from 1 (not 0)

value - the parameter bind value.

setId

Query<T> setId(Object id)

Set the Id value to query. This is used with findUnique().

You can use this to have further control over the query. For example adding fetch joins.

Order order =
    ebeanServer.find(Order.class)
    .setId(1)
    .fetch("details")
    .findUnique();

// the order details were eagerly fetched
List<OrderDetail> details = order.getDetails();

getId

Object getId()

Return the Id value.

where

Query<T> where(Expression expression)

Add a single Expression to the where clause returning the query.

List<Order> newOrders =
    ebeanServer.find(Order.class)
                .where().eq("status", Order.NEW)
                .findList();
...

where

ExpressionList<T> where()

Add Expressions to the where clause with the ability to chain on the ExpressionList. You can use this for adding multiple expressions to the where clause.

List<Order> orders =
    ebeanServer.find(Order.class)
    .where()
      .eq("status", Order.NEW)
      .ilike("customer.name","rob%")
    .findList();

Returns:

The ExpressionList for adding expressions to.

See Also:

Expr

text

ExpressionList<T> text()

Add Full text search expressions for Document store queries.

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.

filterMany

ExpressionList<T> filterMany(String propertyName)

This applies a filter on the 'many' property list rather than the root level objects.

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 =
    ebeanServer.find(Customer.class)
    // .fetch("orders", new FetchConfig().lazy())
    // .fetch("orders", new FetchConfig().query())
    .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.

Parameters:

propertyName - the name of the many property that you want to have a filter on.

Returns:

the expression list that you add filter expressions for the many to.

having

ExpressionList<T> having()

Add Expressions to the Having clause return the ExpressionList.

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).

Returns:

The ExpressionList for adding more expressions to.

See Also:

Expr

having

Query<T> having(Expression addExpressionToHaving)

Add an expression to the having clause returning the query.

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.

Parameters:

addExpressionToHaving - the expression to add to the having clause.

Returns:

the Query object

orderBy

Query<T> orderBy(String orderByClause)

Set the order by clause replacing the existing order by clause if there is one.

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).

order

Query<T> order(String orderByClause)

Set the order by clause replacing the existing order by clause if there is one.

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).

order

OrderBy<T> order()

Return the OrderBy so that you can append an ascending or descending property to the order by clause.

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

OrderBy<T> orderBy()

Return the OrderBy so that you can append an ascending or descending property to the order by clause.

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().

setOrder

Query<T> setOrder(OrderBy<T> orderBy)

Set an OrderBy object to replace any existing OrderBy clause.

This is EXACTLY the same as setOrderBy(OrderBy).

setOrderBy

Query<T> setOrderBy(OrderBy<T> orderBy)

Set an OrderBy object to replace any existing OrderBy clause.

This is EXACTLY the same as setOrder(OrderBy).

setDistinct

Query<T> setDistinct(boolean isDistinct)

Set whether this query uses DISTINCT.

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 =
      Ebean.find(Customer.class)
         .setDistinct(true)
         .select("name")
         .findList();

getFirstRow

int getFirstRow()

Return the first row value.

setFirstRow

Query<T> setFirstRow(int firstRow)

Set the first row to return for this query.

Parameters:

firstRow - the first row to include in the query result.

getMaxRows

int getMaxRows()

Return the max rows for this query.

setMaxRows

Query<T> setMaxRows(int maxRows)

Set the maximum number of rows to return in the query.

Parameters:

maxRows - the maximum number of rows to return in the query.

setMapKey

Query<T> setMapKey(String mapKey)

Set the property to use as keys for a map.

If no property is set then the id property is used.

// Assuming sku is unique for products...

Map<?,Product> productMap =
    ebeanServer.find(Product.class)
    // use sku for keys...
    .setMapKey("sku")
    .findMap();

Parameters:

mapKey - the property to use as keys for a map.

setUseCache

Query<T> setUseCache(boolean useCache)

Set this to false to not use the bean cache.

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.

In the case of other queries (findList(), findEach() etc) then setting this to false beans that the if lazy loading is invoked that lazy loading will not try to use the bean cache.

setUseQueryCache

Query<T> setUseQueryCache(boolean useQueryCache)

Set this to true to use the query cache.

setUseDocStore

Query<T> setUseDocStore(boolean useDocStore)

Set to true if this query should execute against the doc store.

When setting this you may also consider disabling lazy loading.

setReadOnly

Query<T> setReadOnly(boolean readOnly)

When set to true when you want the returned beans to be read only.

setLoadBeanCache

Query<T> setLoadBeanCache(boolean loadBeanCache)

When set to true all the beans from this query are loaded into the bean cache.

setTimeout

Query<T> setTimeout(int secs)

Set a timeout on this query.

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.

Parameters:

secs - the query timeout limit in seconds. Zero means there is no limit.

setBufferFetchSizeHint

Query<T> setBufferFetchSizeHint(int fetchSize)

A hint which for JDBC translates to the Statement.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.

getGeneratedSql

String getGeneratedSql()

Return the sql that was generated for executing this query.

This is only available after the query has been executed and provided only for informational purposes.

setForUpdate

Query<T> setForUpdate(boolean forUpdate)

executed the select with "for update" which should lock the record "on read"

isForUpdate

boolean isForUpdate()

Return true if this query has forUpdate set.

alias

Query<T> alias(String alias)

Set root table alias.

getBeanType

Class<T> getBeanType()

Return the type of beans being queried.

setDisableLazyLoading

Query<T> setDisableLazyLoading(boolean disableLazyLoading)

Set true if you want to disable lazy loading.

That is, once the object graph is returned further lazy loading is disabled.

validate

Set<String> validate()

Returns the set of properties or paths that are unknown (do not map to known properties or paths).

Validate the query checking the where and orderBy expression paths to confirm if they represent valid properties or paths for the given bean type.