Groups, Sorting & Filtering

A group has a name, an expression, and up to two sections.

The important consequence is that a group compares neighbouring rows. It does not collect all the rows with the same value. If the same category shows up again later in the data, a new group starts, with another header, another subtotal and, with startNewPage, another page. The data therefore has to arrive already ordered by the group expressions, either through the report query or through sortField, as the official documentation states. With the sample data used below (77 rows over three categories), a template without sorting rendered 4 pages when the rows were already in category order and 25 pages when the same rows were shuffled, because almost every row started a new group on a new page.

The figure shows the same thing with bands: rows go through a sort and a filter, every change of the group expression is a break, and each group prints its header, its details and its footer.

Groups can be nested. Groups are declared in the template from the outermost to the innermost, and when an outer group breaks all the groups declared after it start again, so a category group followed by a month group prints each month heading inside each category. Any number of groups can be declared, and each one has its own header, footer and attributes.

Derived from the JasperReports sample: data grouping (the jasper sample).

The group element has attributes that control paging. In the v7 JRXML they are written without the is prefix that the version 6 syntax used for the boolean ones. The 6.x attribute names such as isStartNewPage that are quoted in older books are rejected by the 7.0.8 parser (it fails with an unrecognised-field error pointing at the attribute), so a template that is migrated by hand needs startNewPage, keepTogether and reprintHeaderOnEachPage. Opening the 6.x file in Jaspersoft Studio 7 converts it.

A few of these deserve more detail.

startNewPage is the simplest way to give each category its own page, which is what a printed sales report usually wants. It is evaluated on every group break, including the first row of the report, so the first group does not leave an empty first page (the title band is printed on the first page, and the group starts right after it).

keepTogether and minHeightToStartNewPage both avoid a group that starts at the bottom of a page with a heading and one row, but they do it differently. minHeightToStartNewPage is a fixed amount of space in pixels: the group starts on the new page whenever fewer pixels remain. keepTogether is based on the real size of the group, but only for its first break attempt: a group that is longer than a whole page cannot be kept together and is split anyway. In version 6 the attribute that stops a band from splitting was called isSplitAllowed, and in 7.0 it is splitType on the band, which the JRXML Report Design page covers.

footerPosition matters when the footer of the last group should look like the bottom of a form, for example a signature or terms area. StackAtBottom moves the footer to the bottom of the page and stacks the footers of the outer groups below it; ForceAtBottom renders it at the very bottom of the page and forces whatever follows to the next page; CollateAtBottom is a weak setting that only takes effect when all the outer group footers are also at the bottom. The details of each value are in the JRGroup API documentation.

reprintHeaderOnEachPage is what makes a long group readable: with it, page 2 of a long category starts with the category heading again. The column header band is separate and is printed on every page by default.

Derived from the JRGroup API and the jasper sample.

Maven coordinates for this and the following JasperReports pages are the ones from Getting Started with Spring Boot; the artifacts used here are jasperreports (the engine), jasperreports-pdf (the PDF exporter), jasperreports-fonts (DejaVu fonts for containers without system fonts) and jasperreports-jdt (the Eclipse compiler used to compile the expressions).

The template below is src/main/resources/reports/sales-by-category.jrxml. It groups sales by category, sorts them, filters out the rows below a minimum quantity, prints the month only when it changes, and totals each category and the whole report.

In the v7 syntax title, columnHeader, pageFooter and summary hold their elements directly, while detail, groupHeader and groupFooter hold band elements, because those three sections can contain several bands. Putting a band inside title or pageFooter, which is the 6.x shape, does not match the v7 structure.

The Java side compiles the template once, fills it from a JRBeanCollectionDataSource and exports the PDF. The data class is an ordinary bean with getters. A Java record does not work as a bean data source row in 7.0.8 (checked in this run: the fill fails with "Error retrieving field value from bean"), because the engine looks for JavaBeans getX() methods and a record only has x() accessors. Use a class with getters, or a Map data source, and convert the records first.

Running it produced a 4-page PDF. Reading its text back showed the three groups in alphabetical order (Fiction on pages 1 and 2, Poetry on page 3, Science on page 4), each starting on a new page, the "Category: Fiction" heading repeated at the top of page 2, the footer lines 51 sales in Fiction 1.071,66, 5 sales in Poetry 46,10 and 12 sales in Science 274,98 (decimal separators follow the default locale of the machine that ran it), and the grand total on the last page. The Fiction group has 60 rows of which 9 have quantity 0, so the filter removed them and the count is 51. An immutable Map.of(...) as the parameters map made fillReport throw UnsupportedOperationException in the same run, so pass a HashMap. Derived from the JasperReports data source sample and the jasper sample.

Groups need ordered data, and there are two places to order it.

The first is the query. For a report that runs an SQL query, ordering there is the fastest option because the database does the work and the engine can stream the rows:

The second is the sortField element, which orders the rows inside the engine, whichever data source they came from. That is the only choice when the rows come from a Java collection, a JSON document or a CSV file, as in the example above. A sortField is placed between the field and variable declarations and the groups, and takes the name of a field and an optional order, Ascending (the default) or Descending. Several sortField elements sort by the first one, then the second as a tie-breaker, and so on. Its type attribute can name a variable instead of a field (type="Variable"), which the template compiled with in this run; it was not filled in that check, so verify the result against your own data before relying on it.

