Class DataSourceTable

DataSourceTable

Acessar e modificar a tabela da fonte de dados. Para criar uma tabela de fonte de dados em uma nova página, use Spreadsheet.insertSheetWithDataSourceTable(spec).

Use essa classe apenas com fontes de dados do BigQuery.

Este exemplo mostra como criar uma tabela de fonte de dados. 

SpreadsheetApp.enableBigQueryExecution();
const spreadsheet = SpreadsheetApp.getActive();
const spec = SpreadsheetApp.newDataSourceSpec()
                 .asBigQuery()
                 .setProjectId('big_query_project')
                 .setRawQuery('select @FIELD from table limit @LIMIT')
                 .setParameterFromCell('FIELD', 'Sheet1!A1')
                 .setParameterFromCell('LIMIT', 'namedRangeCell')
                 .build();
// Starts data execution asynchronously.
const dataSheet = spreadsheet.insertSheetWithDataSourceTable(spec);
const dataSourceTable = dataSheet.getDataSourceTables()[0];
// waitForCompletion() blocks script execution until data execution completes.
dataSourceTable.waitForCompletion(60);
// Check status after execution.
Logger.log(
    'Data execution state: %s.',
    dataSourceTable.getStatus().getExecutionState(),
);

Este exemplo mostra como editar uma fonte de dados. 

SpreadsheetApp.enableBigQueryExecution();
const dataSheet = SpreadsheetApp.getActive().getSheetByName('Data Sheet 1');
const dataSourceTable = dataSheet.getDataSourceTables()[0];
const dataSource = dataSourceTable.getDataSource();
const newSpec = dataSource.getSpec()
                    .copy()
                    .asBigQuery()
                    .setRawQuery('select name from table limit 2')
                    .removeAllParameters()
                    .build();
// Updates data source specification and starts data execution asynchronously.
dataSource.updateSpec(newSpec);
// Check status during execution.
Logger.log(
    'Data execution state: %s.',
    dataSourceTable.getStatus().getExecutionState(),
);
// waitForCompletion() blocks script execution until data execution completes.
dataSourceTable.waitForCompletion(60);
// Check status after execution.
Logger.log(
    'Data execution state: %s.',
    dataSourceTable.getStatus().getExecutionState(),
);

Métodos

MétodoTipo de retornoBreve descrição
addColumns(columnNames)DataSourceTableAdiciona colunas à tabela de origem de dados.
addFilter(columnName, filterCriteria)DataSourceTableAdiciona um filtro aplicado à tabela de origem de dados.
addSortSpec(columnName, ascending)DataSourceTableAdiciona uma especificação de classificação a uma coluna na tabela da fonte de dados.
addSortSpec(columnName, sortOrder)DataSourceTableAdiciona uma especificação de classificação a uma coluna na tabela da fonte de dados.
cancelDataRefresh()DataSourceTableCancela a atualização de dados associada a esse objeto, se ela estiver em execução.
forceRefreshData()DataSourceTableAtualiza os dados desse objeto, independente do estado atual.
getColumns()DataSourceTableColumn[]Recebe todas as colunas da fonte de dados adicionadas à tabela de origem.
getDataSource()DataSourceRecebe a fonte de dados a que o objeto está vinculado.
getFilters()DataSourceTableFilter[]Retorna todos os filtros aplicados à tabela de origem de dados.
getRange()RangeRecebe o Range abrangido por essa tabela de fonte de dados.
getRowLimit()Integer|nullRetorna o limite de linhas para a tabela da fonte de dados.
getSortSpecs()SortSpec[]Recebe todas as especificações de classificação na tabela da fonte de dados.
getStatus()DataExecutionStatusRecebe o status de execução de dados do objeto.
isSyncingAllColumns()BooleanRetorna se a tabela da fonte de dados está sincronizando todas as colunas na fonte de dados associada.
refreshData()DataSourceTableAtualiza os dados do objeto.
removeAllColumns()DataSourceTableRemove todas as colunas da tabela de origem de dados.
removeAllSortSpecs()DataSourceTableRemove todas as especificações de classificação na tabela da fonte de dados.
setRowLimit(rowLimit)DataSourceTableAtualiza o limite de linhas da tabela de origem de dados.
syncAllColumns()DataSourceTableSincronize todas as colunas atuais e futuras na fonte de dados associada com a tabela da fonte de dados.
waitForCompletion(timeoutInSeconds)DataExecutionStatusAguarde até que a execução atual seja concluída, com tempo limite após o número de segundos fornecido.

Documentação detalhada

addColumns(columnNames)

Adiciona colunas à tabela de origem de dados.

Parâmetros

NomeTipoDescrição
columnNamesString[]A lista dos nomes das colunas a serem adicionadas.

Retornar

DataSourceTable: a tabela de origem de dados, para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

addFilter(columnName, filterCriteria)

Adiciona um filtro aplicado à tabela de origem de dados.

Parâmetros

NomeTipoDescrição
columnNameStringO nome da coluna a que esse filtro será aplicado.
filterCriteriaFilterCriteriaOs critérios de filtragem a serem aplicados.

Retornar

DataSourceTable: a tabela de origem de dados, para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

addSortSpec(columnName, ascending)

