DataTable Class

Represents a two-dimensional, mutable table of values. To make a read-only copy of a
DataTable (optionally filtered to show specific values, rows, or columns), create a
DataView.

Each column is assigned a data type, plus several optional properties including an ID, label,
and pattern string.

In addition, you can assign custom properties (name/value pairs) to any cell, row, column, or the
entire table. Some visualizations support specific custom properties; for example the
Table visualization supports
a cell property called 'style', which lets you assign an inline CSS style string to the rendered
table cell. A visualization should describe in its documentation any custom properties that it
supports.

Constructor

Syntax

DataTable(opt_data, opt_version)

opt_data

[Optional] Data used to initialize the table. This can either be the JSON returned by
calling DataTable.toJSON() on a populated table,
or a JavaScript object containing data used to initialize the table. The structure of the
JavaScript literal object is described here. If this parameter is not
supplied, a new, empty data table will be returned.

The DataTable object is used to hold the data passed into a visualization.
A DataTable is a basic two-dimensional table. All data in each column must have the
same data type. Each column has a descriptor that includes its data type, a label for that column
(which might be displayed by a visualization), and an ID, which can be used to refer to a specific
column (as an alternative to using column indexes). The DataTable object also
supports a map of arbitrary properties assigned to a specific value, a row, a column, or the whole
DataTable. Visualizations can use these to support additional features; for example,
the Table visualization uses
custom properties to let you assign arbitrary class names or styles to individual cells.

Each cell in the table holds a value. Cells can have a null value, or a value
of the type specified by its column. Cells optionally can take a "formatted" version
of the data; this is a string version of the data, formatted for display by a visualization.
A visualization can (but is not required to) use the formatted version for display,
but will always use the data itself for any sorting or calculations that it makes
(such as determining where on a graph to place a point). An example might be assigning
the values "low" "medium", and "high" as formatted
values to numeric cell values of 1, 2, and 3.

To add data rows after calling the constructor, you can call either
addRow() for a single row, or
addRows() for multiple rows. You can add columns as
well by calling the addColumn() methods. There are
removal methods for rows and columns as well, but rather than removing rows or columns, consider
creating a DataView that is a selective view of the DataTable.

If you change values in a DataTable after it is passed into a visualization's
draw() method, the changes will not immediately change the chart. You must call
draw() again to reflect any changes.

Note: Google Charts does not perform any
validation on datatables. (If it did, charts would be slower to
render.) If you provide a number where your column is expecting a
string, or vice versa, Google Charts will do its level best to
interpret the value in a way that makes sense, but will not flag
mistakes.

Examples

The following example demonstrates instantiating and populating a DataTable with a
literal string, with the same data as shown in the JavaScript example above:

Should I create my DataTable in JavaScript or object literal notation?

You can create a DataTable either by calling the constructor without parameters and
then adding values by calling the addColumn()/
addRows() methods listed below, or by passing in
a populated JavaScript literal object to initialize it. Both methods are described below. Which
one should you use?

Creating and populating a table in JavaScript by calling addColumn(),
addRow(), and addRows() is very readable code. This method is useful
when you'll be entering code by hand. It is slower than using object literal notation
(described next), but in smaller tables (say, 1,000 cells) you probably won't notice much
difference.

Direct declaration of the DataTable object using object-literal notation
is considerably faster in large tables. However, it can be a tricky syntax
to get right; use this if you can generate the object literal syntax in code,
which reduces possibility of errors.

Methods

Method

Return Value

Description

addColumn(type, opt_label, opt_id)

OR

addColumn(description_object)

Number

Adds a new column to the data table, and returns the index of the new column. All the cells
of the new column are assigned a null value. This method has two signatures:

First signature has the following parameters:

type - A string with the data type of the values of the column. The type can
be one of the following: 'string', 'number', 'boolean', 'date', 'datetime',
and 'timeofday'.

opt_label - [Optional] A string with the label of the column. The
column label is typically displayed as part of the visualization, for example as a column
header in a table, or as a legend label in a pie chart. If no value is specified, an
empty string is assigned.

opt_id - [Optional] A string with a unique identifier for the
column. If no value is specified, an empty string is assigned.

Second signature has a single object parameter with the following members:

Adds a new row to the data table, and returns the index of the new row.

opt_cellArray [optional] A row object, in JavaScript notation,
specifying the data for the new row. If this parameter is not included, this method will
simply add a new, empty row to the end of the table. This parameter is an array of cell
values: if you only want to specify a value for a cell, just give the cell value
(e.g. 55 or 'hello'); if you want to specify a formatted value and/or properties for the
cell, use a cell object (e.g., {v:55, f:'Fifty-five'}). You can
mix simple values and cell objects in the same method call). Use null or an
empty array entry for an empty cell.

Examples:

data.addRow(); // Add an empty row
data.addRow(['Hermione', new Date(1999,0,1)]); // Add a row with a string and a date value.
// Add a row with two cells, the second with a formatted value.
data.addRow(['Hermione', {v: new Date(1999,0,1),
f: 'January First, Nineteen ninety-nine'}
]);
data.addRow(['Col1Val', null, 'Col3Val']); // Second column is undefined.
data.addRow(['Col1Val', , 'Col3Val']); // Same as previous.

addRows(numOrArray)

Number

Adds new rows to the data table, and returns the index of the last added row. You can call
this method to create new empty rows, or with data used to populate the rows, as described
below.

numOrArray - Either a number or an array:

Number - A number specifying how many new, unpopulated rows to add.

Array - An array of row objects used to
populate a set of new rows. Each row is an object as described in
addRow(). Use null or an empty array entry for an empty
cell.

Example:

data.addRows([
['Ivan', new Date(1977,2,28)],
['Igor', new Date(1962,7,5)],
['Felix', new Date(1983,11,17)],
['Bob', null] // No date set for Bob.
]);

Returns the identifier of a given column specified by the column index in the underlying
table.
For data tables that are retrieved by queries, the column identifier is set by the data
source, and can be used to refer to columns when using the
query language. See also:Query.setQuery

getColumnLabel(columnIndex)

String

Returns the label of a given column specified by the column index in the underlying table.
The column label is typically displayed as part of the visualization. For example the column
label can be displayed as a column header in a table, or as the legend label in a pie chart.
For data tables that are retrieved by queries, the column label is set by the data source, or
by the label clause of the
query language. See also:setColumnLabel

getColumnPattern(columnIndex)

String

Returns the formatting pattern used to format the values of the specified column.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

For data tables that are retrieved by queries, The column pattern is set by the data source,
or by the format clause of the query language. An example of a pattern is
'#,##0.00'. For more on patterns see the
query language reference.

getColumnProperties(columnIndex)

Object

Returns a map of all properties for the specified column. Note that the properties object is
returned by reference, so changing values in the retrieved object changes them in the
DataTable.

columnIndex is the numeric index of the column to retrieve properties for.

getColumnProperty(columnIndex, name)

Auto

Returns the value of a named property, or null if no such property is set for
the specified column. The return type varies, depending on the property.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

The returned column type can be one of the following: 'string', 'number', 'boolean',
'date', 'datetime', and 'timeofday'

getDistinctValues(columnIndex)

Array of objects

Returns the unique values in a certain column, in ascending order.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

The type of the returned objects is the same as that returned by the
getValue method.

getFilteredRows(filters)

Array of objects

Returns the row indexes for rows that match all of the given filters. The indexes are
returned in ascending order. The output of this method can be used as input to
DataView.setRows() to change the displayed set
of rows in a visualization.

filters - An array of objects that describe an acceptable cell value. A row
index is returned by this method if it matches all of the given filters. Each
filter is an object with a numeric column property that specifies the index of
the column in the row to assess, plus one of the following:

A value property with a value that must be matched exactly by the cell in the
specified column. The value must be the same type as the column; or

One or both of the following properties, the same type as the column
being filtered:

minValue - A minimum value for the cell. The cell value in the specified
column must be greater than or equal to this value.

maxValue - A maximum value for the cell. The cell value in the specified
column must be less than or equal to this value.

A null or undefined value for minValue (or maxValue) means that
the lower (or upper) bound of the range will not be enforced.

Another optional property, test, specifies a function to be combined with value
or range filtering. The function is called with the cell value, the row and column indices,
and the datatable. It should return false if the row should be excluded from the result.

Returns a sorted version of the table without modifying the order of the underlying data.
To permanently sort the underlying data, call
sort(). You can specify sorting in a number of
ways, depending on the type you pass in to the sortColumns parameter:

