DataTables e DataViews

Esta página discute a representação de dados interna usada pelos gráficos, as classes DataTable e DataView usadas para transmitir dados para um gráfico e as várias maneiras de instanciar e preencher um DataTable.

Conteúdo

  1. Como os dados são representados em um gráfico
  2. Qual esquema de tabela meu gráfico usa?
  3. DataTables e DataViews
  4. Como criar e preencher uma tabela de dados
    1. Criar uma nova DataTable e chamar addColumn()/addRows()/addRow()/setCell()
    2. arrayToDataTable()
    3. Iniciador de literal do JavaScript
    4. Como enviar uma consulta à fonte de dados
  5. dataTableToCsv() (link em inglês)
  6. Mais informações

Como os dados são representados em um gráfico

Todos os gráficos armazenam os dados em uma tabela. Aqui está uma representação simplificada de uma tabela de dados de duas colunas preenchida:

índice: 0
tipo: string
rótulo: 'Tarefa'

 índice: 1
tipo: número
rótulo: 'Horas por dia'
"Trabalho" 11
"Comer" 2
"Deslocamento diário" 2
"Assistir TV" 2
"Sono" 7

Os dados são armazenados em células referenciadas como (row, column), em que row é um índice de linha baseado em zero e column é um índice de colunas baseado em zero ou um ID exclusivo que pode ser especificado.

Veja uma lista mais completa dos elementos e propriedades compatíveis da tabela. Consulte o Formato do parâmetro de literal JavaScript do construtor para mais detalhes:

  • Tabela: uma matriz de colunas e linhas, além de um mapa opcional de pares arbitrários de nome/valor que você pode atribuir. No momento, as propriedades no nível da tabela não são usadas pelos gráficos.
  • Colunas: cada coluna oferece suporte a um tipo de dados obrigatório, mais um rótulo de string, ID, padrão e mapa de propriedades de nome/valor arbitrárias. O rótulo é uma string fácil de usar que pode ser exibida pelo gráfico. O ID é um identificador opcional que pode ser usado no lugar de um índice de colunas. Uma coluna pode ser citada no código pelo índice baseado em zero ou pelo ID opcional. Consulte DataTable.addColumn() para ver uma lista dos tipos de dados compatíveis.
  • Linhas: uma linha é uma matriz de células e um mapa opcional de pares arbitrários de nome/valor que você pode atribuir.
  • Células: cada célula é um objeto que contém um valor real do tipo de coluna, além de uma versão opcional formatada em string do valor fornecido. Por exemplo: uma coluna numérica pode receber o valor 7 e o valor formatado "seven". Se um valor formatado for fornecido, um gráfico vai usar o valor real para cálculos e renderização, mas poderá mostrar o valor formatado quando apropriado, por exemplo, se o usuário passar o cursor sobre um ponto. Cada célula também tem um mapa opcional de pares arbitrários de nome/valor.

Qual esquema de tabela meu gráfico usa?

Gráficos diferentes usam tabelas em formatos diferentes: por exemplo, um gráfico de pizza espera uma tabela de duas colunas com uma coluna de string e uma coluna numérica, em que cada linha descreve uma fatia, e a primeira coluna é o rótulo da fatia e a segunda coluna é o valor da fatia. Já um gráfico de dispersão espera uma tabela composta de duas colunas numéricas, em que cada linha é um ponto e as duas colunas são os valores X e Y do ponto. Leia a documentação do gráfico para saber qual é o formato de dados necessário.

DataTables e DataViews

Uma tabela de dados do gráfico é representada em JavaScript por um objeto DataTable ou DataView. Em alguns casos, é possível usar um literal JavaScript ou uma versão JSON de um DataTable. Por exemplo, quando os dados são enviados pela Internet por uma fonte de dados de ferramentas de gráficos, ou como um possível valor de entrada para uma ChartWrapper.

Um DataTable é usado para criar a tabela de dados original. Uma DataView é uma classe de conveniência que fornece uma visualização somente leitura de um DataTable, com métodos para ocultar ou reordenar linhas ou colunas rapidamente sem modificar os dados originais vinculados. Confira uma breve comparação entre as duas classes:

