DataTables e DataViews

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

Índice

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

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

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

index: 0
tipo: string
label: 'Task'

 índice: 1
tipo: número
label: "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 com base em zero e column é um índice de coluna com base em zero ou um ID exclusivo que pode ser especificado.

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

  • Tabela: uma matriz de colunas e linhas, além de um mapa opcional de pares de nome/valor arbitrários que você pode atribuir. No momento, as propriedades no nível da tabela não são usadas por gráficos.
  • Colunas: cada coluna aceita um tipo de dados obrigatório, além de uma string opcional de rótulo, ID, padrão e mapa das propriedades arbitrárias de nome/valor. O identificador é 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 referida no código por índice baseado em zero ou pelo ID opcional. Consulte o DataTable.addColumn() para ver uma lista de tipos de dados compatíveis.
  • Linhas: uma linha é uma matriz de células, além de um mapa opcional de pares de nome/valor arbitrários 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 que você fornece. Por exemplo, uma coluna numérica pode ter o valor 7 e o valor formatado "seven". Se um valor formatado for fornecido, um gráfico 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 de nome/valor arbitrários.

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 de número, em que cada linha descreve uma fatia. A primeira coluna é o rótulo da fatia, e a segunda é o valor da fração. No entanto, um gráfico de dispersão espera uma tabela que consiste em 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 formato de dado é necessário.

DataTables e DataViews

Uma tabela de dados do gráfico é representada em JavaScript por um objeto DataTable ou DataView. Em alguns casos, você pode ver um literal de JavaScript ou uma versão JSON de uma tabela de dados usada, por exemplo, quando os dados são enviados pela Internet por uma fonte de dados de ferramentas de gráfico ou como um possível valor de entrada para um 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 uma DataTable, com métodos para ocultar ou reordenar linhas ou colunas rapidamente sem modificar os dados originais vinculados. Veja uma breve comparação entre as duas classes:

Tabela de dados Visualização de dados
Leitura/gravação Somente leitura
Pode ser criado e depois preenchido É uma referência a uma DataTable existente. Não pode ser preenchido do zero. Precisa ser instanciado com uma referência a um DataTable existente.
Os dados ocupam espaço de armazenamento. Os dados são referências 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 permanentes. Pode classificar ou filtrar linhas sem modificar os dados. As linhas e colunas podem ser ocultadas e reveladas repetidamente.
Podem ser clonados Pode retornar uma versão DataTable da visualização.
É dados de origem; não contém referências Uma referência em tempo real para uma DataTable. Qualquer mudança nos dados de DataTable é refletida imediatamente na visualização.
Podem ser transmitidos para um gráfico como uma fonte de dados Podem ser transmitidos para um gráfico como uma fonte de dados
Não oferece suporte a colunas calculadas Oferece suporte a colunas calculadas, que são colunas com um valor calculado em tempo real combinando ou manipulando outras colunas.
Nenhuma linha ou coluna oculta Pode ocultar ou mostrar colunas selecionadas

Como criar e preencher uma tabela de dados

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

Tabela de dados 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. Também é possível adicionar ou remover linhas ou editar valores de células individualmente.

Vantagens:

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

Desvantagens:

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

Exemplos:

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

matrizParaDadosTabela()

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

Vantagens:

  • Código muito simples e legível executado no navegador.
  • É possível especificar explicitamente o tipo de dados de cada coluna ou permitir que os gráficos do Google inferiram o tipo 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 os gráficos do Google deduzam o tipo, use uma string para o rótulo 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]]);

Inicializador do JavaScript Lite

É possível transmitir um objeto literal de JavaScript para seu construtor de tabela, definindo o esquema da tabela e, opcionalmente, dados.

Vantagens:

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

Desvantagens:

  • A sintaxe é difícil de acertar e está sujeita a erros de digitação.
  • O código não está legível.
  • JSON extremamente semelhante, mas não idêntico.

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

Enviar uma consulta da fonte de dados

Quando você envia uma consulta para uma fonte de dados do Chart Tools, a resposta correta é uma instância do DataTable. Essa DataTable retornada pode ser copiada, modificada ou copiada para um DataView da mesma forma que qualquer outra 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 um DataTable ou um DataView.

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

Caracteres especiais como "," e "\n" têm escape usando regras padrão de escape de CSV.

O código a seguir 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