Column Roles

This page describes the concept and use of roles in chart data tables.

What Are Roles?
What Roles Are Available?
Role Hierarchy and Associativity
Assigning a Role

What Are Roles?

Google DataTable and DataView objects now support explicitly assigned column roles. A column role describes the purpose of the data in that column: for example, a column might hold data describing tooltip text, data point annotations, or uncertainty indicators. Most column roles apply to the 'data' column preceding it, whether it is immediately before it or before the first of a consecutive group of role columns. For example, you could have two columns following a 'data' column, one for 'tooltip' and one for 'annotation'. But following the 'domain' column, we also generally allow the 'annotation' and 'annotationText' column roles.

Note: if you're looking to control the content of the tooltips that appear when the user hovers over a chart, see Tooltips.

Originally, there were only two roles available for a column: 'domain', which specifies the major axis values; and 'data', which specifies bar heights, pie slice widths, and so on. These roles were assigned implicitly, based on the order and type of the columns in the table. However, with the ability to explicitly assign column roles, you can now add optional columns that provide new, interesting features to a chart such as arbitrary annotation labels, hovertext, and uncertainty bars.

If you do not explicitly assign a column's role, its role is inferred by the column's order in the table, according to the chart's data format specification. This page will show you what roles are available for you to explicitly assign, and how to assign them.

Here is a comparison of what you can do with a line chart using only the default, inferred roles, compared to additional, explicitly assigned roles.

Line chart data table format:

	Column 0	Column 1	...	Column N
Purpose	X-axis group labels (discrete) X-axis values (continuous)	Line 1 values	...	Line N values
Data Type	string (discrete) number, date, datetime or timeofday (continuous)	number	...	number
Role	domain	data	...	data
Optional supported column roles	annotation annotationText	annotation annotationText certainty emphasis interval scope style tooltip	...	annotation annotationText certainty emphasis interval scope style tooltip

Chart Without Explicit Column Roles	Chart With Explicit Column Roles

This chart does not apply roles explicitly, and so can only use the basic data and domain column layout shown above. DataTable: var data = new google.visualization.DataTable(); data.addColumn('string', 'Month'); // Implicit domain label col. data.addColumn('number', 'Sales'); // Implicit series 1 data col. data.addRows([ ['April',1000], ['May', 1170], ['June', 660], ['July', 1030] ]);	This chart assigns roles explicitly, and so the optional columns can be added. This chart has optional columns for annotation, annotationText, interval, and certainty roles. annotation columns specify static labels in the chart; here, 'A', 'B', 'C' are annotations. annotationText columns specify hovertext when you mouse over the annotation (not the data point). interval columns specify the top and bottom points of I-bars on the chart. There are three I-bars in the chart. certainty columns indicate whether the data at that point is certain. The last data point is uncertain, and so the line leading to it is dashed. DataTable: var data = new google.visualization.DataTable(); data.addColumn('string', 'Month'); // Implicit domain label col. data.addColumn('number', 'Sales'); // Implicit series 1 data col. data.addColumn({type:'number', role:'interval'}); // interval role col. data.addColumn({type:'number', role:'interval'}); // interval role col. data.addColumn({type:'string', role:'annotation'}); // annotation role col. data.addColumn({type:'string', role:'annotationText'}); // annotationText col. data.addColumn({type:'boolean',role:'certainty'}); // certainty col. data.addRows([ ['April',1000, 900, 1100, 'A','Stolen data', true], ['May', 1170, 1000, 1200, 'B','Coffee spill', true], ['June', 660, 550, 800, 'C','Wumpus attack', true], ['July', 1030, null, null, null, null, false] ]);

Chart Without Explicit Column Roles

Chart With Explicit Column Roles

This chart does not apply roles explicitly, and so can only use the basic data and domain column layout shown above.

DataTable:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain label col.
data.addColumn('number', 'Sales'); // Implicit series 1 data col.
data.addRows([
  ['April',1000],
  ['May',  1170],
  ['June',  660],
  ['July', 1030]
]);