DataTable DataView
Leitura/gravação Somente leitura
Pode ser criado em branco e preenchido É uma referência a um DataTable existente. Não pode ser preenchido do zero. Precisa ser instanciado com uma referência a um DataTable já existente.
Os dados ocupam espaço de armazenamento. Os dados são uma referência a um DataTable existente e não consomem espaço.
Pode adicionar/editar/excluir linhas, colunas e dados, e todas as alterações são persistentes. Pode classificar ou filtrar linhas sem modificar os dados subjacentes. Linhas e colunas podem ser ocultadas e reveladas repetidamente.
Podem ser clonadas Pode retornar uma versão DataTable da visualização
São dados de origem, mas não contêm referências Uma referência em tempo real a um DataTable. Qualquer mudança nos dados do DataTable é imediatamente refletida na visualização.
Pode ser transmitido para um gráfico como uma fonte de dados Pode ser transmitido para um gráfico como uma fonte de dados
Não é compatível com colunas calculadas Oferece suporte a colunas calculadas, que são colunas com um valor calculado instantaneamente, combinando ou manipulando outras colunas.
Nenhuma linha ou coluna oculta Pode ocultar ou mostrar as colunas selecionadas

Como criar e preencher uma tabela de dados

Há várias maneiras diferentes de criar e preencher uma tabela de dados:

DataTable vazia + addColumn()/addRows()/addRow()/setCell()

Etapas:

  1. Instancie um novo DataTable.
  2. Adicionar colunas
  3. Adicione uma ou mais linhas, opcionalmente preenchidas com dados. É possível adicionar linhas vazias e preenchê-las mais tarde. Você também pode adicionar ou remover linhas, linhas extras ou editar os valores das células individualmente.

Vantagens:

  • É possível especificar o tipo de dados e o rótulo de cada coluna.
  • Ideal para gerar a tabela no navegador e menos propenso a erros de digitação do que o método JSON literal.

Desvantagens:

  • Não é tão útil quanto criar uma string literal JSON para transmitir a um construtor do DataTable ao gerar a página de maneira programática em um servidor da Web.
  • Depende da velocidade do navegador e pode ser mais lenta do que strings literais JSON com tabelas maiores (cerca de 1.000 células ou mais).

Exemplos:

Aqui estão alguns exemplos de como criar a mesma tabela de dados usando diferentes variações dessa técnica:

// ------- Version 1------------
// Add rows + data at the same time
// -----------------------------
var data = new google.visualization.DataTable();

// Declare columns
data.addColumn('string', 'Employee Name');
data.addColumn('datetime', 'Hire Date');

// Add data.
data.addRows([
  ['Mike', {v:new Date(2008,1,28), f:'February 28, 2008'}], // Example of specifying actual and formatted values.
  ['Bob', new Date(2007,5,1)],                              // More typically this would be done using a
  ['Alice', new Date(2006,7,16)],                           // formatter.
  ['Frank', new Date(2007,11,28)],
  ['Floyd', new Date(2005,3,13)],
  ['Fritz', new Date(2011,6,1)]
]);



// ------- Version 2------------
// Add empty rows, then populate
// -----------------------------
var data = new google.visualization.DataTable();
  // Add columns
  data.addColumn('string', 'Employee Name');
  data.addColumn('date', 'Start Date');

  // Add empty rows
  data.addRows(6);
  data.setCell(0, 0, 'Mike');
  data.setCell(0, 1, {v:new Date(2008,1,28), f:'February 28, 2008'});
  data.setCell(1, 0, 'Bob');
  data.setCell(1, 1, new Date(2007, 5, 1));
  data.setCell(2, 0, 'Alice');
  data.setCell(2, 1, new Date(2006, 7, 16));
  data.setCell(3, 0, 'Frank');
  data.setCell(3, 1, new Date(2007, 11, 28));
  data.setCell(4, 0, 'Floyd');
  data.setCell(4, 1, new Date(2005, 3, 13));
  data.setCell(5, 0, 'Fritz');
  data.setCell(5, 1, new Date(2007, 9, 2));

arrayToDataTable()

Essa função auxiliar cria e preenche um DataTable usando uma única chamada.

