Consultas de dados

Nesta página, descrevemos como enviar uma consulta para uma fonte de dados compatível com o protocolo da fonte de dados das ferramentas de gráficos.

Conteúdo

  1. Visão geral
  2. Como enviar uma solicitação
  3. Como processar a resposta
  4. Como ler arquivos CSV
  5. Saiba mais.

Visão geral

A fonte de dados é um serviço da Web com suporte para o protocolo da fonte de dados das ferramentas de gráfico. É possível enviar uma consulta SQL a uma fonte de dados e, em resposta, você receberá uma DataTable preenchida com as informações apropriadas. Alguns exemplos de fontes de dados incluem Planilhas do Google e SalesForce.

Como enviar uma solicitação

Para enviar uma solicitação:

  1. Instancie um objeto Query com o URL da sua fonte de dados. O URL precisa indicar quais dados estão sendo solicitados, em uma sintaxe compreendida pela fonte de dados.
  2. Também é possível especificar opções de solicitação, como o método de envio como um segundo parâmetro opcional no construtor do objeto Query. Consulte o parâmetro opt_options do construtor de consulta para mais detalhes:
  3. Se quiser, adicione uma string de idioma da consulta para classificar ou filtrar os resultados e enviar a solicitação. As fontes de dados não precisam aceitar a linguagem de consulta delas. Se a fonte de dados não for compatível com a linguagem de consulta, ela ignorará a string de consulta SQL, mas ainda retornará um DataTable. A linguagem de consulta é uma variante da linguagem SQL. Leia a sintaxe completa da linguagem de consulta aqui.
  4. Envie a consulta especificando um gerenciador de callback que será chamado quando a resposta for recebida. Consulte a próxima seção para mais detalhes.

Este é um exemplo de envio de uma solicitação de dados em um intervalo de células das Planilhas Google. Para saber como conseguir o URL de uma planilha do Google, consulte aqui: 

function initialize() {
  var opts = {sendMethod: 'auto'};
  // 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&...', opts);

  // 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.
  ...
}

Se você estiver enviando sua consulta pelo Apps Script, use o modo IFRAME.

Como processar a resposta

Sua função de gerenciador de respostas será chamada quando a solicitação retornar. O parâmetro transmitido para a função do gerenciador de respostas é do tipo google.visualization.QueryResponse. Se a solicitação for bem-sucedida, a resposta conterá uma tabela de dados (classe google.visualization.DataTable). Se a solicitação falhar, a resposta conterá informações sobre o erro e não DataTable.

Seu gerenciador de respostas precisa fazer o seguinte:

  1. Verifique se a solicitação foi bem-sucedida ou falhou chamando response.isError(). Não é necessário mostrar mensagens de erro para o usuário. A biblioteca de visualização exibe uma mensagem de erro para você no contêiner <div>. No entanto, se você quiser processar erros manualmente, use a classe goog.visualization.errors para exibir mensagens personalizadas. Consulte o Exemplo de wrapper de consulta para conferir um exemplo de tratamento de erros personalizado.
  2. Se a solicitação for bem-sucedida, a resposta incluirá um DataTable, que pode ser recuperado chamando getDataTable(). Transmita-o para seu gráfico.

O código a seguir demonstra o processamento da solicitação anterior para desenhar um gráfico de pizza:

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});
}

Como ler arquivos CSV

Há duas opções para criar um gráfico a partir de dados CSV (valores separados por vírgula). Converta manualmente os dados CSV para o formato de tabela de dados do Google Charts ou coloque o arquivo CSV no servidor da Web que veicula o gráfico e o consulte usando a técnica nesta página.

Mais informações