This chart assigns roles explicitly, and so the optional columns can be added. This chart has optional columns for annotation, annotationText, interval, and certainty roles.

annotation columns specify static labels in the chart; here, 'A', 'B', 'C' are annotations.
annotationText columns specify hovertext when you mouse over the annotation (not the data point).
interval columns specify the top and bottom points of I-bars on the chart. There are three I-bars in the chart.
certainty columns indicate whether the data at that point is certain. The last data point is uncertain, and so the line leading to it is dashed.

DataTable:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain label col.
data.addColumn('number', 'Sales'); // Implicit series 1 data col.
data.addColumn({type:'number', role:'interval'});  // interval role col.
data.addColumn({type:'number', role:'interval'});  // interval role col.
data.addColumn({type:'string', role:'annotation'}); // annotation role col.
data.addColumn({type:'string', role:'annotationText'}); // annotationText col.
data.addColumn({type:'boolean',role:'certainty'}); // certainty col.
data.addRows([
    ['April',1000,  900, 1100,  'A','Stolen data', true],
    ['May',  1170, 1000, 1200,  'B','Coffee spill', true],
    ['June',  660,  550,  800,  'C','Wumpus attack', true],
    ['July', 1030, null, null, null, null, false]
]);

What Roles Are Available?

The following table lists all the roles suported by Google Charts. Not all roles are supported by all chart types; each chart's documentation will describe which roles are available, and where they go. Roles are rendered differently for different chart types.