A single number specifies the index of the column to sort by. Sorting
will be in ascending order. Example: sortColumns(3) will
sort by the 4th column, in ascending order.

A single object that contains the number of the column index to sort by,
and an optional boolean property desc. If desc is set to true,
the specific column will be sorted in descending order; otherwise, sorting is in
ascending order. Examples: sortColumns({column: 3}) will
sort by the 4th column, in ascending order;
sortColumns({column: 3, desc: true}) will sort by the 4th column, in
descending order.

An array of numbers of the column indexes by which to sort. The first
number is the primary column by which to sort, the second one is the secondary, and so on.
This means that when two values in the first column are equal, the values in the next
column are compared, and so on. Example:
sortColumns([3, 1, 6]) will sort first by the 4th column
(in ascending order), then by the 2nd column (in ascending order), and then by the 7th
column (in ascending order).

An array of objects, each one with the number of the column index to
sort by, and an optional boolean property desc. If desc is set
to true, the specific column will be sorted in descending order (the default is ascending
order). The first object is the primary column by which to sort, the second one is the
secondary, and so on. This means that when two values in the first column are equal, the
values in the next column are compared, and so on. Example:
sortColumn([{column: 3}, {column: 1, desc: true}, {column: 6, desc: true}])
will sort first by the 4th column (in ascending order), then column 2 in descending order,
and then column 7 in descending order.

The returned value is an array of numbers, each number is an index of a
DataTable row. Iterating on the DataTable rows by the order of the
returned array will result in rows ordered by the specified sortColumns. The
output can be used as input to
DataView.setRows() to quickly change the
displayed set of rows in a visualization.

Note that the sorting is guaranteed to be stable: this means that if you sort on equal
values of two rows, the same sort will return the rows in the same order every time.See also:sort

rowIndex should be a number greater than or equal to zero, and less than the
number of rows as returned by the getNumberOfRows() method.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

The type of the returned value depends on the column type (see
getColumnType):

If the column type is 'string', the value is a string.

If the column type is 'number', the value is a number.

If the column type is 'boolean', the value is a boolean.

If the column type is 'date' or 'datetime', the value is a Date object.

If the column type is 'timeofday', the value is an array of four numbers: [hour, minute,
second, milliseconds].

If the cell value is a null value, it returns null.

insertColumn(columnIndex, type [,label [,id]])

None

Inserts a new column to the data table, at the specifid index. All existing columns at or
after the specified index are shifted to a higher index.

columnIndex is a number with the required index of the new column.

type should be a string with the data type of the values of the column. The
type can be one of the following:
'string', 'number', 'boolean', 'date', 'datetime', and
'timeofday'.

label should be a string with the label of the column. The column label is
typically displayed as part of the visualization, for example as a column header in a
table, or as a legend label in a pie chart. If no value is specified, an empty string is
assigned.

id should be a string with a unique identifier for the column. If no value is
specified, an empty string is assigned.

rowIndex should be a number greater than or equal to zero, and less than the
number of rows as returned by the getNumberOfRows() method.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

value [Optional] is the value assigned to the specified cell. To
avoid overwriting this value, set this parameter to undefined; to clear this
value, set it to null. The type of the value depends on the column type (see
getColumnType()):

If the column type is 'string', the value should be a string.

If the column type is 'number', the value should be a number.

If the column type is 'boolean', the value should be a boolean.

If the column type is 'date' or 'datetime', the value should be a Date object.

If the column type is 'timeofday', the value should be an array of four numbers:
[hour, minute, second, milliseconds].

formattedValue [Optional] is a string with the value formatted as a
string. To avoid overwriting this value, set this parameter to undefined; to
clear this value and have the API apply default formatting to value as
needed, set it to null; to explicitly set an empty formatted value, set it to
an empty string. The formatted value is typically used by visualizations to display value
labels. For example the formatted value can appear as a label text within a pie chart.

properties [Optional] is an Object (a name/value map)
with additional properties for this cell. To avoid overwriting this value, set this
parameter to undefined; to clear this value, set it to null.
Some visualizations support row, column, or cell properties to modify their display or
behavior; see the visualization documentation to see what properties are supported.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

label is a string with the label to assign to the column. The column label is
typically displayed as part of the visualization. For example the column label can be
displayed as a column header in a table, or as the legend label in a pie chart.

Sets a single column property. Some visualizations support row, column, or cell properties
to modify their display or behavior; see the visualization documentation to see what
properties are supported.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

name is a string with the property name.

value is a value of any type to assign to the specified named property of the
specified column.

Sets multiple column properties. Some visualizations support row, column, or cell properties
to modify their display or behavior; see the visualization documentation to see what
properties are supported.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

properties is an Object (name/value map) with additional
properties for this column. If null is specified, all additional properties
of the column will be removed.

rowIndex should be a number greater than or equal to zero, and less than the
number of rows as returned by the getNumberOfRows() method.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

formattedValue is a string with the value formatted for display. To clear
this value and have the API apply default formatting to the cell value as needed, set it
formattedValuenull; to explicitly set an empty formatted value, set
it to an empty string.

Sets multiple cell properties. Some visualizations support row, column, or cell properties
to modify their display or behavior; see the visualization documentation to see what
properties are supported.

rowIndex should be a number greater than or equal to zero, and less than the
number of rows as returned by the getNumberOfRows() method.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method.

properties is an Object (name/value map) with additional
properties for this cell. If null is specified, all additional properties of
the cell will be removed.

Sets a single table property. Some visualizations support table, row, column, or cell
properties to modify their display or behavior; see the visualization documentation to see
what properties are supported.

name is a string with the property name.

value is a value of any type to assign to the specified named property of the
table.

Sets multiple table properties. Some visualizations support table, row, column, or cell
properties to modify their display or behavior; see the visualization documentation to see
what properties are supported.

properties is an Object (name/value map) with additional
properties for the table. If null is specified, all additional properties of
the table will be removed.

Sets the value of a cell. In addition to overwriting any existing cell value, this method
will also clear out any formatted value and properties for the cell.

rowIndex should be a number greater than or equal to zero, and less than the
number of rows as returned by the getNumberOfRows() method.

columnIndex should be a number greater than or equal to zero, and less than
the number of columns as returned by the getNumberOfColumns() method. This
method does not let you set a formatted value for this cell; to do that, call
setFormattedValue().

value is the value assigned to the specified cell. The type of the returned
value depends on the column type
(see getColumnType):

If the column type is 'string', the value should be a string.

If the column type is 'number', the value should be a number.

If the column type is 'boolean', the value should be a boolean.

If the column type is 'date' or 'datetime', the value should be a Date object.

If the column type is 'timeofday', the value should be an array of four numbers:
[hour, minute, second, milliseconds].

Sorts the rows, according to the specified sort columns. The DataTable is
modified by this method. See
getSortedRows() for a description of the
sorting details. This method does not return the sorted data.See also:getSortedRowsExample: To sort by the third column and then by the second
column, use: data.sort([{column: 2}, {column: 1}]);

toJSON()

String

Returns a JSON representation of the DataTable that can be passed into the
DataTableconstructor. For
example:

Format of the Constructor's JavaScript Literal
data Parameter

You can initialize a DataTable by passing a JavaScript string literal object into
the data parameter. We'll call this object the data object. You can code this
object by hand, according to the description below, or you can use a
helper Python library if you know how to
use Python, and your site can use it. However, if you want to construct the object by hand, this
section will describe the syntax.

First, let's show an example of a simple JavaScript object describing a table
with three rows and three columns (String, Number, and Date types):

The data object consists of two required top-level properties, cols and
rows, and an optional p property that is a map of arbitrary values.

Note: All property names and string constants shown are case-sensitive. Also,
properties described as taking a string value should have their value enclosed in quotation marks.
For example, if you wish to specify the type property as being number, it would be expressed like
this: type: 'number' but the value itself, as numeric, would be expressed like this:
v: 42

cols Property

cols is an array of objects describing the ID and type of each column. Each property
is an object with the following properties (case-sensitive):

type [Required] Data type of the data in the column. Supports the
following string values (examples include the v: property, described later):

id [Optional] String ID of the column. Must be unique in the table. Use
basic alphanumeric characters, so the host page does not require fancy escapes to access the
column in JavaScript. Be careful not to choose a JavaScript keyword. Example:
id:'col_1'

label [Optional] String value that some visualizations display for this
column. Example: label:'Height'

