The Grid class provided by the Charting API presents a multi-dimensional array facade to a set of analytics result records. It can be used for application layer rendering (such as building tabular displays).

Typically, analytics statements return a list of records. Each result record contains property and/or dimension values representing the GROUP BY values for the bucket along with dynamically computed properties representing the results of Analytics expressions.

For example, an analytics query such as:

RETURN Results AS
SELECT COUNT(TransId) AS TransCount
GROUP BY Region

returns records of the form { Region, TransCount }:

{ Region="NorthEast", TransCount=20 }
{ Region="SouthEast", TransCount=35 }
{ Region="Central",   TransCount=25 }
...

Results such as these, which are grouped by a single dimension, are convenient for rendering a tabular view. But multidimensional groupings are less convenient. For example, consider a query such as:

RETURN Results AS
SELECT COUNT(TransId) AS TransCount
GROUP BY Region, Year

which returns records of the form { Region, Year, TransCount }, for example:

{ Region="NorthEast", Year="2009", TransCount=8  }
{ Region="NorthEast", Year="2010", TransCount=12 }
{ Region="SouthEast", Year="2010", TransCount=35 }
{ Region="Central",   Year="2009", TransCount=25 }
...

This data complicates table or chart rendering. It is not necessarily organized in an order convenient for the rendering code. Furthermore, the sparseness of the results (for example, because there were no 2009 sales in the SouthEast, no result record is returned for that grouping) must be handled.

The Grid class presents a multi-dimensional array facade to a set of analytics result records, providing an interface that is significantly more convenient for application layer rendering (such as building tabular displays).

The Grid constructor requires three parameters:

For example, to create a Grid over the results of the above example, use the following code:

List axes = new List();
axes.add("Region");
axes.add("Year");
Grid grid = new Grid(analyticsStatementResult.getERecIter(),
  "TransCount",axes);

Convenience constructors are provided for one- and two-dimensional grids, so this example could also have been written:

Grid grid = new Grid(analyticsStatementResult.getERecIter(),
  "TransCount","Region","Year");

An initialized Grid provides a multidimensional array interface. It provides access to “label” values (that is, the set of values found in any of the axes specified in the constructor). For example:

List regions = grid.getLabels(0);
List years = grid.getLabels(1);

The returned Lists contain Label objects, each of which contains a property value (String) or a dimension value (DimVal). Given a list representing an array index (that is, a list of values, one from each axis), the Grid returns a Cell object representing the value at that location. For example:

List location = new List();
location.add(regions.get(0));
location.add(years.get(0));
Cell cell = grid.getValue(location);

Convenience accessors are provided for one- and two-dimensional grids, so this example could also have been written simply as:

Cell cell = grid.getValue(regions.get(0),years.get(0));

Cells contain the value for the grid at the specified location (a String), and also allow reverse lookups. Therefore, from a cell, one can get the list of labels for the location of the cell in its containing grid with the call cell.getLabels().