Data Queries

This page describes how to send a query to a data source that supports the Visualization API.

All visualizations require data. There are two common ways to get data for your visualization:

• Send a request to a data source that supports the Visualization API (such as a Google Spreadsheet). This is described on this page.
• Create and populate it using JavaScript code in your page. This is described on the Using Visualizations page.

Contents

Sending a Request

To send a request, create a Query object, specify a URL for the data source (this URL should indicate what data is being requested, in a syntax understood by that data source), optionally add a query language string to sort or filter the results, and then send the request. (Note: if the data source does not support the query language, it will return a DataTable, but will ignore your query string specifications, such as filtering or sorting). Here's an example of sending a request for data in a section of a Google Spreadsheet (for instructions on how to get the URL for a range of cells in a spreadsheet, see here):

function initialize() {
  // Replace the data source URL on next line with your data source URL.
  var query = new google.visualization.Query('http://spreadsheets.google.com?key=123AB&...');
  
  // Optional request to return only column C and the sum of column B, grouped by C members.
  query.setQuery('select C, sum(B) group by C');
  
  // Send the query with a callback function.
  query.send(handleQueryResponse);
}

function handleQueryResponse(response) {
  // Called when the query response is returned.
  ...
}

See More Information below for references on the query language.

If you are making a request to a restricted data source, you must be in the same domain as the data source; for example, if the restricted data source URL is http://www.example.com/secretinfo, you'll have to call from somewhere inside http://www.example.com.

If you are making a request to an unrestricted data source, you can specify some additional request options (such as sending method). Options are added as an optional second parameter in the Query object constructor (see the Query constructor's opt_options parameter for details):

function initialize() {
  // Specify that we want to use the XmlHttpRequest object to make the query.
  var opts = {sendMethod: 'xhr'};
  var query = new google.visualization.Query('http://spreadsheets.google.com?key=123AB&...', opts);
  
  ...

}

Processing the Response

Your response handler function will be called when the request returns. The parameter passed in to your response handler function is of type google.visualization.QueryResponse. If the request was successful, the response contains a data table (class google.visualization.DataTable). If the request failed, the response contains information about the error, and no DataTable.

Your response handler should do the following:

1. Check whether the request succeeded or failed by calling response.isError(). You shouldn't need to display any error messages to the user; the Visualization library will display an error message for you in your container <div>. However, if you do want to handle errors manually, you can use the goog.visualization.errors class to display custom messages (see the Query Wrapper Example for an example of custom error handling).
2. If the request succeeded, pass the returned DataTable to your visualization.

function handleQueryResponse(response) {

  if (response.isError()) {
    alert('Error in query: ' + response.getMessage() + ' ' + response.getDetailedMessage());
    return;
  }

  var data = response.getDataTable();
  var chart = new google.visualization.PieChart(document.getElementById('chart_div'));
  chart.draw(data, {width: 400, height: 240, is3D: true});
}

Get started quickly with an Interactive Code Sample you can edit and save.

More Information

• Query Language Syntax - Describes the syntax of the language used to make data queries.
• Query Class - Reference page for the class that wraps a query.
• QueryResponse Class - Reference page for the class that wraps the response to a query.