Projections & Aggregates

Search…
v3.x
Hibernate also supports the ability to work with projections and aggregates.  Instead of treating the results as an array of objects or a stream of objects you can return the result as a row with columns or a projection of the data.  This is similar to how you use to select data in a cfquery call.
This is great for API driven applications as you DON"T have to retrieve the entire object graphs, you can decide which columns to bring back and return an array of structs with lightening speed.
There are several projection types you can use which are great for doing counts, distinct counts, max values, sums, averages and much more. 
withProjections()
The method in the criteria builder that will allow you to add projections is called withProjections().  You will then use it's arguments to tell Hibernate what projection or aggregates to compile into the query.  Here is the method signature:
1
/**
2
 * Setup projections for this criteria query, you can pass one or as many projection arguments as you like.
3
 * The majority of the arguments take in the property name to do the projection on, which will also use that as the alias for the column
4
 * or you can pass an alias after the property name separated by a : Ex: projections(avg="balance:avgBalance")
5
 * The alias on the projected value can be referred to in restrictions or orderings.
6
 * Please also note that the resulting array locations are done in alphabetical order of the arguments.
7
 *
8
 * @avg The name of the property to avg or a list or array of property names
9
 * @count The name of the property to count or a list or array of property names
10
 * @countDistinct The name of the property to count distinct or a list or array of property names
11
 * @distinct The name of the property to do a distinct on, this can be a single property name a list or an array of property names
12
 * @groupProperty The name of the property to group by or a list or array of property names
13
 * @id The projected identifier value
14
 * @max The name of the property to max or a list or array of property names
15
 * @min The name of the property to min or a list or array of property names
16
 * @property The name of the property to do a projected value on or a list or array of property names
17
 * @rowCount Do a row count on the criteria
18
 * @sum The name of the property to sum or a list or array of property names
19
 * @sqlProjection Do a projection based on arbitrary SQL string
20
 * @sqlGroupProjection Do a projection based on arbitrary SQL string, with grouping
21
 * @detachedSQLProjection Do a projection based on a DetachedCriteria builder config
22
 */
23
any function withProjections(
24
	string avg,
25
	string count,
26
	string countDistinct,
27
	any distinct,
28
	string groupProperty,
29
	boolean id,
30
	string max,
31
	string min,
32
	string property,
33
	boolean rowCount,
34
	string sum,
35
	any sqlProjection,
36
	any sqlGroupProjection,
37
	any detachedSQLProjection
38
){
Copied!
Arguments
Below are the available projections you can use from this method
Transform
Description
Example
avg
The name of the property to avg or a list or array of property names
withProjections(avg="salary")
count
The name of the property to count or a list or array of property names
withProjections(count="comments")
countDistinct
The name of the property to count distinct or a list or array of property names
withProjections(countDistinct="email")
distinct
The name of the property to do a distinct on, this can be a single property name a list or an array of property names
withProjections(distinct="email")
groupProperty
The name of the property to group by or a list or array of property names
withProjections(groupproperty="lastName")
id
Return the projected identifier value
withProjections(id=true)
max
The name of the property to max or a list or array of property names
withProjections(max="lastLogin")
min
The name of the property to min or a list or array of property names
withProjections(min="cid")
property
The name of the property to do a projected value on or a list or array of property names
withProjections(property="firstname")
rowCount
Do a row count on the criteria
withProjections(rowcount=true)
sum
The name of the property to sum or a list or array of property names
withProjections(sum="balance")
sqlProjection
Return projected value for sql fragment. Can accept a single config {sql,alias,property}, or an array of multiple configs.
withProjections(sqlProjection={sql="SELECT count(  ) from blog where Year < 2006 and Author={alias}.Author", 
alias="BlogPosts", 
property="Author" })*
sqlGroupProjection
Return projected value for sql fragment with grouping. Can accept a single config( sql,alias,property,group}, or an array of multiple configs.
withProjections(sqlGroupProjection={sql="SELECT count(  ) from blog where Year < 2006 and Author={alias}.Author", 
alias="BlogPosts", 
property="Author", 
group="Author" })*
detachedSQLProjection
Creates a sqlProjection() based on Detached Criteria Builder
See Detached Criteria Builder​
The value of the arguments is one, a list or an array of property names to run the projection on, with the exception of id and rowcount which take a boolean true. 
Aliases
Also, you can pass in a string separated with a : to denote an alias on the property when doing the SQL. The alias can then be used with any restriction the criteria builder can use.
1
Ex: avg="balance", avg="balance:myBalance", avg="balance, total", avg=["balance","total"]
Copied!
If the :alias is not used, then the alias becomes the property name.
Examples
1
// Using native approach for one projection only
2
var results = c.like("firstName","Lui%")
3
     .and( 
4
          c.restrictions.between( "balance", 200, 300),
5
          c.restrictions.eq("department", "development")
6
     )
7
     .setProjection( c.projections.rowCount() )
8
     .get();
9
​
10
// Using the withProjections() method, which enables you to do more than 1 projection
11
var results = c.like("firstName","Lui%")
12
     .and( 
13
          c.restrictions.between( "balance", 200, 300),
14
          c.restrictions.eq("department", "development")
15
     )
16
     .withProjections(rowCount=1)
17
     .get();
18
​
19
var results = c.like("firstName","Lui%")
20
     .and( 
21
          c.restrictions.between( "balance", 200, 5000),
22
          c.restrictions.eq("department", "development")
23
     )
24
     .withProjections(avg="balance,total",max="total:maxTotal")
25
     .gt("maxTotal",500)
26
     .list();
27
     
28
var results = c
29
     .withProjections( property="id,name,username" )
30
     .isTrue( "isActive" )
31
     .asStruct()
32
     .list();
Copied!
Projections
Here is a detail overview of each projection type.
avg()
The name of the property to average or a list or array of property names
1
withProjections( avg = "salary" )
Copied!
​
Associations
Next - Criteria Queries
Detached Criteria Builder
Last modified 5mo ago
Copy link
Contents