Role	Description	Example
annotation	Text to display on the chart near the associated data point. The text displays without any user interaction. Annotations and annotation text can be assigned to both data points and categories (axis labels). There are two styles of annotations: point (default), which draws the annotation text near the specified point, and line, which draws the annotation text on a line that bisects the chart area. You can specify the line style by setting this chart option: `annotations: {'column_id': {style: 'line'}}` Data type: string Default: Empty string	Data: label: 'Year', 'Sales', null, null, 'Expenses', null, null role: domain, data, annotation, annotationText, data, annotation, annotationText '2004', 1000, null, null, 400, null, null '2005', 1170, null, null, 460, 'A', 'Develop new model' '2006', 660, 'B', 'New model launched', 1120, null, null '2007', 1030, null, null, 540, null, null The 'A' and 'B' in this chart are annotations. Hover over the annotation to see the annotation text. Note that you must hover over the annotation, not the data point to which it is applied, to display the annotationText value. Null values are accepted for both annotation and annotationText cells; however, if you have an annotationText value, you must have an associated annotation value.
annotationText	Extended text to display when the user hovers over the associated annotation. Annotations and annotation text can be assigned to both data points and categories (axis labels). If you have an annotationText column, you must also have an annotation column. Tooltip text, in contrast, is displayed when the user hovers over the associated data point on the chart. Data type: string Default: Empty string
certainty	Indicates whether a data point is certain or not. How this is displayed depends on the chart type—for example, it might be indicated by dashed lines or a striped fill. For line and area charts, the segment between two data points is certain if and only if both data points are certain. Data type: boolean, where true is certain, false is uncertain. Default: true
emphasis	Emphasizes specified chart data points. Displayed as a thick line and/or large point. For line and area charts, the segment between two data points is emphasized if and only if both data points are emphasized. Data type: boolean Default: false	Data: label: 'Year', 'Sales', null, 'Expenses', null role: domain, data, emphasis, data, emphasis '2004', 1000, true, 400, false '2005', 1170, true, 460, true '2006', 660, false, 1120, true '2007', 1030, false, 540, true In this chart, the 'Sales' series has one emphasized segment, designated by column three, rows one and two. The 'Expenses' series has two emphasized segments, designated by the fifth column, rows two, three, and four. Note how emphasis requires both bounding points to be emphasized.
interval	Indicates potential data range for a specific point. Intervals are usually displayed as I-bar style range indicators. Interval columns are numeric columns; add interval columns in pairs, marking the low and high value of the bar. Interval values should be added in increasing value, from left to right. Data type: number Default: No interval	Data: label: 'Day', 'Stock value', null, null role: domain, data, interval, interval 'Mon', 38, 20, 45 'Tue', 55, 31, 66 'Wed', 77, 50, 80 'Thurs', 66, 50, 77 In this chart, the interval values define an I-bar surrounding the points. The values increase from left to right. The highest and lowest intervals around a point mark the top and bottom of the bar. Note: for all the details on intervals see Intervals.
scope	Indicates whether a point is in or out of scope. If a point is out of scope, it is visually de-emphasized. For line and area charts, the segment between two data points is in scope if either endpoint is in scope. Data type: boolean, where true means in scope. Default: true	Data: label: 'Year', 'Sales', null, 'Expenses', null role: domain, data, scope, data, scope '2004', 1000, false, 400, true '2005', 1170, false, 460, false '2006', 660, true, 1120, false '2007', 1030, true, 540, false The first scope column applies to the 'Sales' data column to its left. The first segment is rendered out of scope because both boundary points are out of scope. The second scope column applies to the 'Expenses' data column to its left. The first segment is marked as in-scope because one of its boundary points is in scope; the rest of the line is out of scope because all other points are marked as out of scope.
style	Styles certain properties of different aspects of your data. Those values are: `color` `opacity` `stroke-width` `stroke-color` `stroke-opacity` `fill-color` `fill-opacity` Data Type: string, where multiple styles can be applied using a `'firstProperty: value; secondProperty: value'` syntax, or set specific styles for `bar, line,` and `point` by specifying the type and wrapping the style properties inside curly braces (e.g. `bar { //properties go here }`). Default: null	Data: label: 'Character', 'Popularity', 'Style', role: domain, data, style, 'Hulk', 50, 'color: green', 'Captain America', 75, 'color: #0000cf;' + 'stroke-color: #cf001d', 'Wolverine', 90, 'opacity: 0.5;' + 'stroke-width: 5;' + 'stroke-color: #01a0ff;' + 'fill-color: #fff600', 'Iron Man', 60, 'color: #db9500;' + 'stroke-width: 10;' + 'stroke-color: #a30300', 'Spider Man', 100, 'bar {' + 'fill-color: #c8001d;' + 'stroke-width: 3;' + 'stroke-color: #1800c8}' In this chart, each bar is styled independent of the others using the `style` column role. Styles can be set for point, line, or bar specifically (see Spider Man's row), or generally, which will apply the styles to all points, lines, and bars, depending on the type of chart. Note: more details are documented elsewhere on how to customize the style of points, lines, and bars. Also see options for each type of chart where styles can be specified for other kinds of entities, such as areas, text, and boxes.
tooltip	Text to display when the user hovers over the data point associated with this row. Note: this is not supported by the Bubble Chart visualization. The content of Bubble Chart HTML tooltips is not customizable. Data type: string Default: Data point value	Data: label: 'Year', 'Sales', null, 'Expenses', null role: domain, data, tooltip, data, tooltip '2004', 1000, '1M$ sales, 400, '$0.4M expenses in 2004' in 2004' '2005', 1170, '1.17M$ sales, 460, '$0.46M expenses in 2005' in 2005' '2006', 660, '.66$ sales, 1120, '$1.12M expenses in 2006' in 2006' '2007', 1030, '1.03M$ sales, 540, '$0.54M expenses in 2007' in 2007' Hover over the data points to display tooltip text. Tooltip data is assigned to all points in both lines, in columns 3 and 5. Note: for more details on customizing tooltips, see Tooltips.
*domain*	You should not need to assign this role explicitly unless designing a multi-domain chart (shown here); the basic format of the data table enables the charting engine to infer which columns are domain columns. However, you should be aware of which columns are domain columns so that you know which other columns can modify it. Domain columns specify labels along the major axis of the chart. Multiple domain columns can sometimes be used to support multiple scales within the same chart. Data type: Usually string, but occasionally number or date	Data: label: '2009, '2009, '2009, '2008, '2008 '2008 Quarter', Sales', Expenses', Quarter', Sales', Expenses' role: domain, data, data, domain, data, data 'Q1/09', 1000, 400, 'Q1/08', 800, 300 'Q2/09', 1170, 460, 'Q2/08', 750, 400 'Q3/09', 660, 1120, 'Q3/08', 700, 540 'Q4/09', 1030, 540, 'Q4/08', 820, 620 This example demonstrates a multi-domain chart. The first two data columns modify the first domain ("2009 Quarter"), and the last two data columns modify the second domain ("2008 Quarter"). Both domains are overlaid on the same axis scales.
*data*	You should not need to assign this role explicitly; the basic format of the data table enables the charting engine to infer which columns are domain columns. However, you should be aware of which columns are data columns so that you know which other columns can modify it. Data role columns specify series data to render in the chart. For most charts, one column = one series, but this can vary by chart type (for example, scatter charts require two data columns for the first series, and an additional one for each additional series; candlestick charts require four data columns for each series). Data type: number

Role Hierarchy and Associativity

The following diagram shows which role columns can apply to which other role columns. All columns except domain columns apply to the nearest left neighbor to which it can be applied.

So, for example, a scope column applies to the nearest data column on its left; an annotationText column will apply to the nearest annotation column to its left; an annotation will apply to the nearest data or domain column to its left.

Assigning a Role

Roles are assigned as a property of the column in a DataTable object. There are several ways to create a role column, but here are the most common:

DataTable.addColumn()
JavaScript literal notation
DataView.setColumns()

The first two techniques draw the following chart:

DataTable.addColumn Method

The following example creates a bar chart with an interval marker on three of the bars. The interval markers are specified by the third and fourth columns using the DataTable.addColumn() method.

       var data = new google.visualization.DataTable();
       data.addColumn('string', 'Month'); // Implicit domain column.
       data.addColumn('number', 'Sales'); // Implicit data column.
       data.addColumn({type:'number', role:'interval'});
       data.addColumn({type:'number', role:'interval'});
       data.addColumn('number', 'Expenses');
       data.addRows([
         ['April',1000,  900, 1100,   400],
         ['May',  1170, 1000, 1200,   460],
         ['June',  660,  550,  800,  1120],
         ['July', 1030,    ,     ,    540]
       ]);

       var chart = new google.visualization.BarChart(
                document.getElementById('visualization'));
       chart.draw(data,
          {width: 800, height: 600, title: 'Company Performance'});

JavaScript Literal Notation

In JSON literal, you must specify a p property of the column with the value "role":"role-type". The following example demonstrates how to specify roles using JavaScript literal notation. This can only be done at table creation time.

{"cols":[
  {"id":"","label":"Month","pattern":"","type":"string"},
  {"id":"","label":"Sales","pattern":"","type":"number"},
  {"id":"","label":"","pattern":"","type":"number","p":{"role":"interval"}},
  {"id":"","label":"","pattern":"","type":"number","p":{"role":"interval"}},
  {"id":"","label":"Expenses","pattern":"","type":"number"}],
"rows":[
  {"c":[
    {"v":"April","f":null},
    {"v":1000,"f":null},
    {"v":900,"f":null},
    {"v":1100,"f":null},
    {"v":400,"f":null}]},
  {"c":[
    {"v":"May","f":null},
    {"v":1170,"f":null},
    {"v":1000,"f":null},
    {"v":1200,"f":null},
    {"v":460,"f":null}]},
  {"c":[{"v":"June","f":null},
    {"v":660,"f":null},
    {"v":550,"f":null},
    {"v":800,"f":null},
    {"v":1120,"f":null}]},
  {"c":[
    {"v":"July","f":null},
    {"v":1030,"f":null},
    {"v":null,"f":null},
    {"v":null,"f":null},
    {"v":540,"f":null}]}],
"p":null
}

DataView.setColumns Method

When creating a view, you can explicitly set the role of a column. This is useful when creating a new calculated column. See DataView.setColumns() for more information.