Vantagens:

  • Código muito simples e legível executado no navegador.
  • Você pode especificar explicitamente o tipo de dados de cada coluna ou deixar que os Gráficos do Google deduzam o tipo a partir dos dados transmitidos.
    • Para especificar explicitamente o tipo de dados de uma coluna, especifique um objeto na linha do cabeçalho com a propriedade type.
    • Para permitir que o Gráficos Google deduza o tipo, use uma string para o marcador da coluna.

Exemplos:

var data = google.visualization.arrayToDataTable([
       ['Employee Name', 'Salary'],
       ['Mike', {v:22500, f:'22,500'}], // Format as "22,500".
       ['Bob', 35000],
       ['Alice', 44000],
       ['Frank', 27000],
       ['Floyd', 92000],
       ['Fritz', 18500]
      ],
      false); // 'false' means that the first row contains labels, not data.


var data = google.visualization.arrayToDataTable([
       [ {label: 'Year', id: 'year'},
         {label: 'Sales', id: 'Sales', type: 'number'}, // Use object notation to explicitly specify the data type.
         {label: 'Expenses', id: 'Expenses', type: 'number'} ],
       ['2014', 1000, 400],
       ['2015', 1170, 460],
       ['2016', 660, 1120],
       ['2017', 1030, 540]]);

Iniciador de literal JavaScript

Você pode passar um objeto literal JavaScript para o construtor da tabela, definindo o esquema da tabela e, opcionalmente, os dados.

Vantagens:

  • Útil para gerar dados no seu servidor da Web.
  • Processa mais rapidamente do que outros métodos para tabelas maiores (cerca de 1.000 células ou mais)

Desvantagens:

  • A sintaxe é complicada de acertar e propensa a erros de digitação.
  • Código pouco legível.
  • Interessantemente semelhante, mas não idêntico, ao JSON.

Exemplo:

var data = new google.visualization.DataTable(
   {
     cols: [{id: 'task', label: 'Employee Name', type: 'string'},
            {id: 'startDate', label: 'Start Date', type: 'date'}],
     rows: [{c:[{v: 'Mike'}, {v: new Date(2008, 1, 28), f:'February 28, 2008'}]},
            {c:[{v: 'Bob'}, {v: new Date(2007, 5, 1)}]},
            {c:[{v: 'Alice'}, {v: new Date(2006, 7, 16)}]},
            {c:[{v: 'Frank'}, {v: new Date(2007, 11, 28)}]},
            {c:[{v: 'Floyd'}, {v: new Date(2005, 3, 13)}]},
            {c:[{v: 'Fritz'}, {v: new Date(2011, 6, 1)}]}
           ]
   }
)

Como enviar uma consulta à fonte de dados

Quando você envia uma consulta a uma fonte de dados das Ferramentas de gráfico, uma resposta bem-sucedida é uma instância do DataTable. Esse DataTable retornado pode ser copiado, modificado ou copiado para um DataView da mesma forma que qualquer outro DataTable.

function drawVisualization() {
    var query = new google.visualization.Query(
        'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');

    // Apply query language statement.
    query.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
    
    // Send the query with a callback function.
    query.send(handleQueryResponse);
  }

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

    var data = response.getDataTable();
    visualization = new google.visualization.LineChart(document.getElementById('visualization'));
    visualization.draw(data, {legend: 'bottom'});
  }

dataTableToCsv()

A função auxiliar google.visualization.dataTableToCsv(data) retorna uma string CSV com os dados da tabela de dados.

A entrada para essa função pode ser uma DataTable ou uma DataView.

Ela usa os valores formatados das células. Os marcadores de coluna são ignorados.

Caracteres especiais como "," e "\n" são usados para evitar escape com as regras padrão de escape de CSV.

O código a seguir vai exibir

Ramanujan,1729
Gauss,5050

no Console JavaScript do navegador:

<html>
  <head>
  <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
  <script type="text/javascript">
   google.charts.load("current", {packages:['corechart']});
   google.charts.setOnLoadCallback(drawChart);
   function drawChart() {
      var data = google.visualization.arrayToDataTable([
        ['Name', 'Number'],
        ['Ramanujan', 1729],
        ['Gauss', 5050]
      ]);
    var csv = google.visualization.dataTableToCsv(data);
    console.log(csv);
  }
  </script>
  </head>
</html>

Mais informações