Module io.ebean.api
Package io.ebean

Interface ExpressionList<T>

All Known Subinterfaces:
Junction<T>
@NonNullApi public interface ExpressionList<T>
List of Expressions that make up a where or having clause.

An ExpressionList is returned from Query.where().

The ExpressionList has a list of convenience methods that create the standard expressions and add them to this list.

The ExpressionList also duplicates methods that are found on the Query such as findList() and order(). The purpose of these methods is provide a fluid API. The upside of this approach is that you can build and execute a query via chained methods. The down side is that this ExpressionList object has more methods than you would initially expect (the ones duplicated from Query).

See Also:

  • Method Details

    • query

      Query<T> query()
      Return the query that owns this expression list.

      This is a convenience method solely to support a fluid API where the methods are chained together. Adding expressions returns this expression list and this method can be used after that to return back the original query so that further things can be added to it.

    • orderById

      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. This may affect performance. If this is not enabled, and an orderBy is set on the query, it's up to the programmer that this query provides a deterministic result.

    • order

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

    • orderBy

      ExpressionList<T> orderBy(String orderBy)
      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.

    • 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 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 the same as order()

    • setOrderBy

      @Deprecated Query<T> setOrderBy(String orderBy)
      Deprecated.
      Deprecated migrate to orderBy(String)

    • apply

      Query<T> apply(FetchPath fetchPath)
      Apply the path properties to the query replacing the select and fetch clauses.

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

    • asDto

      <D> DtoQuery<D> asDto(Class<D> dtoClass)
      Convert the query to a DTO bean query.

      We effectively use the underlying ORM query to build the SQL and then execute and map it into DTO beans.

    • asUpdate

      UpdateQuery<T> asUpdate()
      Return the underlying query as an UpdateQuery.

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

    • withLock

      Query<T> withLock(Query.LockType lockType)
      Execute the query with the given lock type and WAIT.

      Note that forUpdate() is the same as withLock(LockType.UPDATE).

      Provides us with the ability to explicitly use Postgres SHARE, KEY SHARE, NO KEY UPDATE and UPDATE row locks.

    • withLock

      Query<T> withLock(Query.LockType lockType, Query.LockWait lockWait)
      Execute the query with the given lock type and lock wait.

      Note that forUpdateNoWait() is the same as withLock(LockType.UPDATE, LockWait.NOWAIT).

      Provides us with the ability to explicitly use Postgres SHARE, KEY SHARE, NO KEY UPDATE and UPDATE row locks.

    • forUpdate

      Query<T> forUpdate()
      Execute using "for update" clause which results in the DB locking the record.

    • forUpdateNoWait

      Query<T> forUpdateNoWait()
      Execute using "for update" clause with No Wait option.

      This is typically a Postgres and Oracle only option at this stage.

    • forUpdateSkipLocked

      Query<T> forUpdateSkipLocked()
      Execute using "for update" clause with Skip Locked option.

      This is typically a Postgres and Oracle only option at this stage.

    • setIncludeSoftDeletes

      Query<T> setIncludeSoftDeletes()
      Execute the query including soft deleted rows.

    • usingTransaction

      Query<T> usingTransaction(Transaction transaction)
      Execute the query using the given transaction.

    • usingConnection

      Query<T> usingConnection(Connection connection)
      Execute the query using the given connection.

    • 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 rows that were deleted.

    • delete

      int delete(Transaction transaction)
      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 rows that were deleted.

    • update

      int update()
      Execute as a update query.
      Returns:
      the number of rows that were updated.
      See Also:

    • update

      int update(Transaction transaction)
      Execute as a update query with the given transaction.
      Returns:
      the number of rows that were updated.
      See Also:

    • exists

      boolean exists()
      Execute the query returning true if a row is found.

      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.

      Example:

      

   boolean userExists = query().where().eq("email", "rob@foo.com").exists();

      Example using a query bean:

      

   boolean userExists = new QContact().email.equalTo("rob@foo.com").exists();
      Returns:
      True if the query finds a matching row in the database

    • findIterate

      QueryIterator<T> findIterate()
      Execute the query iterating over the results.
      See Also:

    • findEach

      void findEach(Consumer<T> consumer)
      Execute the query process the beans one at a time.
      See Also:

    • findEach

      void findEach(int batch, Consumer<List<T>> consumer)
      Execute findEach with a batch consumer.
      See Also:

    • findEachWhile

      void findEachWhile(Predicate<T> consumer)
      Execute the query processing the beans one at a time with the ability to stop processing before reading all the beans.
      See Also:

    • findList

      List<T> findList()
      Execute the query returning a list.
      See Also:

    • findIds

      <A> List<A> findIds()
      Execute the query returning the list of Id's.
      See Also:

    • findCount

      int findCount()
      Return the count of entities this query should return.

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

    • findSet

      Set<T> findSet()
      Execute the query returning a set.
      See Also:

    • findMap

      <K> Map<K,T> findMap()
      Execute the query returning a map.
      See Also:

    • findSingleAttributeList

      <A> List<A> findSingleAttributeList()
      Execute the query returning a list of values for a single property.

      Example 1:

      

  List<String> names =
    DB.find(Customer.class)
      .select("name")
      .order().asc("name")
      .findSingleAttributeList();

      Example 2:

      

  List<String> names =
    DB.find(Customer.class)
      .setDistinct(true)
      .select("name")
      .where().eq("status", Customer.Status.NEW)
      .order().asc("name")
      .setMaxRows(100)
      .findSingleAttributeList();
      Returns:
      the list of values for the selected property

    • findSingleAttribute

      default <A> A findSingleAttribute()
      Execute a query returning a single value of a single property/column. 
      

  String name =
    DB.find(Customer.class)
      .select("name")
      .where().eq("id", 42)
      .findSingleAttribute();

    • findOne

      @Nullable T findOne()
      Execute the query returning 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.

      Throws:
      javax.persistence.NonUniqueResultException - if more than one result was found
      See Also:

    • findOneOrEmpty

      Optional<T> findOneOrEmpty()
      Execute the query returning an optional bean.

    • 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

    • 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 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 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 = 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();
      Returns:
      The PagedList
      See Also:

    • findVersions

      List<Version<T>> findVersions()
      Return versions of a @History entity bean.

      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.

    • filterMany

      ExpressionList<T> filterMany(String manyProperty)
      Add some filter predicate expressions to the many property.

    • filterMany

      ExpressionList<T> filterMany(String manyProperty, String expressions, Object... params)
      Add filter expressions to the many property. 
      

   DB.find(Customer.class)
   .where()
   .eq("name", "Rob")
   .filterMany("orders", "status = ?", Status.NEW)
   .findList();
      Parameters:
      manyProperty - The many property
      expressions - Filter expressions with and, or and ? or ?1 type bind parameters
      params - Bind parameters used in the expressions

    • select

      Query<T> select(String properties)
      Specify specific properties to fetch on the main/root bean (aka partial object).
      See Also:

    • select

      Query<T> select(FetchGroup<T> fetchGroup)
      Apply the fetchGroup which defines what part of the object graph to load.

    • setDistinct

      Query<T> setDistinct(boolean distinct)
      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 =
       DB.find(Customer.class)
          .setDistinct(true)
          .select("name")     // only select the customer name
          .findList();

    • setDocIndexName

      Query<T> setDocIndexName(String indexName)
      Set the index(es) to search for a document store which uses partitions.

      For example, when executing a query against ElasticSearch with daily indexes we can explicitly specify the indexes to search against.

      Parameters:
      indexName - The index or indexes to search against
      Returns:
      This query
      See Also:

    • setFirstRow

      ExpressionList<T> setFirstRow(int firstRow)
      Set the first row to fetch.
      See Also:

    • setMaxRows

      ExpressionList<T> setMaxRows(int maxRows)
      Set the maximum number of rows to fetch.
      See Also:

    • setMapKey

      Query<T> setMapKey(String mapKey)
      Set the name of the property which values become the key of a map.
      See Also:

    • setUseCache

      Query<T> setUseCache(boolean useCache)
      Set to true when this query should use the bean cache.

      This is now the same as setUseBeanCache(CacheMode.ON) and will be deprecated.

      See Also:

    • setBeanCacheMode

      Query<T> setBeanCacheMode(CacheMode beanCacheMode)
      Set the mode to use the bean cache when executing this query.
      See Also:

    • setUseQueryCache

      Query<T> setUseQueryCache(CacheMode useCache)
      Set the CacheMode to use the query cache for executing this query.
      See Also:

    • setCountDistinct

      Query<T> setCountDistinct(CountDistinctOrder orderBy)
      Extended version for setDistinct in conjunction with "findSingleAttributeList"; 
      

  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

    • setUseQueryCache

      default Query<T> setUseQueryCache(boolean enabled)
      Calls setUseQueryCache(CacheMode) with ON or OFF.
      See Also:

    • setUseDocStore

      Query<T> setUseDocStore(boolean useDocsStore)
      Set to true if this query should execute against the doc store.

      When setting this you may also consider disabling lazy loading.

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

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

    • setLabel

      Query<T> setLabel(String label)
      Set a label on the query (to help identify query execution statistics).

    • having

      ExpressionList<T> having()
      Add expressions to the having clause.

      The having clause is only used for queries based on raw sql (via SqlSelect annotation etc).

    • where

      ExpressionList<T> where()
      Add another expression to the where clause.

    • where

      ExpressionList<T> where(String expressions, Object... params)
      Add the expressions to this expression list.
      Parameters:
      expressions - The expressions that are parsed and added to this expression list
      params - Bind parameters to match ? or ?1 bind positions.

    • jsonExists

      ExpressionList<T> jsonExists(String propertyName, String path)
      Path exists - for the given path in a JSON document. 
      

   where().jsonExists("content", "path.other")
      Parameters:
      propertyName - the property that holds a JSON document
      path - the nested path in the JSON document in dot notation

    • jsonNotExists

      ExpressionList<T> jsonNotExists(String propertyName, String path)
      Path does not exist - for the given path in a JSON document. 
      

   where().jsonNotExists("content", "path.other")
      Parameters:
      propertyName - the property that holds a JSON document
      path - the nested path in the JSON document in dot notation

    • jsonEqualTo

      ExpressionList<T> jsonEqualTo(String propertyName, String path, Object value)
      Equal to expression for the value at the given path in the JSON document. 
      

   where().jsonEqualTo("content", "path.other", 34)
      Parameters:
      propertyName - the property that holds a JSON document
      path - the nested path in the JSON document in dot notation
      value - the value used to test against the document path's value

    • jsonNotEqualTo

      ExpressionList<T> jsonNotEqualTo(String propertyName, String path, Object value)
      Not Equal to - for the given path in a JSON document. 
      

   where().jsonNotEqualTo("content", "path.other", 34)
      Parameters:
      propertyName - the property that holds a JSON document
      path - the nested path in the JSON document in dot notation
      value - the value used to test against the document path's value

    • jsonGreaterThan

      ExpressionList<T> jsonGreaterThan(String propertyName, String path, Object value)
      Greater than - for the given path in a JSON document. 
      

   where().jsonGreaterThan("content", "path.other", 34)

    • jsonGreaterOrEqual

      ExpressionList<T> jsonGreaterOrEqual(String propertyName, String path, Object value)
      Greater than or equal to - for the given path in a JSON document. 
      

   where().jsonGreaterOrEqual("content", "path.other", 34)

    • jsonLessThan

      ExpressionList<T> jsonLessThan(String propertyName, String path, Object value)
      Less than - for the given path in a JSON document. 
      

   where().jsonLessThan("content", "path.other", 34)

    • jsonLessOrEqualTo

      ExpressionList<T> jsonLessOrEqualTo(String propertyName, String path, Object value)
      Less than or equal to - for the given path in a JSON document. 
      

   where().jsonLessOrEqualTo("content", "path.other", 34)

    • jsonBetween

      ExpressionList<T> jsonBetween(String propertyName, String path, Object lowerValue, Object upperValue)
      Between - for the given path in a JSON document. 
      

   where().jsonBetween("content", "orderDate", lowerDateTime, upperDateTime)

    • add

      ExpressionList<T> add(Expression expr)
      Add an Expression to the list.

    • addAll

      ExpressionList<T> addAll(ExpressionList<T> exprList)
      Add a list of Expressions to this ExpressionList.s

    • eq

      ExpressionList<T> eq(String propertyName, Object value)
      Equal To - property is equal to a given value.

    • eqOrNull

      ExpressionList<T> eqOrNull(String propertyName, Object value)
      Equal To or Null - property is equal to a given value or null.

    • ne

      ExpressionList<T> ne(String propertyName, Object value)
      Not Equal To - property not equal to the given value.

    • ieq

      ExpressionList<T> ieq(String propertyName, String value)
      Case Insensitive Equal To - property equal to the given value (typically using a lower() function to make it case insensitive).

    • ine

      ExpressionList<T> ine(String propertyName, String value)
      Case Insensitive Not Equal To - property not equal to the given value (typically using a lower() function to make it case insensitive).

    • inRangeWith

      ExpressionList<T> inRangeWith(String lowProperty, String highProperty, Object value)
      Value in Range between 2 properties. 
      

    .startDate.inRangeWith(endDate, now)

    // which equates to
    startDate <= now and (endDate > now or endDate is null)

      This is a convenience expression combining a number of simple expressions. The most common use of this could be called "effective dating" where 2 date or timestamp columns represent the date range in which

    • inRange

      ExpressionList<T> inRange(String propertyName, Object value1, Object value2)
      In Range - property >= value1 and property < value2.

      Unlike Between inRange is "half open" and usually more useful for use with dates or timestamps.

    • between

      ExpressionList<T> between(String propertyName, Object value1, Object value2)
      Between - property between the two given values.

    • betweenProperties

      ExpressionList<T> betweenProperties(String lowProperty, String highProperty, Object value)
      Between - value between the two properties.

    • gt

      ExpressionList<T> gt(String propertyName, Object value)
      Greater Than - property greater than the given value.

    • gtOrNull

      ExpressionList<T> gtOrNull(String propertyName, Object value)
      Greater Than or Null - property greater than the given value or null.

    • geOrNull

      ExpressionList<T> geOrNull(String propertyName, Object value)
      Greater Than or Equal to OR Null - (>= or null ).

    • ge

      ExpressionList<T> ge(String propertyName, Object value)
      Greater Than or Equal to - property greater than or equal to the given value.

    • lt

      ExpressionList<T> lt(String propertyName, Object value)
      Less Than - property less than the given value.

    • ltOrNull

      ExpressionList<T> ltOrNull(String propertyName, Object value)
      Less Than or Null - property less than the given value or null.

    • leOrNull

      ExpressionList<T> leOrNull(String propertyName, Object value)
      Less Than or Equal to OR Null - (<= or null ).

    • le

      ExpressionList<T> le(String propertyName, Object value)
      Less Than or Equal to - property less than or equal to the given value.

    • isNull

      ExpressionList<T> isNull(String propertyName)
      Is Null - property is null.

    • isNotNull

      ExpressionList<T> isNotNull(String propertyName)
      Is Not Null - property is not null.

    • exampleLike

      ExpressionList<T> exampleLike(Object example)
      A "Query By Example" type of expression.

      Pass in an example entity and for each non-null scalar properties an expression is added.

      By Default this case sensitive, will ignore numeric zero values and will use a Like for string values (you must put in your own wildcards).

      To get control over the options you can create an ExampleExpression and set those options such as case insensitive etc. 

      

 // create an example bean and set the properties
 // with the query parameters you want
 Customer example = new Customer();
 example.setName("Rob%");
 example.setNotes("%something%");

 List<Customer> list =
   DB.find(Customer.class)
     .where().exampleLike(example)
     .findList();

      Similarly you can create an ExampleExpression 

      

 Customer example = new Customer();
 example.setName("Rob%");
 example.setNotes("%something%");

 // create a ExampleExpression with more control
 ExampleExpression qbe = new ExampleExpression(example, true, LikeType.EQUAL_TO).includeZeros();

 List<Customer> list = DB.find(Customer.class).where().add(qbe).findList();

    • iexampleLike

      ExpressionList<T> iexampleLike(Object example)
      Case insensitive version of exampleLike(Object)

    • like

      ExpressionList<T> like(String propertyName, String value)
      Like - property like value where the value contains the SQL wild card characters % (percentage) and _ (underscore).

    • ilike

      ExpressionList<T> ilike(String propertyName, String value)
      Case insensitive Like - property like value where the value contains the SQL wild card characters % (percentage) and _ (underscore). Typically uses a lower() function to make the expression case insensitive.

    • startsWith

      ExpressionList<T> startsWith(String propertyName, String value)
      Starts With - property like value%.

    • istartsWith

      ExpressionList<T> istartsWith(String propertyName, String value)
      Case insensitive Starts With - property like value%. Typically uses a lower() function to make the expression case insensitive.

    • endsWith

      ExpressionList<T> endsWith(String propertyName, String value)
      Ends With - property like %value.

    • iendsWith

      ExpressionList<T> iendsWith(String propertyName, String value)
      Case insensitive Ends With - property like %value. Typically uses a lower() function to make the expression case insensitive.

    • contains

      ExpressionList<T> contains(String propertyName, String value)
      Contains - property like %value%.

    • icontains

      ExpressionList<T> icontains(String propertyName, String value)
      Case insensitive Contains - property like %value%. Typically uses a lower() function to make the expression case insensitive.

    • inPairs

      ExpressionList<T> inPairs(Pairs pairs)
      In expression using pairs of value objects.

    • in

      ExpressionList<T> in(String propertyName, Query<?> subQuery)
      In - using a subQuery.

    • in

      ExpressionList<T> in(String propertyName, Object... values)
      In - property has a value in the array of values.

    • in

      ExpressionList<T> in(String propertyName, Collection<?> values)
      In - property has a value in the collection of values.

    • inOrEmpty

      ExpressionList<T> inOrEmpty(String propertyName, Collection<?> values)
      In where null or empty values means that no predicate is added to the query.

      That is, only add the IN predicate if the values are not null or empty.

      Without this we typically need to code an if block to only add the IN predicate if the collection is not empty like:

      Without inOrEmpty()

      

   query.where() // add some predicates
     .eq("status", Status.NEW);

   if (ids != null && !ids.isEmpty()) {
     query.where().in("customer.id", ids);
   }

   query.findList();

      Using inOrEmpty()

      

   query.where()
     .eq("status", Status.NEW)
     .inOrEmpty("customer.id", ids)
     .findList();

    • isIn

      default ExpressionList<T> isIn(String propertyName, Query<?> subQuery)
      In - using a subQuery.

      This is exactly the same as in() and provided due to "in" being a Kotlin keyword (and hence to avoid the slightly ugly escaping when using in() in Kotlin)

    • isIn

      default ExpressionList<T> isIn(String propertyName, Object... values)
      In - property has a value in the array of values.

      This is exactly the same as in() and provided due to "in" being a Kotlin keyword (and hence to avoid the slightly ugly escaping when using in() in Kotlin)

    • isIn

      default ExpressionList<T> isIn(String propertyName, Collection<?> values)
      In - property has a value in the collection of values.

      This is exactly the same as in() and provided due to "in" being a Kotlin keyword (and hence to avoid the slightly ugly escaping when using in() in Kotlin)

    • notIn

      ExpressionList<T> notIn(String propertyName, Object... values)
      Not In - property has a value in the array of values.

    • notIn

      ExpressionList<T> notIn(String propertyName, Collection<?> values)
      Not In - property has a value in the collection of values.

    • notIn

      ExpressionList<T> notIn(String propertyName, Query<?> subQuery)
      Not In - using a subQuery.

    • isEmpty

      ExpressionList<T> isEmpty(String propertyName)
      Is empty expression for collection properties.

    • isNotEmpty

      ExpressionList<T> isNotEmpty(String propertyName)
      Is not empty expression for collection properties.

    • exists

      ExpressionList<T> exists(Query<?> subQuery)
      Exists expression

    • notExists

      ExpressionList<T> notExists(Query<?> subQuery)
      Not exists expression

    • idIn

      ExpressionList<T> idIn(Object... idValues)
      Id IN a list of id values.

    • idIn

      ExpressionList<T> idIn(Collection<?> idValues)
      Id IN a collection of id values.

    • idEq

      ExpressionList<T> idEq(Object value)
      Id Equal to - ID property is equal to the value.

    • allEq

      ExpressionList<T> allEq(Map<String,Object> propertyMap)
      All Equal - Map containing property names and their values.

      Expression where all the property names in the map are equal to the corresponding value.

      Parameters:
      propertyMap - a map keyed by property names.

    • arrayContains

      ExpressionList<T> arrayContains(String propertyName, Object... values)
      Array property contains entries with the given values.

    • arrayNotContains

      ExpressionList<T> arrayNotContains(String propertyName, Object... values)
      Array does not contain the given values.

      Array support is effectively limited to Postgres at this time.

    • arrayIsEmpty

      ExpressionList<T> arrayIsEmpty(String propertyName)
      Array is empty - for the given array property.

      Array support is effectively limited to Postgres at this time.

    • arrayIsNotEmpty

      ExpressionList<T> arrayIsNotEmpty(String propertyName)
      Array is not empty - for the given array property.

      Array support is effectively limited to Postgres at this time.

    • bitwiseAny

      ExpressionList<T> bitwiseAny(String propertyName, long flags)
      Add expression for ANY of the given bit flags to be set. 
      

 where().bitwiseAny("flags", BwFlags.HAS_BULK + BwFlags.HAS_COLOUR)
      Parameters:
      propertyName - The property that holds the flags value
      flags - The flags we are looking for

    • bitwiseAll

      ExpressionList<T> bitwiseAll(String propertyName, long flags)
      Add expression for ALL of the given bit flags to be set. 
      

 where().bitwiseAll("flags", BwFlags.HAS_BULK + BwFlags.HAS_COLOUR)
      Parameters:
      propertyName - The property that holds the flags value
      flags - The flags we are looking for

    • bitwiseNot

      ExpressionList<T> bitwiseNot(String propertyName, long flags)
      Add expression for the given bit flags to be NOT set. 
      

 where().bitwiseNot("flags", BwFlags.HAS_COLOUR)
      Parameters:
      propertyName - The property that holds the flags value
      flags - The flags we are looking for

    • bitwiseAnd

      ExpressionList<T> bitwiseAnd(String propertyName, long flags, long match)
      Add bitwise AND expression of the given bit flags to compare with the match/mask. 

      

 // Flags Bulk + Size = Size
 // ... meaning Bulk is not set and Size is set

 long selectedFlags = BwFlags.HAS_BULK + BwFlags.HAS_SIZE;
 long mask = BwFlags.HAS_SIZE; // Only Size flag set

 where().bitwiseAnd("flags", selectedFlags, mask)
      Parameters:
      propertyName - The property that holds the flags value
      flags - The flags we are looking for

    • raw

      ExpressionList<T> raw(String raw, Object value)
      Add raw expression with a single parameter.

      The raw expression should contain a single ? or ?1 at the location of the parameter. We use ?1 when binding a collection for an IN expression.

      When properties in the clause are fully qualified as table-column names then they are not translated. logical property name names (not fully qualified) will still be translated to their physical name.

      Examples:

      

   // use a database function
   raw("add_days(orderDate, 10) < ?", someDate)

   raw("name like ?", "Rob%")

   raw("name in (?1)", asList("Rob", "Fiona", "Jack"))

   raw("name = any(?)", asList("Rob", "Fiona", "Jack"))

      Subquery examples:

      

   // Bind collection using ?1
   .raw("id in (select c.id from o_customer c where c.name in (?1))", asList("Rob", "Fiona", "Jack"))

   // Using Postgres ANY expression
   .raw("t0.customer_id in (select customer_id from customer_group where group_id = any(?::uuid[]))", groupIds)

    • raw

      ExpressionList<T> raw(String raw, Object... values)
      Add raw expression with an array of parameters.

      The raw expression should contain the same number of ? or ?1, ?2 ... bind parameters as there are values. We use ?1, ?2 etc when binding a collection for an IN expression.

      When properties in the clause are fully qualified as table-column names then they are not translated. logical property name names (not fully qualified) will still be translated to their physical name.

      Examples:

      

   raw("unitPrice > ? and product.id > ?", 2, 3)

   raw("(status = ? or (orderDate < ? and shipDate is null) or customer.name like ?)",
         Order.Status.APPROVED,
         new Timestamp(System.currentTimeMillis()),
         "Rob")

    • raw

      ExpressionList<T> raw(String raw)
      Add raw expression with no parameters.

      When properties in the clause are fully qualified as table-column names then they are not translated. logical property name names (not fully qualified) will still be translated to their physical name. 

      

   raw("orderQty < shipQty")

      Subquery example:

      

   .raw("t0.customer_id in (select customer_id from customer_group where group_id = any(?::uuid[]))", groupIds)

    • rawOrEmpty

      ExpressionList<T> rawOrEmpty(String raw, Collection<?> values)
      Only add the raw expression if the values is not null or empty.

      This is a pure convenience expression to make it nicer to deal with the pattern where we use raw() expression with a subquery and only want to add the subquery predicate when the collection of values is not empty.

      Without inOrEmpty()

      

   query.where() // add some predicates
     .eq("status", Status.NEW);

   // common pattern - we can use rawOrEmpty() instead
   if (orderIds != null && !orderIds.isEmpty()) {
     query.where().raw("t0.customer_id in (select o.customer_id from orders o where o.id in (?1))", orderIds);
   }

   query.findList();

      Using rawOrEmpty()

      Note that in the example below we use the ?1 bind parameter to get "parameter expansion" for each element in the collection. 
      

   query.where()
     .eq("status", Status.NEW)
     // only add the expression if orderIds is not empty
     .rawOrEmpty("t0.customer_id in (select o.customer_id from orders o where o.id in (?1))", orderIds);
     .findList();

      Postgres ANY

      With Postgres we would often use the SQL ANY expression and array parameter binding rather than IN. 
      

   query.where()
     .eq("status", Status.NEW)
     .rawOrEmpty("t0.customer_id in (select o.customer_id from orders o where o.id = any(?))", orderIds);
     .findList();

      Note that we need to cast the Postgres array for UUID types like: 

      

   " ... = any(?::uuid[])"
      Parameters:
      raw - The raw expression that is typically a subquery
      values - The values which is typically a list or set of id values.

    • match

      ExpressionList<T> match(String propertyName, String search)
      Add a match expression.
      Parameters:
      propertyName - The property name for the match
      search - The search value

    • match

      ExpressionList<T> match(String propertyName, String search, Match options)
      Add a match expression with options.
      Parameters:
      propertyName - The property name for the match
      search - The search value

    • multiMatch

      ExpressionList<T> multiMatch(String search, String... properties)
      Add a multi-match expression.

    • multiMatch

      ExpressionList<T> multiMatch(String search, MultiMatch options)
      Add a multi-match expression using options.

    • textSimple

      ExpressionList<T> textSimple(String search, TextSimple options)
      Add a simple query string expression.

    • textQueryString

      ExpressionList<T> textQueryString(String search, TextQueryString options)
      Add a query string expression.

    • textCommonTerms

      ExpressionList<T> textCommonTerms(String search, TextCommonTerms options)
      Add common terms expression.

    • and

      ExpressionList<T> and(Expression expOne, Expression expTwo)
      And - join two expressions with a logical and.

    • or

      ExpressionList<T> or(Expression expOne, Expression expTwo)
      Or - join two expressions with a logical or.

    • not

      ExpressionList<T> not(Expression exp)
      Negate the expression (prefix it with NOT).

    • and

      Junction<T> and()
      Start a list of expressions that will be joined by AND's returning the expression list the expressions are added to.

      This is exactly the same as conjunction();

      Use endAnd() or endJunction() to end the AND junction.

      Note that a where() clause defaults to an AND junction so typically you only explicitly need to use the and() junction when it is nested inside an or() or not() junction. 

      

  // Example: Nested and()

    .where()
    .or()
      .and() // nested and
        .startsWith("name", "r")
        .eq("anniversary", onAfter)
        .endAnd()
      .and()
        .eq("status", Customer.Status.ACTIVE)
        .gt("id", 0)
        .endAnd()
      .order().asc("name")
      .findList();

    • or

      Junction<T> or()
      Return a list of expressions that will be joined by OR's. This is exactly the same as disjunction();

      Use endOr() or endJunction() to end the OR junction. 

      

  // Example: (status active OR anniversary is null)

    .where()
    .or()
      .eq("status", Customer.Status.ACTIVE)
      .isNull("anniversary")
    .order().asc("name")
    .findList();

 
      

  // Example: Use or() to join
  // two nested and() expressions

    .where()
    .or()
      .and()
        .startsWith("name", "r")
        .eq("anniversary", onAfter)
        .endAnd()
      .and()
        .eq("status", Customer.Status.ACTIVE)
        .gt("id", 0)
        .endAnd()
      .order().asc("name")
      .findList();

    • not

      Junction<T> not()
      Return a list of expressions that will be wrapped by NOT.

      Use endNot() or endJunction() to end expressions being added to the NOT expression list. 

      

    .where()
      .not()
        .gt("id", 1)
        .eq("anniversary", onAfter)
        .endNot()

 
      

 // Example: nested not()

   .where()
     .eq("status", Customer.Status.ACTIVE)
     .not()
       .gt("id", 1)
       .eq("anniversary", onAfter)
       .endNot()
     .order()
       .asc("name")
     .findList();

    • conjunction

      Junction<T> conjunction()
      Start (and return) a list of expressions that will be joined by AND's.

      This is the same as and().

    • disjunction

      Junction<T> disjunction()
      Start (and return) a list of expressions that will be joined by OR's.

      This is the same as or().

    • must

      Junction<T> must()
      Start a list of expressions that will be joined by MUST.

      This automatically makes the query a useDocStore(true) query that will execute against the document store (ElasticSearch etc).

      This is logically similar to and().

    • should

      Junction<T> should()
      Start a list of expressions that will be joined by SHOULD.

      This automatically makes the query a useDocStore(true) query that will execute against the document store (ElasticSearch etc).

      This is logically similar to or().

    • mustNot

      Junction<T> mustNot()
      Start a list of expressions that will be joined by MUST NOT.

      This automatically makes the query a useDocStore(true) query that will execute against the document store (ElasticSearch etc).

      This is logically similar to not().

    • endJunction

      ExpressionList<T> endJunction()
      End a junction returning the parent expression list.

      Ends a and(), or(), not(), must(), mustNot() or should() junction such that you get the parent expression.

      Alternatively you can always use where() to return the top level expression list.

    • endAnd

      ExpressionList<T> endAnd()
      End a AND junction - synonym for endJunction().

    • endOr

      ExpressionList<T> endOr()
      End a OR junction - synonym for endJunction().

    • endNot

      ExpressionList<T> endNot()
      End a NOT junction - synonym for endJunction().