Adiciona uma especificação de classificação a uma coluna na tabela da fonte de dados.

Parâmetros

NomeTipoDescrição
columnNameStringO nome da coluna a ser classificada.
ascendingBooleanSe true, classifique a coluna em ordem crescente; se false, classifique a coluna em ordem decrescente.

Retornar

DataSourceTable: a planilha da fonte de dados, para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

addSortSpec(columnName, sortOrder)

Adiciona uma especificação de classificação a uma coluna na tabela da fonte de dados.

Parâmetros

NomeTipoDescrição
columnNameStringO nome da coluna a ser classificada.
sortOrderSortOrderA ordem de classificação.

Retornar

DataSourceTable: a planilha da fonte de dados, para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

cancelDataRefresh()

Cancela a atualização de dados associada a esse objeto, se ela estiver em execução.

Este exemplo mostra como cancelar uma atualização de fórmula. 

const spreadsheet = SpreadsheetApp.getActive();
const formula = spreadsheet.getDataSourceFormulas()[0];
// Cancel the ongoing refresh on the formula.
formula.cancelDataRefresh();

Gera uma exceção se o tipo de fonte de dados não estiver ativado. Use métodos SpreadsheetApp#enable...Execution() para ativar a execução de dados para um tipo específico de fonte de dados.

Retornar

DataSourceTable: o objeto de dados.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

forceRefreshData()

Atualiza os dados desse objeto, independente do estado atual. Consulte refreshData() para mais detalhes. Se quiser cancelar uma atualização em andamento desse objeto, consulte cancelDataRefresh().

Gera uma exceção se o tipo de fonte de dados não estiver ativado. Use métodos SpreadsheetApp#enable...Execution() para ativar a execução de dados para um tipo específico de fonte de dados.

Retornar

DataSourceTable: o objeto de dados.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getColumns()

Recebe todas as colunas da fonte de dados adicionadas à tabela de origem.

Retornar

DataSourceTableColumn[]: uma lista de colunas da tabela de origem de dados.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getDataSource()

Recebe a fonte de dados a que o objeto está vinculado.

Retornar

DataSource: a fonte de dados.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getFilters()

Retorna todos os filtros aplicados à tabela de origem de dados.

Retornar

DataSourceTableFilter[]: uma matriz de todos os filtros aplicados à tabela de origem de dados.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getRange()

Recebe o Range abrangido por essa tabela de fonte de dados.

Retornar

Range: o intervalo.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getRowLimit()

Retorna o limite de linhas para a tabela da fonte de dados.

Retornar

Integer|null: o limite de linhas para a tabela da fonte de dados ou null se nenhum limite for definido e a tabela usar o limite máximo padrão, como na interface das Planilhas Google.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getSortSpecs()

Recebe todas as especificações de classificação na tabela da fonte de dados.

Retornar

SortSpec[]: uma lista de especificações de classificação.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

getStatus()

Recebe o status de execução de dados do objeto.

Retornar

DataExecutionStatus: o status da execução de dados.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

isSyncingAllColumns()

Retorna se a tabela da fonte de dados está sincronizando todas as colunas na fonte de dados associada.

Retornar

Boolean: True se a tabela da fonte de dados estiver sincronizando todas as colunas na fonte de dados associada ou false caso contrário.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

refreshData()

Atualiza os dados do objeto.

Gera uma exceção se estiver no estado error. Use DataSource#updateSpec() para atualizar a especificação. O método é preferível a forceRefreshData() para evitar edições inesperadas na fonte de dados.

Gera uma exceção se o tipo de fonte de dados não estiver ativado. Use métodos SpreadsheetApp#enable...Execution() para ativar a execução de dados para um tipo específico de fonte de dados.

Retornar

DataSourceTable: o objeto de dados.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

removeAllColumns()

Remove todas as colunas da tabela de origem de dados.

Retornar

DataSourceTable: a tabela de origem de dados, para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

removeAllSortSpecs()

Remove todas as especificações de classificação na tabela da fonte de dados.

Retornar

DataSourceTable: a planilha da fonte de dados, para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

setRowLimit(rowLimit)

Atualiza o limite de linhas da tabela de origem de dados. Se o limite de linhas fornecido for null, a tabela da fonte de dados será atualizada para usar o limite máximo de linhas padrão, como na interface das Planilhas Google.

Parâmetros

NomeTipoDescrição
rowLimitIntegerO novo limite de linhas para a tabela de dados. Se null, atualiza a tabela para usar o limite de linhas padrão.

Retornar

DataSourceTable: a tabela de origem de dados, para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

syncAllColumns()

Sincronize todas as colunas atuais e futuras na fonte de dados associada com a tabela da fonte de dados.

Retornar

DataSourceTable: a tabela de origem de dados, para encadeamento.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets

waitForCompletion(timeoutInSeconds)

Aguarde até que a execução atual seja concluída, com tempo limite após o número de segundos fornecido. Gera uma exceção se a execução não for concluída quando o tempo limite expirar, mas não cancela a execução de dados.

Parâmetros

NomeTipoDescrição
timeoutInSecondsIntegerO tempo de espera para a execução de dados, em segundos. O máximo é 300 segundos.

Retornar

DataExecutionStatus: o status da execução de dados.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/spreadsheets