To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Fluent Hibernate criteria query builder for a single entity type, returned by KCriteriaBuilder.build(). Adds projections (count, sum, min, max, average, distinct, group by), joins to associated entities and sort order on top of the restriction methods inherited from BaseCriteriaBuilder, plus terminal execute methods that run the query and return matching rows or aggregated values. Instances are exposed to Velocity templates and JS as the object returned from calling build() on an entity's registered criteria builder, for example services.criteriaBuilders.product.build(), typically used to compute reporting aggregates over a table.
Extends: BaseCriteriaBuilder
Properties
| Property | Returns | Description |
|---|---|---|
| alias | String | The alias this query's entity is registered under, used to reference its properties when this query is joined from another query. |
| criterions | List<Criterion> | NOT available to JS and untrusted code etc |
Inherited from BaseCriteriaBuilder
Methods
likeStartsWith(String propertyName, Object value) · likeAnywhere(String propertyName, Object value) · ilikeAnywhere(String propertyName, Object value) · ilikeStartsWith(String propertyName, Object value) · ilike(String propertyName, Object value) · eq(String propertyName, Object value) · ne(String propertyName, Object value) · ge(String propertyName, Object value) · gt(String propertyName, Object value) · le(String propertyName, Object value) · lt(String propertyName, Object value) · isNull(String propertyName) · isNotNull(String propertyName) · in(String propertyName, Collection value) · in(String propertyName, Object[] value) · nin(String propertyName, Object[] value) · nin(String propertyName, Collection value) · conjunction() · disjunction()
likeStartsWith(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds a case-sensitive "starts with" restriction, matching values of the property that begin with the given value.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the value to match at the start of the property; converted to a string before matching |
likeAnywhere(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds a case-sensitive "contains" restriction, matching values of the property that contain the given value anywhere in the string.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the value to search for within the property; converted to a string before matching |
ilikeAnywhere(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds a case-insensitive "contains" restriction, matching values of the property that contain the given value anywhere in the string, regardless of case.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the value to search for within the property; converted to a string before matching |
ilikeStartsWith(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds a case-insensitive "starts with" restriction, matching values of the property that begin with the given value, regardless of case.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the value to match at the start of the property; converted to a string before matching |
ilike(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds a case-insensitive equality-style "like" restriction, similar to the Postgres ilike operator. Unlike ilikeAnywhere, no wildcard is implied around the value, so it behaves as a case-insensitive equality match unless the caller includes their own wildcard characters in the value.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the value to match against the property; converted to a string before matching |
eq(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds an equality restriction on the named property. Integer values are widened to Long first, because identifier properties are stored as Long and JS numeric values otherwise arrive as Integer.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the value the property must equal |
ne(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds a not-equal restriction on the named property. Integer values are widened to Long first, because identifier properties are stored as Long and JS numeric values otherwise arrive as Integer.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the value the property must not equal |
ge(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds a "greater than or equal to" restriction on the named property. Integer values are widened to Long first, because identifier properties are stored as Long and JS numeric values otherwise arrive as Integer.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the lower bound the property must meet or exceed |
gt(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds a "greater than" restriction on the named property. Integer values are widened to Long first, because identifier properties are stored as Long and JS numeric values otherwise arrive as Integer.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the lower bound the property must exceed |
le(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds a "less than or equal to" restriction on the named property. Integer values are widened to Long first, because identifier properties are stored as Long and JS numeric values otherwise arrive as Integer.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the upper bound the property must meet or fall below |
lt(String propertyName, Object value)
Returns: BaseCriteriaBuilder
Adds a "less than" restriction on the named property. Integer values are widened to Long first, because identifier properties are stored as Long and JS numeric values otherwise arrive as Integer.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the upper bound the property must fall below |
isNull(String propertyName)
Returns: BaseCriteriaBuilder
Adds a restriction that the named property must be null.
| Parameter | Description |
|---|---|
propertyName | the name of the property to check |
isNotNull(String propertyName)
Returns: BaseCriteriaBuilder
Adds a restriction that the named property must not be null.
| Parameter | Description |
|---|---|
propertyName | the name of the property to check |
in(String propertyName, Collection value)
Returns: BaseCriteriaBuilder
Adds a restriction that the named property must equal one of the values in the given collection. Integer values are widened to Long first, because identifier properties are stored as Long and JS numeric values otherwise arrive as Integer.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the collection of allowed values; must not be null |
in(String propertyName, Object[] value)
Returns: BaseCriteriaBuilder
Adds a restriction that the named property must equal one of the values in the given array. Integer values are widened to Long first, because identifier properties are stored as Long and JS numeric values otherwise arrive as Integer.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the array of allowed values; must not be null |
nin(String propertyName, Object[] value)
Returns: BaseCriteriaBuilder
Adds a restriction that the named property must not equal any of the values in the given array.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the array of disallowed values |
nin(String propertyName, Collection value)
Returns: BaseCriteriaBuilder
Adds a restriction that the named property must not equal any of the values in the given collection.
| Parameter | Description |
|---|---|
propertyName | the name of the property to match on |
value | the collection of disallowed values |
conjunction()
Returns: JunctionCriteriaBuilder
Starts a nested AND block: restrictions added to the returned builder are combined with each other using AND, and the whole block is added as a single restriction to this builder.
disjunction()
Returns: JunctionCriteriaBuilder
Starts a nested OR block: restrictions added to the returned builder are combined with each other using OR, and the whole block is added as a single restriction to this builder.
Methods
applySearchQuery(KSearchQuery searchQuery, String textFields) · removeProjections() · timeoutSecs(Integer timeoutSecs) · get(Long id) · distinct() · count(String propertyName) · count(String propertyName, String alias) · countDistinct(String propertyName, String alias) · rowCount(String alias) · distinctProperty(String propertyName, String alias) · min(String propertyName, String alias) · max(String propertyName, String alias) · avg(String propertyName, String alias) · sum(String propertyName) · sum(String propertyName, String alias) · groupBy(String propertyName) · joinOnProp(String propertyName, String alias) · joinOnProp(String propertyName, String alias, String joinType) · sortAsc(String prop) · sortDesc(String prop) · execute(int maxSize) · executeSingle() · execute(SearchProperties properties) · useRecords(int startPos, int pageSize, Integer maxRows, Consumer<Object> c) · getAlias()
applySearchQuery(KSearchQuery searchQuery, String textFields)
Returns: KCriteria
Applies a KSearchQuery's field and free-text terms as restrictions on this query. The exact-match "must" and "must not" field terms are combined with AND or OR according to searchQuery.isCombineWithAnd(); each free-text "must" term is matched case-insensitively against every field named in textFields, combined with OR across those fields.
| Parameter | Description |
|---|---|
searchQuery | the search query supplying the field and free-text terms to apply |
textFields | the property names checked for each free-text search term; ignored if searchQuery has no free-text terms |
removeProjections()
Returns: void
Clears any projections previously added via methods such as count, sum, min, max or groupBy, so the query reverts to returning full entities rather than projected values.
timeoutSecs(Integer timeoutSecs)
Returns: KCriteria
Sets the maximum time, in seconds, the query is allowed to run for before it is cancelled.
| Parameter | Description |
|---|---|
timeoutSecs | the timeout in seconds, or null for no explicit timeout |
get(Long id)
Returns: Object
Adds an equals restriction on the id property and runs the query, returning the single matching entity.
| Parameter | Description |
|---|---|
id | the identifier to look up |
distinct()
Returns: KCriteria
Marks the query to return distinct results, removing duplicate rows caused by joins.
count(String propertyName)
Returns: KCriteria
Adds a count projection on the named property, using the property name as the result alias.
| Parameter | Description |
|---|---|
propertyName | the property to count |
count(String propertyName, String alias)
Returns: KCriteria
Adds a count projection on the named property.
| Parameter | Description |
|---|---|
propertyName | the property to count |
alias | the alias to expose the count under in the results, or null to use the default alias |
countDistinct(String propertyName, String alias)
Returns: KCriteria
Adds a count-distinct projection on the named property, counting only its distinct values.
| Parameter | Description |
|---|---|
propertyName | the property to count distinct values of |
alias | the alias to expose the count under in the results, or null to use the default alias |
rowCount(String alias)
Returns: KCriteria
Adds a row count projection, counting the number of matching rows.
| Parameter | Description |
|---|---|
alias | the alias to expose the count under in the results, or null to use the default alias |
distinctProperty(String propertyName, String alias)
Returns: KCriteria
Adds a projection that returns the distinct values of the named property, rather than the full entity.
| Parameter | Description |
|---|---|
propertyName | the property whose distinct values are projected |
alias | the alias to expose the projected values under in the results, or null to use the default alias |
min(String propertyName, String alias)
Returns: KCriteria
Adds a minimum-value projection on the named property.
| Parameter | Description |
|---|---|
propertyName | the property to find the minimum value of |
alias | the alias to expose the minimum under in the results, or null to use the default alias |
max(String propertyName, String alias)
Returns: KCriteria
Adds a maximum-value projection on the named property.
| Parameter | Description |
|---|---|
propertyName | the property to find the maximum value of |
alias | the alias to expose the maximum under in the results, or null to use the default alias |
avg(String propertyName, String alias)
Returns: KCriteria
Adds an average-value projection on the named property.
| Parameter | Description |
|---|---|
propertyName | the property to average |
alias | the alias to expose the average under in the results, or null to use the default alias |
sum(String propertyName)
Returns: KCriteria
Adds a sum projection on the named property, using the property name as the result alias.
| Parameter | Description |
|---|---|
propertyName | the property to sum |
sum(String propertyName, String alias)
Returns: KCriteria
Adds a sum projection on the named property.
| Parameter | Description |
|---|---|
propertyName | the property to sum |
alias | the alias to expose the sum under in the results, or null to use the default alias |
groupBy(String propertyName)
Returns: KCriteria
Adds the named property to the query's group-by clause, for use alongside aggregate projections such as count or sum.
| Parameter | Description |
|---|---|
propertyName | the property to group by |
joinOnProp(String propertyName, String alias)
Returns: KCriteria
Joins to the entity associated with the named property using an inner join, returning a new query builder scoped to the joined entity under the given alias.
| Parameter | Description |
|---|---|
propertyName | the name of the association property to join on |
alias | the alias to assign the joined entity, used to reference its properties in later restrictions |
joinOnProp(String propertyName, String alias, String joinType)
Returns: KCriteria
Joins to the entity associated with the named property using the given join type, returning a new query builder scoped to the joined entity under the given alias.
| Parameter | Description |
|---|---|
propertyName | the name of the association property to join on |
alias | the alias to assign the joined entity, used to reference its properties in later restrictions |
joinType | the Hibernate join type to use, for example "INNER_JOIN" or "LEFT_OUTER_JOIN" |
sortAsc(String prop)
Returns: BaseCriteriaBuilder
Adds an ascending sort order on the named property.
| Parameter | Description |
|---|---|
prop | the property to sort by |
sortDesc(String prop)
Returns: BaseCriteriaBuilder
Adds a descending sort order on the named property.
| Parameter | Description |
|---|---|
prop | the property to sort by |
execute(int maxSize)
Returns: List
Runs the query and returns up to maxSize matching rows, starting from the first result.
| Parameter | Description |
|---|---|
maxSize | the maximum number of rows to return; must be MAX_RESULTS (10000) or less |
executeSingle()
Returns: Object
Runs the query for at most one row and returns it.
execute(SearchProperties properties)
Returns: List
Runs the query with the given paging properties and returns the matching rows, or projected values if a projection has been added. Yields to the Governor before running, and marks the query cacheable.
| Parameter | Description |
|---|---|
properties | the paging properties (page, page size) to apply, or null to run without paging |
useRecords(int startPos, int pageSize, Integer maxRows, Consumer<Object> c)
Returns: void
Iterates over the query's results in pages, invoking the given consumer for each row, until maxRows rows have been consumed or a page returns fewer rows than pageSize. Yields to the Governor between rows.
| Parameter | Description |
|---|---|
startPos | the zero-based offset of the first row to fetch |
pageSize | the number of rows to fetch per page |
maxRows | the maximum number of rows to pass to the consumer, or null for no limit |
c | the consumer invoked once for each row |
getAlias()
Returns: String
The alias this query's entity is registered under, used to reference its properties when this query is joined from another query.
© 2025 Kademi Ltd