Version 36 (modified by Dominic König, 11 years ago) ( diff )



S3Report is a REST method handler for data analysis.

S3Report currently exists in two versions: S3Report (based on S3Search, to be deprecated) and S3Report2 (based on Ajax filter forms). Any new pages should always use S3Report2 (URL method /report2).


S3Report generates a full page which includes a set of S3Search widgets, a pivot table (a.k.a. contingency table) from S3Resources and graphs based on the Pivot Tables.


There are currently 2 versions:


S3Report supports grouping and aggregation by virtual fields - however, using this without care can lead to severe scalability problems:

With large numbers of records involved it can take a long time to compute all virtual field values - and especially where this involves additional database lookups it may quickly exhaust any available bandwidth. Example calculation:

Records in the tableNumber of virtual fields with DB lookupsConcurrent usersTotal number of queries

Unless you're running on a super-computer, such a scenario would take your site beyond any reasonable response times - and users may end up waiting forever to get their report (make sure your site has a reasonable timeout for requests).

Without virtual fields, you have a very different scenario:

Records in the tableNumber of virtual fields with DB lookupsConcurrent usersTotal number of queries

Therefore, it is strongly recommended to minimize (better: avoid) the use of virtual fields which include additional DB lookup as rows, cols or fact parameter in reports wherever large numbers of records can be expected.

URL Methods

S3Report responds to the /report URL method (S3Report2 uses /report2), for all resources (generic method).

The following parameters are accepted:

rowsthe name of the field to be used for the table rowsyes
colsthe name of the field to be used for the table columnsno (if no cols are specified, all instance values appear in 1 column)
factS3Report: the name of the fact field, S3Report2: aggregation function fact=method(selector)yes
aggregatethe aggregation methodno longer supported in S3Report2, use fact=method(selector) syntax instead
tablewhether to hide the pivot table (table=0) or show it (table=1)no
chartrender as chart by default, format: chart=<type>:<dimension>no

rows, cols and fact support the same options as list_fields:

  • fields in the table
  • virtual fields in the table
  • fields/virtual fields in tables linked by foreign keys ($-notation)

The chart option accepts:

  • type: piechart|barchart|breakdown
  • dimension: rows|cols

S3Report supports a number of aggregation functions. The following functions have been tested so far:

lista comma-separated list of all instance values
countthe number of instance values
sumthe sum of all instance values
avgthe average (mean) of all instance values


$-notation for references:

reduced parameter list:

Report Options

Table configurations can contain a report_options item, which is a Storage object. This object is used to configure reports and report options form.

The rows, cols, facts and aggregate items are lists of available values for the user to select from.

The defaults property is a Storage object that contains the default values for the report. It can contain a value for rows, cols, fact, aggregate and totals (as described in URL Methods).

The search property is a list of S3Search widgets that will allow the report to be filtered. If no search property is specified, no filter form will be available.

Here is an example of a report_options item:

                # Older versions of S3Report used this syntax (no longer supported):
                        label = T("Project"),
                        field = "project_id",

All items in report_options and defaults are optional.

If fact and methods are configured like:

   report_options = Storage(
       fact = [selector1, selector2, selector3],
       methods = [method1, method2], # methods can be omitted, falls back to a list of all supported methods

then S3Report will automatically provide a selection of all (mathematically) meaningful field-method-combinations. Some of these combinations may not be relevant for the use-case, though. To specify field-method-combinations instead, you can configure it like:

   report_options = Storage(
       fact = [
               # Older versions of S3Report used this syntax (no longer supported):
               #(field1, method1),
               #(field2, method1),
               #(field2, method2),
               #(field3, method1),

Optionally, you can define a custom label for each combination (which will be used in the select list):

   report_options = Storage(
       fact = [
               (T("ReportLabel1"), method(selector1)"),
               (T("ReportLabel2"), method(selector2)"),
               (T("ReportLabel3"), method(selector3)"),
               # Older versions of S3Report used this syntax (no longer supported):
               #(field1, method1, T("My Report A")),
               #(field2, method1, T("My Report B")),
               #(field2, method2, T("My Report C")),
               #(field3, method1, T("My Report D")),

Report UI Options

Show/Hide Report Option Fields

This can be done with the deployment setting:

settings.ui.hide_report_options = False # default = True

Future Plans

See BluePrint/Reporting

Note: See TracWiki for help on using the wiki.