Alias

Sets the table alias to use on the base table.

List<Customer> customers =
    new QCustomer()
      .alias("cust")
      .name.istartsWith("Rob")
      .findList();

select cust.id, cust.inactive, cust.name, cust.registered, ...
from customer cust
where lower(cust.name) like ? escape'|' ; --bind(rob%)

The typically use of alias is when used as a subquery.

Query<Order> subQuery = new QOrder()
  .alias("sub")
  .select("id").where().raw("sub.customer_id = main.id")
  .query();

List<Customer> customers = new QCustomer()
    .alias("main")
    .query().where().exists(subQuery)
    .findList();

select main.id, main.inactive, main.name, main.registered, ...
from customer main
where  exists (select sub.id from orders sub where sub.customer_id = main.id)

asDraft

Used to fetch a @Draftable entities from their draft table(s) rather than the published tables.

Document documentDraft =
  new QDocument()
    .asDraft()
    .id.equalTo(42)
    .findOne();

As of timestamp

For entities with @History fetch the entities AS OF the given timestamp.

Timestamp timeInPast = ...;

List<Customer> customers
  = new QCustomer()
  .asOf(timeInPast)
  .findList();

Autotune

Turn on or off automatic query tuning.

bufferFetchSizeHint

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.

disableLazyLoading

Disables any lazy loading that would otherwise occur. Instead unloaded properties would return null.

disableReadAuditing

Disable read auditing for this query. Refer to Read Auditing.

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.

distinct

Make the query use sql distinct.

List<String> lastNames =
  new QContact()
   .setDistinct(true)
   .select("lastName")
   .email.isNull()
   .findSingleAttributeList();

int count =
  new QCustomer()
      .setDistinct(true)
      .select("anniversary")
      .status.equalTo(Customer.Status.NEW)
      .findCount();

select count(distinct t0.anniversary) from customer t0 where t0.status = ?

// partially loaded beans without Id properties
// ... not persistable, no lazy loading etc

List<Customer> beans =
  new QContact()
      .setDistinct(true)
      .select("lastName, dateOfBirth")
      .findList();

forUpdate

Execute the query with FOR UPDATE that will hold a lock on the rows fetched.

try (Transaction txn = database.beginTransaction()) {

  Customer customer =
    new QContact()
    .forUpdate()
    .email.equalTo("rob@foo.com")
    .findOne();


  customer.setName("a better name");
  customer.save();

  txn.commit();
}

includeSoftDeletes

Set to true to include soft deleted rows. Refer to Soft Delete.

lazyLoadBatchSize

Set this to tune the lazy loading batch size which by default is set to 10.

persistenceContextScope

Generally queries run with transaction scoped persistence context. With this we can set to QUERY the object graph built will be fresh data from the database ignoring any existing bean that is in the [transaction] persistence context.

try (Transaction txn = database.beginTransaction()) {

  // when customer is loaded it then is referenced in the
  // transaction scoped persistence context (aka L1 cache)
  Customer loaded = Customer.find.byId(42)


  // fetch this same customer but we want to ignore the L1 cache
  // such that we get a "fresh" version of its data

  Customer customer =
    new QCustomer()
      .id.equalTo(42)
      .setUseCache(false)                        // ignore L2 cache
      .setPersistenceContextScope(QUERY)         // ignore L1 cache
      .findOne();


  ...

  txn.commit();
}

readOnly [Removed]

This option has been REMOVED and replaced by Unmodifiable

Query returns beans that are deemed to be READ ONLY and calling setter methods will throw an exception.

Unmodifiable

When set to true the query returns beans that are unmodifiable read only. When a Query.setUseQueryCache() is enabled the query will automatically use Unmodifiable mode (and return unmodifiable beans).

This means that the returning graph can't be mutated via setters, all the collections are unmodifiable collections, lazy loading is disabled and that the query uses PersistenceContextScope#QUERY.

Attempting to mutate an unmodifiable bean will throw a UnmodifiableEntityException. Attempting to load an unloaded property will throw a LazyInitialisationException.

Use this when we want to ensure that the returned object graph can't be mutated in any way, such as if we want to hold the result in an application cache or otherwise want to ensure that no lazy loading is performed.