DataSourcePivotTable

Access and modify existing data source pivot table. To create a new data source pivot table, use
`https://developers.google.com/apps-script/reference/spreadsheet/range#createDataSourcePivotTable(DataSource)`.


**Only use this class with data that's connected to a database.**

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#addColumnGroup(String)` | `https://developers.google.com/apps-script/reference/spreadsheet/pivot-group` | Adds a new pivot column group based on the specified data source column. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#addFilter(String,FilterCriteria)` | `https://developers.google.com/apps-script/reference/spreadsheet/pivot-filter` | Adds a new filter based on the specified data source column with the specified filter criteria. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#addPivotValue(String)` | `https://developers.google.com/apps-script/reference/spreadsheet/pivot-value` | Adds a new pivot value based on the specified data source column without any summarize function. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#addPivotValue(String,PivotTableSummarizeFunction)` | `https://developers.google.com/apps-script/reference/spreadsheet/pivot-value` | Adds a new pivot value based on the specified data source column with the specified summarize function. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#addRowGroup(String)` | `https://developers.google.com/apps-script/reference/spreadsheet/pivot-group` | Adds a new pivot row group based on the specified data source column. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#asPivotTable()` | `https://developers.google.com/apps-script/reference/spreadsheet/pivot-table` | Returns the data source pivot table as a regular pivot table object. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#cancelDataRefresh()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#` | Cancels the data refresh associated with this object if it's currently running. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#forceRefreshData()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#` | Refreshes the data of this object regardless of the current state. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#getDataSource()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source` | Gets the data source the object is linked to. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#getStatus()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-execution-status` | Gets the data execution status of the object. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#refreshData()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#` | Refreshes the data of the object. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#waitForCompletion(Integer)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-execution-status` | Waits until the current execution completes, timing out after the provided number of seconds. |

## Detailed documentation

### `addColumnGroup(columnName)`

Adds a new pivot column group based on the specified data source column.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The data source column name the pivot group is based on. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/pivot-group` --- The new pivot group.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `addFilter(columnName, filterCriteria)`

Adds a new filter based on the specified data source column with the specified filter criteria.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The data source column name the filter is based on. |
| `filterCriteria` | `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria` | The criteria the filter uses. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/pivot-filter` --- The new filter.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `addPivotValue(columnName)`

Adds a new pivot value based on the specified data source column without any summarize
function. For Looker measures only.

The following code shows how you can add a Looker measure as a pivot value.

```javascript
// TODO(developer): Replace with your spreadsheet ID which has a Looker data
// source.
const spreadsheet = SpreadsheetApp.openById('abcd1234');
const datasource = spreadsheet.getDataSources()[0];
const pivotTable = datasource.createDataSourcePivotTableOnNewSheet();

pivotTable.addPivotValue('columnName');
```

This method is only available for Looker data sources.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The data source column name the pivot value is based on. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/pivot-value` --- The new pivot value.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `addPivotValue(columnName, summarizeFunction)`

Adds a new pivot value based on the specified data source column with the specified summarize
function.

In order to add pivot values for Looker measures, use `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#addPivotValue(String)`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The data source column name the pivot value is based on. |
| `summarizeFunction` | `https://developers.google.com/apps-script/reference/spreadsheet/pivot-table-summarize-function` | The summarize function the pivot value uses. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/pivot-value` --- The new pivot value.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `addRowGroup(columnName)`

Adds a new pivot row group based on the specified data source column.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The data source column name the pivot group is based on. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/pivot-group` --- The new pivot group.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `asPivotTable()`

Returns the data source pivot table as a regular pivot table object.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/pivot-table` --- The pivot table.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `cancelDataRefresh()`

Cancels the data refresh associated with this object if it's currently running.

This example shows how to cancel a formula refresh.

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

Throws an exception if the data source type is not enabled. Use `SpreadsheetApp#enable...Execution()` methods to enable data execution for specific data source
type.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#` --- The data object.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `forceRefreshData()`

Refreshes the data of this object regardless of the current state. See `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#refreshData()` for
more details. If you want to cancel a currently running refresh of this object, see `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#cancelDataRefresh()`.

Throws an exception if the data source type is not enabled. Use `SpreadsheetApp#enable...Execution()` methods to enable data execution for specific data source
type.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#` --- The data object.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `getDataSource()`

Gets the data source the object is linked to.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source` --- The data source.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `getStatus()`

Gets the data execution status of the object.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-execution-status` --- The data execution status.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `refreshData()`

Refreshes the data of the object.

Throws an exception if currently in `https://developers.google.com/apps-script/reference/spreadsheet/data-execution-state#ERROR` state. Use `https://developers.google.com/apps-script/reference/spreadsheet/data-source#updateSpec(DataSourceSpec)` to update the specification. The method is
preferred over `https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#forceRefreshData()` to prevent unexpected edits on data source.

Throws an exception if the data source type is not enabled. Use `SpreadsheetApp#enable...Execution()` methods to enable data execution for specific data source
type.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-pivot-table#` --- The data object.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`

*** ** * ** ***

### `waitForCompletion(timeoutInSeconds)`

Waits until the current execution completes, timing out after the provided number of seconds.
Throws an exception if the execution is not completed when timing out, but does not cancel the
data execution.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `timeoutInSeconds` | `Integer` | The time to wait for data execution, in seconds. The maximum is 300 seconds. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-execution-status` --- The data execution status.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/spreadsheets.currentonly`
- `https://www.googleapis.com/auth/spreadsheets`