pattern [Optional] String pattern that was used by a data source to format
numeric, date, or time column values. This is for reference only; you probably won't need to
read the pattern, and it isn't required to exist. The Google Visualization client does not use
this value (it reads the cell's formatted value). If the DataTable has come from a
data source in response to a query with a
format clause, the pattern you
specified in that clause will probably be returned in this value. The recommended pattern
standards are the ICU
DecimalFormat
and
SimpleDateFormat
.

p [Optional] An object that is a map of custom values applied to the cell.
These values can be of any JavaScript type. If your visualization supports any cell-level
properties, it will describe them; otherwise, this property will be ignored.
Example:p:{style: 'border: 1px solid green;'}.

Each row object has one required property called c, which is an array of cells in
that row. It also has an optional p property that defines a map of arbitrary custom
values to assign to the whole row. If your visualization supports any row-level properties it will
describe them; otherwise, this property will be ignored.

Cell Objects

Each cell in the table is described by an object with the following properties:

v [Optional] The cell value. The data type should match the column data
type. If the cell is null, the v property should be null, though it can still have
f and p properties.

f [Optional] A string version of the v value, formatted for
display. Typically the values will match, though they do not need to, so if you specify
Date(2008, 0, 1) for v, you should specify
"January 1, 2008" or some such string for this property. This value is not checked
against the v value. The visualization will not
use this value for calculation, only as a label for display. If omitted, a string version of
v will be automatically generated using the default formatter. The f
values can be modified using your own formatter, or set with setFormattedValue()
or setCell(), or retrieved with getFormattedValue().

p [Optional] An object that is a map of custom values applied to the cell.
These values can be of any JavaScript type. If your visualization supports any cell-level
properties, it will describe them. These properties can be retrieved by the
getProperty() and getProperties() methods.
Example:p:{style: 'border: 1px solid green;'}.

Cells in the row array should be in the same order as their column descriptions in
cols. To indicate a null cell, you can specify null, leave a blank for a
cell in an array, or omit trailing array members. So, to indicate a row with null for the first
two cells, you could specify [ , , {cell_val}] or
[null, null, {cell_val}].

Here is a sample table object with three columns, filled with three rows of data:

The table-level p property is a map of custom values applied to the whole
DataTable. These values can be of any JavaScript type. If your visualization supports
any datatable-level properties, it will describe them; otherwise, this property will be available
for application use.
Example:p:{className: 'myDataTable'}.

DataView Class

A read-only view of an underlying DataTable. A DataView
allows selection of only a subset of the columns and/or rows. It also allows reordering
columns/rows, and duplicating columns/rows.

A view is a live window on the underlying DataTable, not a static snapshot of data.
However, you still must be careful when changing the structure of the table
itself, as described here:

Adding or removing columns from the underlying table will not be reflected by the view,
and might cause unexpected behavior in the view; you will have to create a new
DataView from the DataTable to pick up these changes.

Adding or removing rows from the underlying table is safe and changes will be
propagated to the view immediately (but you must call draw() on any visualizations
after this change to have the new row set rendered). Note that if your view has filtered out
rows by calling one of the setRows() or hideRows() methods, and you add or remove
rows from the underlying table, the behavior is unexpected; you must create a new
DataView to reflect the new table.

Changing cell values in existing cells is safe, and changes are immediately propagated
to the DataView (but you must call draw() on any visualizations after
this change to have the new cell values rendered).

It is also possible to create a DataView from another DataView. Note
that whenever an underlying table or view is mentioned, it refers to the level
immediately below this level. In other words, it refers to the data object used to construct this
DataView.

DataView also supports calculated columns; these are columns whose value is
calculated on the fly using a function that you supply. So, for example, you can include a column
that is a sum of two preceding columns, or a column that calculates and shows the calendar quarter
of a date from another column. See setColumns()
for more details.

When you modify a DataView by hiding or showing rows or columns, the visualization
will not be affected until you call draw() on the visualization again.

You can combine DataView.getFilteredRows() with DataView.setRows() to
create a DataView with an interesting subset of data, as shown here:

Constructors

There are two ways to create a new DataView instance:

Constructor 1

var myView = new google.visualization.DataView(data)

data

A DataTable or DataView used to initialize the view. By default, the
view contains all the columns and rows in the underlying data table or view, in the original
order. To hide or show rows or columns in this view, call the appropriate
set...() or hide...() methods.

Same as the equivalent DataTable methods, except that row/column indexes refer to
the index in the view and not in the underlying table/view.

getTableColumnIndex(viewColumnIndex)

Number

Returns the index in the underlying table (or view) of a given column specified by its index
in this view. viewColumnIndex should be a number greater than or equal to zero,
and less than the number of columns as returned by the getNumberOfColumns()
method. Returns -1 if this is a generated column.

Example: If setColumns([3, 1, 4]) was previously called, then
getTableColumnIndex(2) will return 4.

getTableRowIndex(viewRowIndex)

Number

Returns the index in the underlying table (or view) of a given row specified by its index in
this view. viewRowIndex should be a number greater than or equal to zero, and
less than the number of rows as returned by the getNumberOfRows() method.

Example: If setRows([3, 1, 4]) was previously called, then
getTableRowIndex(2) will return 4.

getViewColumnIndex(tableColumnIndex)

Number

Returns the index in this view that maps to a given column specified by its index in the
underlying table (or view). If more than one such index exists, returns the first (smallest)
one. If no such index exists (the specified column is not in the view), returns -1.
tableColumnIndex should be a number greater than or equal to zero, and less
than the number of columns as returned by the getNumberOfColumns() method of
the underlying table/view.

Example: If setColumns([3, 1, 4]) was previously called, then
getViewColumnIndex(4) will return 2.

getViewColumns()

Array of numbers

Returns the columns in this view, in order. That is, if you call setColumns
with some array, and then call getViewColumns() you should get an identical
array.

getViewRowIndex(tableRowIndex)

Number

Returns the index in this view that maps to a given row specified by its index in the
underlying table (or view). If more than one such index exists, returns the first (smallest)
one. If no such index exists (the specified row is not in the view), returns -1.
tableRowIndex should be a number greater than or equal to zero, and less than
the number of rows as returned by the getNumberOfRows() method of the
underlying table/view.

Example: If setRows([3, 1, 4]) was previously called, then
getViewRowIndex(4) will return 2.

getViewRows()

Array of numbers

Returns the rows in this view, in order. That is, if you call setRows with some
array, and then call getViewRows() you should get an identical array.

hideColumns(columnIndexes)

none

Hides the specified columns from the current view. columnIndexes is an array of
numbers representing the indexes of the columns to hide. These indexes are the index numbers
in the underlying table/view. The numbers in columnIndexes do not have
to be in order (that is, [3,4,1] is fine). The remaining columns retain their index order
when you iterate through them. Entering an index number for a column already hidden is not
an error, but entering an index that does not exist in the underlying table/view will throw
an error. To unhide columns, call setColumns().

Example: If you have a table with 10 columns, and you call
setColumns([2,7,1,7,9]), and then hideColumns([7,9]), the columns
in the view will then be [2,1].

hideRows(min, max)

None

Hides all rows with indexes that lie between min and max (inclusive) from the current view.
This is a convenience syntax for hideRows(rowIndexes) above. For example,
hideRows(5, 10) is equivalent to hideRows([5, 6, 7, 8, 9, 10]).

hideRows(rowIndexes)

None

Hides the specified rows from the current view. rowIndexes is an array of
numbers representing the indexes of the rows to hide. These indexes are the index numbers in
the underlying table/view. The numbers in rowIndexes do not have to be
in order (that is, [3,4,1] is fine). The remaining rows retain their index order. Entering
an index number for a row already hidden is not an error, but entering an index that does
not exist in the underlying table/view will throw an error. To unhide rows, call
setRows().

Example: If you have a table with 10 rows, and you call
setRows([2,7,1,7,9]), and then hideRows([7,9]), the rows in the
view will then be [2,1].

setColumns(columnIndexes)

None

Specifies which columns are visible in this view. Any columns not specified will be hidden.
This is an array of column indexes in the underlying table/view, or calculated columns. If
you don't call this method, the default is to show all columns. The array can also contain
duplicates, to show the same column multiple times. Columns will be shown in the order
specified.

columnIndexes - An array of numbers and/or objects (can be mixed):

Numbers specify the index of the source data column to include in the
view. The data is brought through unmodified. If you need to explicitly define a role
or additional column properties, specify an object with a sourceColumn
property.

Objects specify a calculated column. A calculated column
creates a value on the fly for each row and adds it to the view. The object must have
the following properties:

calc [function] - A function that will be called for each
row in the column to calculate a value for that cell. The function signature is
func(dataTable, row), where
dataTable is the source DataTable, and
row is the index of the source data row. The function should
return a single value of the type specified by type.

type [string] - The JavaScript type of the value that the
calc function returns.

label [Optional, string] - An optional label to
assign to this generated column. If not specified, the view column will have no
label.

id [Optional, string] - An optional ID to assign to
this generated column.

sourceColumn - [Optional, number] The source column
to use as a value; if specified, do not specify the calc or the
type property. This is similar to passing in a number instead of an
object, but enables you to specify a role and properties for the new column.

properties [Optional, object] - An object
containing any arbitrary properties to assign to this column. If not specified,
the view column will have no properties.

role [Optional, string] - A
role to assign to this column. If not
specified, the existing role will not be imported.

Sets the rows in this view to be all indexes (in the underlying table/view) that lie between
min and max (inclusive). This is a convenience syntax for setRows(rowIndexes)
below. For example, setRows(5, 10) is equivalent to
setRows([5, 6, 7, 8, 9, 10]).

setRows(rowIndexes)

None

Sets the visible rows in this view, based on index numbers from the underlying table/view.
rowIndexes should be an array of index numbers specifying which rows to show in
the view. The array specifies the order in which to show the rows, and rows can be
duplicated. Note that only the rows specified in rowIndexes will be
shown; this method clears all other rows from the view. The array can also contain
duplicates, effectively duplicating the specified row in this view (for example,
setRows([3, 4, 3, 2]) will cause row 3 to appear twice in this
view). The array thus provides a mapping of the rows from the underlying table/view to this
view. You can use getFilteredRows() or
getSortedRows() to generate input for
this method.

Example: To create a view with rows three and zero of an underlying
table/view: view.setRows([3, 0])

toDataTable()

DataTable

Returns a DataTable object populated with the visible rows and columns of the
DataView.

toJSON()

string

Returns a string representation of this DataView. Thisstring does not contain the
actual data; it only contains the DataView-specific settings such as visible rows
and columns. You can store this string and pass it to the static
DataView.fromJSON() constructor to recreate this view. This won't include
generated columns.

ChartWrapper Class

A ChartWrapper class is used to wrap your chart and handle all loading, drawing, and
Datasource querying for your chart. The class exposes convenience methods for setting values on
the chart and drawing it. This class simplifies reading from a data source, because you do not
have to create a query callback handler. You can also use it to save a chart easily for reuse.

Another bonus of using ChartWrapper is that you can reduce the number of library
loads by using dynamic loading. Additionally, you don't need to load the packages explicitly
since ChartWrapper will handle looking up and loading the chart packages for you.
See the examples below for details.

However, ChartWrapper currently only propagates a subset of events thrown by charts:
select, ready, and error. Other events are not transmitted through the ChartWrapper instance; to
get other events, you must call getChart() and subscribe to events directly on the
chart handle, as shown here:

Constructor

ChartWrapper(opt_spec)

opt_spec

[Optional] - Either a JSON object defining the chart, or a serialized string version of
that object. The format of this object is shown in the
drawChart() documentation. If not specified, you
must set all the appropriate properties using the set... methods exposed by this
object.

Methods

ChartWrapper exposes the following additional methods:

Method

Return Type

Description

draw(opt_container_ref)

None

Draws the chart. You must call this method after any changes that you make to the chart or
data to show the changes.

opt_container_ref [Optional] - A reference to a valid container element
on the page. If specified, the chart will be drawn there. If not, the chart will be drawn
in the element with ID specified by containerId.

If this chart gets its data from a locally-defined DataTable, will return a
reference to the chart's DataTable. If this chart gets its data from a data
source, it will return null.

Any changes that you make to the returned object will be reflected by the chart the next
time you call ChartWrapper.draw().

getChartType()

String

The class name of the wrapped chart. If this is a Google chart, the name will not be qualified
with google.visualization. So, for example, if this were a Treemap chart,
it would return "Treemap" rather than "google.visualization.treemap".

getChartName()

String

Returns the chart name assigned by setChartName().

getChart()

Chart object reference

Returns a reference to the chart created by this ChartWrapper, for example a
google.visualization.BarChart
or a
google.visualization.ColumnChart
.
This will return null until after you have called draw() on the ChartWrapper
object, and it throws a ready event. Methods called on the returned object will be reflected
on the page.

getContainerId()

String

The ID of the chart's DOM container element.

getQuery()

String

The query string for this chart, if it has one and queries a data source.

getRefreshInterval()

Number

Any refresh interval for this chart, if it queries a data source. Zero
indicates no refresh.

getOption(key, opt_default_val)

Any type

Returns the specified chart option value

key - The name of the option to retrieve. May be a qualified name, such as
'vAxis.title'.

opt_default_value [Optional] - If the specified value is undefined or
null, this value will be returned.

getOptions()

Object

Returns the options object for this chart.

getView()

Object OR Array

Returns the DataView initializer object, in the same format as
dataview.toJSON(), or an array of such objects.

setDataSourceUrl(url)

None

Sets the URL of a data source to use for this
chart. If you also set a data table for this object, the data source URL will be ignored.

setDataTable(table)

None

Sets the DataTable for the chart. Pass in one of the following: null; a DataTable object; a
JSON representation of a DataTable; or an array following the syntax of
arrayToDataTable().

setChartType(type)

None

Sets the chart type. Pass in the class name of the wrapped chart. If this is a Google chart,
do not qualify it with google.visualization. So, for example, for a pie chart,
pass in "PieChart".

setChartName(name)

None

Sets an arbitrary name for the chart. This is not shown anywhere on the chart, unless a custom
chart is explicitly designed to use it.

setContainerId(id)

None

Sets the ID of the containing DOM element for the chart.

setQuery(query_string)

None

Sets a query string, if this chart queries a data source. You must also set the data source
URL if specifying this value.

setRefreshInterval(interval)

None

Sets the refresh interval for this chart, if it queries a data source.
You must also set a data source URL if specifying this value. Zero indicates no refresh.

setOption(key, value)

None

Sets a single chart option value, where key is the option name and value is
the value. To unset an option, pass in null for the value. Note that key may be a
qualified name, such as 'vAxis.title'.

setOptions(options_obj)

None

Sets a complete options object for a chart.

setView(view_spec)

None

Sets a DataView initializer object, which acts as a filter over the underlying
data. The chart wrapper must have underlying data from a DataTable or a data source to apply
this view to. You can pass in either a string or DataView initializer object,
like that returned by dataview.toJSON(). You can
also pass in an array of DataView initializer objects, in which case the first
DataView in the array is applied to the underlying data to create a new data
table, and the second DataView is applied to the data table resulting from
application of the first DataView, and so on.

Events

The ChartWrapper object throws the following events. Note that you must call
ChartWrapper.draw() before any events will be thrown.

Name

Description

Properties

error

Fired when an error occurs when attempting to render the chart.

id, message

ready

The chart is ready for external method calls. If you want to interact with the chart, and call
methods after you draw it, you should set up a listener for this event before you call
the draw method, and call them only after the event was fired.

None

select

Fired when the user clicks a bar or legend. When a chart element is selected, the
corresponding cell in the data table is selected; when a legend is selected, the corresponding
column in the data table is selected. To learn what has been selected, call
ChartWrapper.getChart().getSelection(). Note that this will only be thrown
when the underlying chart type throws a selection event.

None

Example

The following two snippets create an equivalent
line chart. The first example uses JSON
literal notation to define the chart; the second uses ChartWrapper methods to set these values.

ChartEditor Class

The ChartEditor class is used to open an in-page dialog box that enables a user to
customize a visualization on the fly.

To use ChartEditor:

Load the charteditor package.
In google.charts.load(), load
the package 'charteditor'. You do not need to load the packages for the chart type that you
render in the editor; the chart editor will load any package for you as needed.

Create a ChartWrapper object that defines the chart for the user to
customize. This chart will be shown in the dialog, and the user uses the editor to
redesign the chart, change chart types, or even change the source data.

Create a new ChartEditor instance, and register to listen for the "ok"
event. This event is thrown when the user clicks the "OK" button on the
dialog. When received, you should call ChartEditor.getChartWrapper() to retrieve
the user-modified chart.

Call ChartEditor.openDialog(), passing in the
ChartWrapper. This opens the dialog. The dialog buttons enable the user to close
the editor. The ChartEditor instance is available as long as it is in scope; it is
not automatically destroyed after the user closes the dialog.

To update the chart in code, call setChartWrapper().

Methods

Method

Return Value

Description

openDialog(chartWrapper, opt_options)

null

Opens the chart editor as an embedded dialog box on the page. The function returns
immediately; it does not wait for the dialog to be closed. If you do not lose scope of the
instance, you can call openDialog() again to reopen the dialog, although you
must pass in a ChartWrapper object again.

chartWrapper - A ChartWrapper
object defining the initial chart to render in the window. The chart must either have a
populated DataTable, or be connected to a valid data source. This wrapper is
copied internally to the chart editor, so any later changes that you make to your
ChartWrapper handle will not be reflected in the chart editor's copy.

opt_options - [Optional] An object containing any options for the chart
editor. See the options table below.

Returns a ChartWrapper representing the chart, with user modifications.

setChartWrapper(chartWrapper)

null

Use this method to update the rendered chart on the editor.

chartWrapper - A ChartWrapper object representing the new chart to
render. The chart must either have a populated DataTable, or be connected to a
valid data source.

closeDialog()

null

Closes the chart editor dialog box.

Options

The chart editor supports the following options:

Name

Type

Default

Description

dataSourceInput

Element handle or 'urlbox'

null

Use this to enable the user to specify a data source for the chart. This property can be
one of two values:

'urlbox' -
Show the chart's data source URL on the dialog in an
editable textbox. The user can modify this, and the chart
will be redrawn, based on the new data source.

DOM element - Enables you to provide a custom HTML
element to use to select a data source. Pass in a handle to an HTML
element, either one created in code or copied from the page.
This element will be displayed on the dialog. Use this as a way to let the user
choose the chart's data source. For example, create a listbox containing several
data source URLs, or user-friendly names that the user can choose from.
The element must implement a selection handler and use it to change
the chart's data source: for example, either change the underlying DataTable,
or modify the chart's dataSourceUrl field.

Events

The chart editor throws the following events:

Name

Description

Properties

ok

Fired when the user clicks the "OK" button on the dialog. After receiving this
method, you should call getChartWrapper() to retrieve the user-configured chart.

none

cancel

Fired when the user clicks the "Cancel" button on the dialog.

none

Example

The following example code opens a chart editor dialog with a populated line chart. If the user
clicks "OK", the edited chart will be saved to the specified <div>
on the page.

group()

Takes a populated DataTable object and performs a SQL-like GROUP BY operation,
returning a table with rows grouped by the specified column values. Note that this does not modify
the input DataTable.

The returned table includes one row for each combination of values in the specified key columns.
Each row includes the key columns, plus one column with an aggregated column value over all rows
that match the key combination (for example, a sum or count of all values in the specified
column).

The google.visualization.data namespace includes several useful aggregation values
(for example, sum and
count), but you can define your own (for example,
standardDeviation or secondHighest). Instructions on how to define your own aggregator are given
after the method description.

Syntax

google.visualization.data.group(data_table, keys, columns)

data_table

The input DataTable. This will not be modified by calling group().

keys

An array of numbers and/or objects specifying which columns to group by. The result table
includes every column in this array, as well as every column in columns. If a number,
this is a column index of the input DataTable to group by. If an object, it will
include a function that can modify the specified column (for example, add 1 to the value in that
column). The object must have the following properties:

column - A number that is a column index from dt to apply the
transformation to.

modifier - A function that accepts one value (the cell value in that column
for each row), and returns the modified value. This function is used to modify the column
value to assist in the grouping: for example, by calling a whichQuarter function that
calculates a quarter from a date column, so the API can group rows by quarter. The
calculated value is displayed in the key columns in the returned table. This function can be
declared inline inside this object, or it can be a function that you define elsewhere in
your code (it must be within the calling scope). The API provides
one simple modifier function;
here are instructions on how to create your own,
more useful functions. You must know the data type that this function can accept, and call
it only on columns of that type. You must also know the return type of this function, and
declare it in the type property described next.

type - The type returned by the function modifier. This should be
a JavaScript string type name, for example: 'number' or 'boolean'.

label - [Optional] A string label to assign this column in the
returned DataTable.

id - [Optional] A string ID to assign this column in the returned
DataTable.

[Optional] Lets you specify which columns, in addition to key columns, to include in
the output table. Because all rows in the row group are compressed into a single output row,
you must determine what value to display for that row group. For example, you could choose to
show the column value from the first row in the set, or an average of all rows in that group.
columns is an array of objects, with the following properties:

column - A number specifying the index of the column to show.

aggregation - A function that accepts an array of all values of this column
in this row group and returns a single value to display in the result row. The return value
must be of the type specified by the object's type property. Details on
creating your own aggregation function are given below. You must know what data types this
method accepts and only call it on columns of the appropriate type. The API provides several
useful aggregation functions. See Provided Aggregation
Functions below for a list, or Creating an
aggregation function to learn how to write your own aggregation function.

type - The return type of the aggregation function. This should be a
JavaScript string type name, for example: 'number' or 'boolean'.

label - [Optional] A string label to apply to this column in the
returned table.

id - [Optional] A string ID to apply to this column in the
returned table.

Return Value

A DataTable with one column for each column listed in keys and one column
for each column listed in columns. The table is sorted by key rows, from left to right.

Provided Modifier Functions

The API provides the following modifier functions that you can pass into the keys.
modifier parameter to customize grouping behavior.

Function

Input Array Type

Return Type

Description

google.visualization.data.month

Date

number

Given a date, it will return the zero-based month value (0, 1, 2, and so on).

Provided Aggregation Functions

The API provides the following aggregation functions that you can pass into the columns.
aggregation parameter array.

Function

Input Array Type

Return Type

Description

google.visualization.data.avg

number, string, Date

number

The average value of the array passed in.

google.visualization.data.count

any type

number

The count of rows in the group. Null and duplicate values are counted.

google.visualization.data.max

number, string, Date

number, string, Date

The maximum value in the array. For strings, this is the first item in an lexicographically
sorted list; for Date values, it is the latest date. Nulls are ignored.

google.visualization.data.min

number, string, Date

number, string, Date

The minimum value in the array. For strings, this is the last item in an lexicographically
sorted list; for Date values, it is the earliest date. Nulls are ignored.

google.visualization.data.sum

number, string, Date

number

The sum of all values in the array.

Creating a modifier function

You can create a modifier function to perform a simple transformation onkey values before the
group() function groups your rows. This function takes a single cell value, performs
an action on it (for example, adds 1 to the value), and returns it. The input and return types
need not be the same type, but the caller must know the input and output types. Here's an example
of a function that accepts a date and returns the quarter:

Creating an aggregation function

You can create an aggregation function that accepts a set of column values in a row group and
returns a single number: for example, returning a count or average of values. Here is an
implementation of the provided count aggregation function, which returns a count of how many rows
are in the row group:

join()

This method joins two data tables (DataTable or DataView objects) into a
single results table, similar to a SQL JOIN statement. You specify one or more column pairs
(key columns) between the two tables, and the output table includes the rows according to
a join method that you specify: only rows where both keys match; all rows from one table; or all
rows from both tables, whether or not the keys match. The results table includes only the key
columns, plus any additional columns that you specify. Note that dt2 cannot have
duplicate keys, but dt1 can. The term "key" means the combination of all key
column values, not a specific key column value; so if a row has cell values A | B | C and columns
0 and 1 are key columns, then the key for that row is AB.

A populated DataTable to join with dt1. This table cannot have multiple
identical keys (where a key is a combination of key column values).

joinMethod

A string specifying the join type. If dt1 has multiple rows that match a dt2
row, the output table will include all matching dt1 rows. Choose from the following
values:

'full' - The output table includes all rows from both tables, regardless of whether keys
match. Unmatched rows will have null cell entries; matched rows are joined.

'inner' - The full join filtered to include only rows where the keys match.

'left' - The output table includes all rows from dt1, whether or not there are any
matching rows from dt2.

'right' - The output table includes all rows from dt2, whether or not there are any
matching rows from dt1.

keys

An array of key columns to compare from both tables. Each pair is a two element array, the first
is a key in dt1, the second is a key in dt2. Columns must be the same type in
both tables. All specified keys must match according to the rule given by joinMethod in
order to include a row from the table. Key columns are always included in the output table.
Only dt1, the left-hand table, can include duplicate keys; keys in dt2 must be
unique. The term "key" here means a unique set of key columns, not individual column
values. For example, if your key columns were A and B, the following table would have only
unique key values (and could thus be used as dt2):

A

B

Jen

Red

Jen

Blue

Fred

Red

Example:[[0,0], [2,1]] compares values from the first column in
both tables as well as the third column from dt1 with the second column from
dt2.

dt1Columns

An array of columns from dt1 to include in the output table, in addition to
dt1's key columns. This is an array of column indexes.

dt2Columns

An array of columns from dt2 to include in the output table, in addition to
dt2's key columns. This is an array of column indexes.

Return Value

A DataTable with the key columns, dt1Columns, and dt2Columns. This
table is sorted by the key columns, from left to right. When joinMethod is 'inner', all
key cells should be populated. For other join methods, if no matching key is found, the table will
have a null for any unmatched key cells.

Important: Formatters can only be used with a DataTable; they cannot
be used with a DataView (DataView objects are read-only).

Here are the general steps for using a formatter:

Get your populated DataTable object.

For each column that you want to reformat:

Create an object that specifies all the options for your formatter. This is a basic
JavaScript object with a set of properties and values. Look at your formatter's
documentation to see what properties are supported. (Optionally, you can pass in an object
literal notation object specifying your options.)

Create your formatter, passing in your options object.

Call formatter.format(table,
colIndex), passing in the DataTable and the (zero-based)
column number of the data to reformat. Note that you can only apply a single formatter to
each column; applying a second formatter will simply overwrite the effects of the first.
Important: Many formatters require HTML tags to display special
formatting; if your visualization supports an allowHtml option, you should set
it to true.

Here is an example of changing the formatted date values of a date column to use a long date
format ("January 1, 2009"):

options - A generic JavaScript object that specifies the options for that
formatter. This object is a generic object with property/value pairs with properties
specific to that formatter. See the documentationfor your specific formatter to learn
what options are supported. Here are two example ways to call the constructor for the
DateFormat object, passing in two properties:

Concatenates cell values on the same row into a specified cell,
along with arbitrary text.

ArrowFormat

Adds an up or down arrow to a numeric cell, depending on whether the
value is above or below a specified base value. If equal to the base
value, no arrow is shown.

Options

ArrowFormat supports the following options, passed in to the constructor:

Option

Description

base

A number indicating the base value, used to compare against the cell value. If the cell
value is higher, the cell will include a green up arrow; if the cell value is lower, it
will include a red down arrow; if the same, no arrow.

ColorFormat

Assigns colors to the foreground or background of a numeric cell,
depending on the cell value. This formatter is an unusual, in that
it doesn't take its options in the constructor. Instead, you should
call addRange() or addGradientRange() as
many times as you want, to add color ranges, before
calling format(). Colors can be specified in any
acceptable HTML format, for example "black",
"#000000", or "#000".

Methods

ColorFormat supports the following methods:

Method

Description

google.visualization.ColorFormat()

Constructor. Takes no arguments.

addRange(from, to, color, bgcolor)

Specifies a foreground color and/or background color to a cell, depending on the cell value.
Any cell with a value in the specified from—to range will be
assigned color and bgcolor. It is important to realize that the range is
non-inclusive, because creating a range from 1—1,000 and a second from 1,000—
2,000 will not cover the value 1,000!

from - [String, Number, Date, DateTime, or TimeOfDay] The lower boundary
(inclusive) of the range, or null. If null, it will match -∞. String boundaries are
compared alphabetically against string values.

to - [String, Number, Date, DateTime, or TimeOfDay] The high boundary
(non-inclusive) of the range, or null. If null, it will match +∞. String boundaries
are compared alphabetically against string values.

color - The color to apply to text in matching cells. Values can be either
'#RRGGBB' values or defined color constants, (example: '#FF0000' or 'red').

bgcolor - The color to apply to the background of matching cells. Values can be
either '#RRGGBB' values or defined color constants, (example: '#FF0000' or 'red').

addGradientRange(from, to, color,fromBgColor,
toBgColor)

Assigns a background color from a range, according to the cell value. The color is scaled to
match the cell's value within a range from a lower boundary color to an upper boundary
color. Note that this method cannot compare string values, as addRange() can.
Tip: Color ranges are often hard for viewers to gauge accurately; the simplest and
easiest to read range is from a fully saturated color to white (e.g., #FF0000—FFFFFF).

from - [Number, Date, DateTime, or TimeOfDay] The lower boundary
(inclusive) of the range, or null. If null, it will match -∞.

to - [Number, Date, DateTime, or TimeOfDay] The higher boundary
(non-inclusive) of the range, or null. If null, it will match +∞.

color - The color to apply to text in matching cells. This color is the same for
all cells, no matter what their value.

fromBgColor - The background color for cells holding values at the low end of the
gradient. Values can be either '#RRGGBB' values or defined color constants, (example:
'#FF0000' or 'red').

toBgColor - The background color for cells holding values at the high end of the
gradient. Values can be either '#RRGGBB' values or defined color constants, (example:
'#FF0000' or 'red').

format(dataTable, columnIndex)

The standard format() method to apply formatting to the specified column.

DateFormat

Formats a JavaScript Date value in a variety of ways, including "January 1,
2016," "1/1/16" and "Jan 1, 2016".

Options

DateFormat supports the following options, passed in to the constructor:

Option

Description

formatType

A quick formatting option for the date. The following string values are supported,
reformatting the date February 28, 2016 as shown:

'short' - Short format: e.g., "2/28/16"

'medium' - Medium format: e.g., "Feb 28, 2016"

'long' - Long format: e.g., "February 28, 2016"

You cannot specify both formatType and pattern.

pattern

A custom format pattern to apply to the value, similar to the
ICU date and time format.
For example: var formatter3 = new google.visualization.DateFormat({pattern: "EEE,
MMM d, ''yy"});

You cannot specify both formatType and pattern. You can read more
details about patterns in the next section.

timeZone

The time zone in which to display the date value. This is a numeric value, indicating GMT +
this number of time zones (can be negative). Date object are created by default with the
assumed time zone of the computer on which they are created; this option is used to display
that value in a different time zone. For example, if you created a Date object of 5pm noon on
a computer located in Greenwich, England, and specified timeZone to be -5
(options['timeZone'] = -5, or Eastern Pacific Time in the US), the value
displayed would be 12 noon.

Methods

DateFormat supports the following methods:

Method

Description

google.visualization.DateFormat(options)

Constructor. See the options section above for more info.

format(dataTable, columnIndex)

The standard format() method to apply formatting to the
specified column.

formatValue(value)

Returns the formatted value of a given value.
This method does not require a DataTable.

The patterns are similar to the ICU
date and time format, but the following patterns are not yet supported: A e D F g Y u w W. To
avoid collision with patterns, any literal text you want to appear in the output should be
surrounded by single quotes, except for the single quote, which should be doubled: e.g.,
"K 'o''clock.'".

Pattern

Description

Example Output

GG

Era designator.

"AD"

yy or yyyy

year.

1996

M

Month in year. For January:

M produces 1

MM produces 01

MMM produces Jan

MMMM produces January

"July"

"07"

d

Day in month. Extra 'd' values will add leading zeros.

10

h

Hour in 12 hour scale. Extra 'h' values will add leading zeros.

12

H

Hour in 24 hour scale. Extra Hk' values will add leading zeros.

0

m

Minute in hour. Extra 'M' values will add leading zeros.

30

s

Second in minute. Extra 's' values will add leading zeros.

55

S

Fractional second. Extra 'S' values will be padded on the right with zeros.

978

E

Day of week. Following outputs for "Tuesday":

E produces T

EE or EEE Produce Tu or Tues

EEEE Produces Tuesday

"Tues"

"Tuesday"

aa

AM/PM

"PM"

k

Hour in day (1~24). Extra 'k' values will add leading zeros.

24

K

Hour in AM/PM (0~11). Extra 'k' values will add leading zeros.

0

z

Time zone. For time zone 5, produces "UTC+5"

"UTC+5"

Z

Time zone in RFC 822 format. For time zone -5:

Z, ZZ, ZZZ produce -0500

ZZZZ and more produce "GMT -05:00"

"-0800"

"GMT -05:00"

v

Time zone (generic).

"Etc/GMT-5"

'

escape for text

'Date='

''

single quote

''yy

NumberFormat

Describes how numeric columns should be formatted. Formatting
options include specifying a prefix symbol (such as a dollar sign)
or the punctuation to use as a thousands marker.

Options

NumberFormat supports the following options, passed in to the constructor:

Option

Description

decimalSymbol

A character to use as the decimal marker. The default is a dot (.).

fractionDigits

A number specifying how many digits to display after the decimal. The default is 2. If you
specify more digits than the number contains, it will display zeros for the smaller values.
Truncated values will be rounded (5 rounded up).

groupingSymbol

A character to be used to group digits to the left of the decimal into sets of three. Default
is a comma (,).

negativeColor

The text color for negative values. No default value. Values can be any acceptable HTML color
value, such as "red" or "#FF0000".

negativeParens

A boolean, where true indicates that negative values should be surrounded by parentheses.
Default is true.

pattern

A format string. When provided, all other options are ignored, except
negativeColor.

The format string is a subset of the
ICU pattern set
.
For instance, {pattern:'#,###%'} will result in output values
"1,000%", "750%", and "50%" for values 10, 7.5, and 0.5.

prefix

A string prefix for the value, for example "$".

suffix

A string suffix for the value, for example "%".

Methods

NumberFormat supports the following methods:

Method

Description

google.visualization.NumberFormat(options)

Constructor. See the options section above for more info.

format(dataTable, columnIndex)

The standard format() method to apply formatting to the specified column.

formatValue(value)

Returns the formatted value of a given value. This method does not require a
DataTable.

PatternFormat

Enables you to merge the values of designated columns into a single
column, along with arbitrary text. So, for example, if you had a
column for first name and a column for last name, you could populate
a third column with {last name}, {first name}. This formatter does
not follow the conventions for the constructor and
the format() method. See the Methods section below for
instructions.

Methods

PatternFormat supports the following methods:

Method

Description

google.visualization.PatternFormat(pattern)

Constructor. Does not take an options object. Instead, it takes a string pattern
parameter. This is a string that describes which column values to put into the destination
column, along with any arbitrary text. Embed placeholders in your string to indicate a value
from another column to embed. The placeholders are {#}, where # is a the index
of a source column to use. The index is an index in the srcColumnIndices array from
the format() method below. To include a literal { or } character, escape it
like this: \{ or \}. To include a literal \ mark, escape it as \\.

Sample code

The following example demonstrates a constructor for a pattern
that creates an anchor element, with the first and second elements taken from the
format() method:

srcColumnIndices - An array of one or more (zero-based) column indices to pull
as the sources from the underlying DataTable. This will be used as a data source for the
pattern parameter in the constructor. The column numbers do not have to
be in sorted order.

opt_dstColumnIndex - [optional] The destination column to place the
output of the pattern manipulation. If not specified, the first element in
srcColumIndices will be used as the destination.

Constructor

Methods

Static. Create a new instance of google.visualization.Query and set its
properties according to values from the gadget preferences. The type of parameter
prefs is _IG_Prefs

Preference _table_query_url is used to set the Query data source URL.

Preference _table_query_refresh_interval is used to set the Query refresh
interval (in seconds).

validateResponse(response)

Boolean

Static. Parameter response is of type
google.visualization.QueryResponse. Returns true if
the response contains data. Returns false if the query execution failed and the
response does not contain data. If an error occurred, this method displays an error message.

Query Classes

The following objects are available to send queries for data to an external data source, such as
Google Spreadsheets.

'makeRequest' - [Available only for gadgets, which are
deprecated] Send the query using the Gadget API
makeRequest()
method. If specified, you should also specify makeRequestParams.

'auto' - Use the method specified by the tqrt URL
parameter from the data source URL. tqrt can have the following values:
'xhr', 'scriptInjection', or 'makeRequest'. If tqrt is missing or has an
invalid value, the default is 'xhr' for same-domain requests and 'scriptInjection' for
cross-domain requests.

makeRequestParams - [Object] A map of parameters for a
makeRequest() query. Used and required only if sendMethod is
'makeRequest'.

Methods

Method

Return Value

Description

abort()

None

Stops the automated query sending that was started with setRefreshInterval().

setRefreshInterval(seconds)

None

Sets the query to automatically call the send method every specified duration
(number of seconds), starting from the first explicit call to send.
seconds is a number greater than or equal to zero.

If you use this method, you should call it before calling the send method.

Cancel this method either by calling it again with zero (the default), or by calling
abort().

setTimeout(seconds)

None

Sets the number of seconds to wait for the data source to respond before raising a timeout
error. seconds is a number greater than zero.
The default timeout is 30 seconds. This method, if used, should be called before calling the
send method.

setQuery(string)

None

Sets the query string. The value of the string parameter should be a valid
query.
This method, if used, should be called before calling the send method.
Learn more about the Query language.

send(callback)

None

Sends the query to the data source. callback should be a function that will be
called when the data source responds. The callback function will receive a single parameter of
type google.visualization.QueryResponse.

QueryResponse

Represents a response of a query execution as received from the data source. An instance of this
class is passed as an argument to the callback function that was set when
Query.send was called.

Methods

Returns the data table as returned by the data source. Returns null if the query
execution failed and no data was returned.

getDetailedMessage()

String

Returns a detailed error message for queries that failed. If the query execution was
successful, this method returns an empty string. The message returned is a message that is
intended for developers, and may contain technical information, for example 'Column {salary}
does not exist'.

getMessage()

String

Returns a short error message for queries that failed. If the query execution was successful,
this method returns an empty string. The message returned is a short message that is intended
for end users, for example 'Invalid Query' or 'Access Denied'.

getReasons()

Array of strings

Returns an array of zero of more entries. Each entry is a short string with an error or
warning code that was raised while executing the query. Possible codes:

access_denied The user does not have permissions to access the data source.

invalid_query The specified query has a syntax error.

data_truncated One or more data rows that match the query selection were not
returned due to output size limits. (warning).

timeout The query did not respond within the expected time.

hasWarning()

Boolean

Returns true if the query execution has any warning messages.

isError()

Boolean

Returns true if the query execution failed, and the response does not contain
any data table. Returns <false> if the query execution was successful and the response
contains a data table.

Error Display

The API provides several functions to help you display custom error messages to your users. To
use these functions, provide a container element on the page (typically a
<div>), into which the API will draw a formatted error message. This container
can be either the visualization container element, or a container just for errors. If you specify
the visualization containe element, the error message will be displayed above the visualization.
Then call the appropriate function below to show, or remove, the error message.

All functions are static functions in the namespace google.visualization.errors.

Many visualizations can throw an error event; see error event below to learn more about that.

String ID value that identifies the error object created. This is a unique value on the page,
and can be used to remove the error or find its containing element.

Adds an error display block to the specified page element, with specified text and
formatting.

container - The DOM element into which to insert the error message. If the
container cannot be found, the function will throw a JavaScript error.

message - A string message to display.

opt_detailedMessage - An optional detailed message string. By default, this is
mouseover text, but that can be changed in the opt_options.showInToolTip property
described below.

opt_options - An optional object with properties that set various display options
for the message. The following options are supported:

showInTooltip - A boolean value where true shows the detailed message
only as tooltip text, and false shows the detailed message in the container body after
the short message. Default value is true.

type - A string describing the error type, which determines which css
styles should be applied to this message. The supported values are 'error' and
'warning'. Default value is 'error'.

style - A style string for the error message. This style will
override any styles applied to the warning type (opt_options.type). Example:
'background-color: #33ff99; padding: 2px;' Default value is an empty
string.

removable - A boolean value, where true means that the message can be
closed by a mouse click from the user. Default value is false.

addErrorFromQueryResponse(container, response)

String ID value that identifies the error object created, or null if the response didn't
indicate an error. This is a unique value on the page, and can be used to remove the error
or find its containing element.

Pass a query response and error message container to this method: if the query response
indicates a query error, displays an error message in the specified page element. If the
query response is null, the method will throw a JavaScript error. Pass your
QueryResponse received in your query handler to this message to
display an error. It will also set the style of the display appropriate to the type (error
or warning, similar to addError(opt_options.type))

container - The DOM element into which to insert the error message. If the
container cannot be found, the function will throw a JavaScript error.

response - A QueryResponse object received by your
query handler in response to a query. If this is null, the method
will throw a JavaScript error.

removeError(id)

Boolean: true if the error was removed; false otherwise.

Removes the error specified by ID from the page.

id - The string ID of an error created using addError() or
addErrorFromQueryResponse().

removeAll(container)

None

Removes all error blocks from a specified container. If the specified container does not
exist, this will throw an error.

container - The DOM element holding the error strings to remove. If the container
cannot be found, the function will throw a JavaScript error.

getContainer(errorId)

Handle to a DOM element holding the error specified, or null if it could not be found.

Retrieves a handle to the container element holding the error specified by errorID.

errorId - String ID of an error created using addError() or
addErrorFromQueryResponse().

Events

Most visualizations fire events to indicate something has occurred. As a user of the chart, you
would often want to listen to these events. If you
code your own visualization, you might also want
to trigger such events on your own.

The following methods enable developers to listen to events, remove existing event handlers or
trigger events from inside a visualization.

A handle to the source visualization instance. If you are calling this function from within a
method defined by the sending visualization, you can simply pass in the this
keyword.

event_name

A string name to call the event. You can choose any string value that you want.

event_args

[optional] A map of name/value pairs to pass to the receiving method. For example:
{message: "Hello there!", score: 10, name: "Fred"}. You can pass null if no
events are needed; the receiver should be prepared to accept null for this parameter.

Example

Here is an example of a visualization that throws a method named "select" when its
onclick method is called. It does not pass back any values.

Standard Visualization Methods and Properties

Every visualization should expose the following set of required and optional methods and
properties. However, note that there is no type checking to enforce these standards, so you should
read the documentation for each visualization.

draw()

Draws the visualization on the page. Behind the scenes this can be fetching a graphic from a
server or creating the graphic on the page using the linked visualization code. You should call
this method every time the data or options change. The object should be drawn inside the DOM
element passed into the constructor.

draw(data[, options])

data

A DataTable or
DataView holding the data to use to draw the chart. There
is no standard method for extracting a DataTable from a chart.

options

[Optional] A map of name/value pairs of custom options. Examples include height and
width, background colors, and captions. The visualization documentation should list which
options are available, and should support default options if you do not specify this parameter.
You can use the JavaScript object literal syntax to pass in an options map: e.g.,
{x:100, y:200, title:'An Example'}

getAction()

// Returns the action object with the ID 'alertAction'.
chart.getAction('alertAction');

getSelection()

This is optionally exposed by visualizations that want to let you access the currently selected
data in the graphic.

selection_array getSelection()

Returns

selection_array An array of selected objects, each one describing a data
element in the underlying table used to create the visualization (a DataView or
a DataTable). Each object has properties row and/or column,
with the index of the row and/or column of the selected item in the underlying
DataTable. If the row property is null, then the selection is a column;
if the column property is null, then the selection is a row; if both are non-null,
then it is a specific data item. You can call the
DataTable.getValue() method to get the value of the
selected item. The retrieved array can be passed into
setSelection().

removeAction()

Removes the tooltip action object with the requested actionID from your chart.

Example:

// Removes an action from chart with the ID of 'alertAction'.
chart.removeAction('alertAction');

setAction()

This is optionally exposed by visualizations that have
tooltips and allow
tooltip actions. It works only for core charts (bar, column, line, area, scatter, combo, bubble, pie, donut, candlestick, histogram, stepped area).

Sets a tooltip action to be executed when the user clicks on the action text.

setAction(action object)

The setAction method takes an object as its action parameter. This object should
specify 3 properties: id— the ID of the action being set, text
—the text that should appear in the tooltip for the action, and action
— the function that should be run when a user clicks on the action text.

Any and all tooltip actions should be set prior to calling the chart's draw()
method.

The setAction method can also define two additional properties: visible
and enabled. These properties should be functions that return boolean
values indicating if the tooltip action will be visible and/or enabled.

setSelection()

Optionally selects a data entry in the visualization—for example, a point in an area chart, or a bar
in a bar chart. When this method is called, the visualization should visually indicate what the
new selection is. The implementation of setSelection()should not fire a
"select" event. Visualizations may ignore part of the selection. For example, a table
that can show only selected rows may ignore cell or column elements in its
setSelection() implementation, or it can select the entire row.

Every time this method is called, all selected items are deselected, and the new selection list
passed in should be applied. There is no explicit way to deselect individual items; to deselect
individual items, call setSelection() with the items to remain selected; to
deselect all elements, call setSelection(), setSelection(null),
or setSelection([]).

setSelection(selection_array)

selection_array

An array of objects, each with a numeric row and/or column property. row and
column are the zero-based row or column number of an item in the data table to
select. To select a whole column, set row to null; to select a whole row, set
column to null. Example:setSelection([{row:0,column:1},{row:1, column:null}]) selects the cell at (0,1)
and the entire row 1.

Assorted Static Methods

This section contains various useful methods exposed in the google.visualization
namespace.

arrayToDataTable()

This method takes in a two-dimensional array and converts it to a DataTable.

The column data types are determined automatically by the data provided. Column data types can
also be specified using the object literal notation in the first row (the column header row) of
the array (i.e. {label: 'Start Date', type: 'date'}).
Optional data roles may be used as well, but they
must be defined explicitly using object literal notation. Object literal notation may also be
used for any cell, allowing you to define Cell Objects).

Syntax

google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)

twoDArray

A two-dimensional array, where each row represents a row in the data table. If
opt_firstRowIsData is false (the default), the first row will be interpreted as
header labels. The data types of each column are interpreted automatically from the data given.
If a cell has no value, specify a null or empty value as appropriate.

opt_firstRowIsData

Whether the first row defines a header row or not. If true, all rows are assumed to be data. If
false, the first row is assumed to be a header row, and the values are assigned as column
labels. Default is false.

Returns

A new DataTable.

Examples

The following code demonstrates three ways to create the same DataTable object:

drawChart()

This method creates a chart in a single call. The advantage of using this method is that it
requires slightly less code, and you can serialize and save visualizations as text strings for
reuse. This method does not return a handle to the created chart, so you cannot assign method
listeners to catch chart events.

Syntax

google.visualization.drawChart(chart_JSON_or_object)

chart_JSON_or_object

Either a JSON literal string or a JavaScript object, with
the following properties (case-sensitive):

Property

Type

Required

Default

Description

chartType

String

Required

none

The class name of the visualization. The google.visualization package name can
be omitted for Google charts. If the appropriate visualization library has not already been
loaded, this method will load the library for you if this is a Google visualization; you must
load third party visualizations explicitly. Examples:Table,
PieChart, example.com.CrazyChart.

containerId

String

Required

none

The ID of the DOM element on your page that will host the visualization.

options

Object

Optional

none

An object describing the options for the visualization. You can use either JavaScript literal
notation, or provide a handle to the object. Example:"options": {"width": 400, "height": 240,
"is3D": true, "title": "Company Performance"}

dataTable

Object

Optional

None

A DataTable used to populate the visualization. This can be a literal JSON string
representation of a DataTable, as described above, or a handle to a
populated google.visualization.DataTable object, or a 2-dimensional array like
that accepted by
arrayToDataTable(opt_firstRowIsData=false)
.
You must specify either this property or the dataSourceUrl property.

dataSourceUrl

String

Optional

None

A data source query to populate the chart data (for example, a
Google Spreadsheet). You must specify
either this property or the dataTable property.

query

String

Optional

None

If specifying dataSourceUrl, you can optionally specify a SQL-like query string
using the Visualization query language
to filter or manipulate the data.

refreshInterval

Number

Optional

None

How often, in seconds, the visualization should refresh its query source. Use this only when
specifying dataSourceUrl.

view

Object OR Array

Optional

None

Sets a DataView initializer object, which acts as a filter over the underlying
data, as defined by either the dataTable or dataSourceUrl parameter.
You can pass in either a string or DataView initializer object, like that
returned by dataview.toJSON().
Example:"view": {"columns": [1, 2]} You
can also pass in an array of DataView initializer objects, in which case the
first DataView in the array is applied to the underlying data to create a new
data table, and the second DataView is applied to the data table resulting from
application of the first DataView, and so on.

Examples

Creates a table chart based on a spreadsheet data source, and includes the query SELECT A,D WHERE
D > 100 ORDER BY D

drawToolbar()

This is the constructor for the toolbar element that can be attached to many visualizations. This
toolbar enables the user to export the visualization data into different formats, or to provide
an embeddable version of the visualization for use in different places. See the
toolbar page for more information and a
code example.