The order of the sort fields must start with the group expressions, in the order the groups are declared, and then add whatever order the details should have inside the last group. In the example the details are ordered by month and then by amount descending, which is why the month cell can print only when its value changes. Because the engine must see every row before it can output the first one in order, sorting inside the engine reads the whole data source first; for a very large report prefer ORDER BY in the query, and see Generating Reports from Databases & Services for ways to feed the engine.

A group expression does not have to be a plain field: it can be any expression, and the official sample groups shipping data by the first letter of a name and then by country. The data must be ordered consistently with that expression, so expose the same value as a field or sort in the query. A mismatch between the group expression and the sort order is the usual cause of the "one page per row" result described earlier.

Derived from the jasper sample and the datasource sample.

A filterExpression is a Boolean expression evaluated for every row before the row reaches the groups, the variables or the detail band. Rows for which it returns false are skipped entirely: they are not counted, not summed and not printed. In the example, $F{quantity} >= $P{MIN_QUANTITY} takes a parameter, so the same compiled template serves "all sales", with a minimum of 0, and "sales of at least one copy", with a minimum of 1, which is what the run above used.

Two practical points follow. First, filtering is done on rows, after the query has delivered them, so when the data comes from SQL a WHERE clause that reaches the database is cheaper than a filterExpression; the expression is the right tool for rules the query cannot express and for data sources that have no query, such as a collection or a JSON file. Second, filtering by the expression is global to the report. To hide a single element conditionally use the element’s own printWhenExpression, and to show an alternative layout when nothing survives the filter use the noData band described in the JRXML Report Design page.

Derived from the datasource sample and the JasperDesign API.

In a grouped detail it is common that one column has the same value on many consecutive rows: the month, the author, the customer. Printing it once and leaving the following cells blank makes the report readable. The element attribute printRepeatedValues="false" does that: the element is printed only when its value differs from the one printed on the previous row. In the example, the month appears once per month, so rows are grouped visually even though the month column is a plain field and not a group.

With only printRepeatedValues="false", the first row of a new page or of a new category can be left without its month when the value happens to equal the previous one. Two further attributes decide when the element is printed again (both compiled with 7.0.8):

The complementary tool is an element-level printWhenExpression, which is a Boolean expression that decides whether a single element is printed at all and is evaluated for every row.

Derived from the jasper sample and the JRElement API.

A group total is a variable that is reset when the group breaks. The variable declares a calculation (Sum, Count, Average, Lowest, Highest, and so on), an expression, and resetType="Group" with resetGroup naming the group. The engine adds the expression value of each row to the variable, and when the group breaks it prints the footer, and only then resets the variable. This order is why the footer shows the total of the group that just ended and the next group’s header does not: the footer belongs to the old group, and the reset happens before the new header.

Footers have a second use: the percentage of the report a group represents. The official sample does this with an expression that divides the group sum by the report sum. When a header needs a value that is only known at the end of its group, for example the number of pages the group used or its total, the text field can be evaluated late: the jasper sample sets evaluationTime="Group" and evaluationGroup on a header element, so the value is computed when the group ends and then placed in the header printed earlier. That is the same mechanism as "page X of Y" with evaluationTime="Report", covered in the expressions page.

Placed in the groupHeader band of the example, that element shows the category total next to the category name even though the total is not known when the header is printed. This fragment is derived from the sample and was not filled as a separate run.

Derived from the jasper sample and the JRVariable API.

A second group declared after the first is nested inside it. The fragment below adds a month group inside category that prints a month heading whenever the month changes, replacing the repeated-value trick for a more visual layout. It has to be declared after the category group, and its sort field must come after the category’s. The attributes and the nested group compiled with JasperReports 7.0.8, together with keepTogether="true", footerPosition="StackAtBottom", preventOrphanFooter="true" and a type="Variable" sort field on the other group, and the parsed group reported those values back.

When the category changes, the month group also breaks, because the outer group’s break reinitialises the inner ones, so every category starts with a month heading even if the month value happens to be the same as the last row of the previous category.

Derived from the jasper sample.

The official documentation names two ways to group. A query can do the aggregation itself with GROUP BY and aggregate functions, and the report then prints the already aggregated rows. The sample documentation lists the advantage as speed, because the engine has less to prepare, and the disadvantage as the loss of nested groups with header and footer bands, so only simplified layouts are possible. Report groups let the template show the details and the aggregates in one layout, at the cost of the engine iterating over all the rows. For a sales report grouped by category with a subtotal under the titles, report groups are the right tool; for a summary table of one total per category, the query is enough and the template can be a plain detail band.

The older books on JasperReports cover groups, sorting and filtering in the DTD-era syntax of the 1.x to 3.x versions, with the 6.x attribute names (isStartNewPage, isReprintHeaderOnEachPage) and <group> elements that contain bands directly. The concepts survived unchanged, but the file format did not (the 7.0 parser is Jackson-based and rejects the old spelling, as described above), and the examples in this page are written from the official documentation and checked against 7.0.8 rather than adapted from those books.