public interface ServerSummaries

Server Summaries

In Smart GWT, "summarization" refers to applying functions to DataSource fields to obtain summary records calculated from the values of multiple DataSource records.

For example, by applying an "average" function to a DataSourceField representing the dollar value of an order, you can calculate the average dollar amount of a set of orders.

Client-side calculation of summary records is a listGrid feature. Server Summaries is a feature of the Smart GWT Server allowing similar summaries to be computed server-side, generally by the database engine itself.

See also the related feature which allows a single field to receive a value summarized from several related records, DataSourceField.includeSummaryFunction.

The Server Summaries feature is available with Power or better licenses only. See smartclient.com/product for details.

Summarization can be statically configured directly in a .ds.xml file, or can be dynamically configured when sending a DSRequest, either client-side or server-side. The following examples all assume a DataSource with fields like this:

  <DataSource ID="dsOrders" ...>
       <fields>
           <field name="customerName" type="text" />
           <field name="orderDate" type="date" />
           <field name="deliveryStatus" type="string" />
           ...
       </fields>
  </DataSource>
  

Summaries in DataSource .ds.xml files

You can declare summarization directly on an operationBinding in a .ds.xml file, using OperationBinding.summaryFunctions and OperationBinding.groupBy. For example:

   <DataSource ID="dsOrders" ...>
       ...
       <operationBindings>
           <operationBinding operationType="fetch" operationId="lastOrderDateByCustomer">
               <summaryFunctions>
                   <orderDate>max</orderDate>
               </summaryFunctions>
               <groupBy>customerName</groupBy>
           </operationBinding>
       </operationBindings>
   </DataSource>
  

This would return summary records representing the most recent order per customer. Represented in JSON, the returned records would look like:

    { customerName: "JBar Struts", orderDate:"2012/02/05" },
    { customerName: "KFoo Widgets", orderDate:"2012/03/01" },
    ...
  

This is analogous to the result of a SQL query like:

  SELECT
   max(order.orderDate)
   order.customerName
  FROM
   order
  GROUP BY
   order.customerName
  

Note that, as with SQL, the returned records will only include the fields where summary functions were applied or which were used for grouping - "deliveryDate" and other fields are not included because in general, summary records may represent data from more than one record (there may be more than one record with the "max" value, and consider also "sum" or "avg" functions), so it's ambiguous which record's values should be returned for non-grouped, non-summarized fields.

Dynamically Requested Summaries

DSRequest.summaryFunctions and DSRequest.groupBy allow you to dynamically request a server summary from client-side code. For example:

   DSRequest requestProperties = new DSRequest();
   requestProperties.setGroupBy("customerName");
   requestProperties.setSummaryFunctions(new HashMap() {{
      put("orderDate", SummaryFunctionType.MAX);
   }});
   dsOrders.fetchData(null, callback, request);
  

By default such requests are allowed, but such requests can be disallowed on a per-DataSource or system-wide level if you have concerns - see DataSource.allowClientRequestedSummaries.

You can also dynamically request summaries from server-side code (for example, in a DMI method):

    DSRequest dsRequest = new DSRequest("dsOrders", "fetch");
    dsRequest.setSummaryFunctions(new HashMap() {{
      put("orderDate", SummaryFunctionType.MAX);
    }});
    dsRequest.setGroupBy("customerName");
    DSResponse dsResponse = dsRequest.execute();
  

Criteria, Sort & Data Paging

Criteria and sort directions are supported for queries that involve server summarization.

Criteria apply to record before summaries are applied. For example, if the "avg" function is being applied to a "price" field, criteria like "price < 5" will eliminate records where price is less than 5 before the average price is calculated. This means that client-side filtering may not work as expected with summarized results: client-side filter criteria are necessarily applied after summary functions have been applied, so may not match the server's behavior. You can set ResultSet.useClientFiltering to disable client-side filtering on a grid via ListGrid.dataProperties. Or individual fields can be marked canFilter:false.

Sort directions may only target fields that are returned by the query (only those fields included in groupBy or where a summaryFunction was applied).

Data paging is also supported, however, consider that for aggregated queries, when asked for a second page of data, the database is likely to have to repeat all the work of calculating aggregated values. Turning paging off or setting a generous ListGrid.dataPageSize is advised.

SQL Templating

SQL Templating is also supported with server summaries. Clause-by-clause substitution works normally.

Fields with customSelectExpression

Fields with customSelectExpression can be used with server summaries as both groupBy fields or fields with summaryFunction. In case of summaryFunction requested on field with customSelectExpression we will wrap SQL function around the expression, which may or may not be correct.

Summarizing without Grouping

Declaring just <summaryFunctions> without declaring <groupBy> is allowed. This will always give you exactly one summary record in the result, which will represent the summary functions as applied to all records that match the criteria in the DSRequest.

Grouping without Summarizing

Declaring just <groupBy> without <summaryFunctions> is also allowed. This gives results similar to a SQL "select distinct": one record per distinct set of values for the grouped fields. This kind of result can be used in various ways; one common use case is populating a ComboBoxItem with a list of existing values for a field that already appear in DataSource records.

Check out this example of grouping without summarizing being used to determine all unique values of a field.