DataSourceSheet

Access and modify existing data source sheet. To create a new data source sheet, use `https://developers.google.com/apps-script/reference/spreadsheet/spreadsheet#insertDataSourceSheet(DataSourceSpec)`.


**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-sheet#addFilter(String,FilterCriteria)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Adds a filter applied to the data source sheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#asSheet()` | `https://developers.google.com/apps-script/reference/spreadsheet/sheet` | Returns the data source sheet as a regular sheet object. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#autoResizeColumn(String)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Auto resizes the width of the specified column. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#autoResizeColumns(String)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Auto resizes the width of the specified columns. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#cancelDataRefresh()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Cancels the data refresh associated with this object if it's currently running. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#forceRefreshData()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Refreshes the data of this object regardless of the current state. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#getColumnWidth(String)` | `Integer|null` | Returns the width of the specified column. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#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-sheet#getFilters()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet-filter` | Returns all filters applied to the data source sheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#getSheetValues(String)` | `Object[]` | Returns all the values for the data source sheet for the provided column name. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#getSheetValues(String,Integer,Integer)` | `Object[]` | Returns all the values for the data source sheet for the provided column name from the provided start row (based-1) and up to the provided `numRows`. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#getSortSpecs()` | `https://developers.google.com/apps-script/reference/spreadsheet/sort-spec` | Gets all the sort specs in the data source sheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#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-sheet#refreshData()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Refreshes the data of the object. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#removeFilters(String)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Removes all filters applied to the data source sheet column. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#removeSortSpec(String)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Removes the sort spec on a column in the data source sheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#setColumnWidth(String,Integer)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Sets the width of the specified column. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#setColumnWidths(String,Integer)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Sets the width of the specified columns. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#setSortSpec(String,Boolean)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Sets the sort spec on a column in the data source sheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#setSortSpec(String,SortOrder)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` | Sets the sort spec on a column in the data source sheet. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#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

### `addFilter(columnName, filterCriteria)`

Adds a filter applied to the data source sheet.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The name of the column to apply this filter to. |
| `filterCriteria` | `https://developers.google.com/apps-script/reference/spreadsheet/filter-criteria` | The filter criteria to apply. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` --- The data source sheet, for method chaining.

#### 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`

*** ** * ** ***

### `asSheet()`

Returns the data source sheet as a regular sheet object.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/sheet` --- The regular sheet.

#### 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`

*** ** * ** ***

### `autoResizeColumn(columnName)`

Auto resizes the width of the specified column.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The column name. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` --- This data source sheet, for chaining.

#### 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`

*** ** * ** ***

### `autoResizeColumns(columnNames)`

Auto resizes the width of the specified columns.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnNames` | `String[]` | The list of column names to update. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` --- This data source sheet, for chaining.

#### 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-sheet#` --- 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-sheet#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-sheet#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-sheet#` --- 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`

*** ** * ** ***

### `getColumnWidth(columnName)`

Returns the width of the specified column.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The column name. |

#### Return


`Integer|null` --- The column's width, or `null` if the column uses the default width.

#### 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`

*** ** * ** ***

### `getFilters()`

Returns all filters applied to the data source sheet.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet-filter` --- An array of all filters applied to the data source sheet.

#### 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`

*** ** * ** ***

### `getSheetValues(columnName)`

Returns all the values for the data source sheet for the provided column name.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The data source column name to fetch values for. |

#### Return


`Object[]` --- A one-dimensional array of values.

#### 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`

*** ** * ** ***

### `getSheetValues(columnName, startRow, numRows)`

Returns all the values for the data source sheet for the provided column name from the provided
start row (based-1) and up to the provided `numRows`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The data source column name to fetch values for. |
| `startRow` | `Integer` | The row position to start fetching values from. |
| `numRows` | `Integer` | The number of rows to fetch. |

#### Return


`Object[]` --- A one-dimensional array of values.

#### 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`

*** ** * ** ***

### `getSortSpecs()`

Gets all the sort specs in the data source sheet.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/sort-spec` --- A list of sort specs.

#### 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-sheet#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-sheet#` --- 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`

*** ** * ** ***

### `removeFilters(columnName)`

Removes all filters applied to the data source sheet column.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The name of the column to remove filters from. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` --- The data source sheet, for method chaining.

#### 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`

*** ** * ** ***

### `removeSortSpec(columnName)`

Removes the sort spec on a column in the data source sheet.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The name of the column. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` --- The data source sheet, for chaining.

#### 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`

*** ** * ** ***

### `setColumnWidth(columnName, width)`

Sets the width of the specified column.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The column name. |
| `width` | `Integer` | The new width for the column. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` --- This data source sheet, for chaining.

#### 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`

*** ** * ** ***

### `setColumnWidths(columnNames, width)`

Sets the width of the specified columns.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnNames` | `String[]` | The list of column names to update. |
| `width` | `Integer` | The new width for the columns. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` --- This data source sheet, for chaining.

#### 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`

*** ** * ** ***

### `setSortSpec(columnName, ascending)`

Sets the sort spec on a column in the data source sheet.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The name of the column to sort. |
| `ascending` | `Boolean` | If `true`, sort the column in ascending order; if `false`, sort the column in descending order. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` --- The data source sheet, for chaining.

#### 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`

*** ** * ** ***

### `setSortSpec(columnName, sortOrder)`

Sets the sort spec on a column in the data source sheet.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `columnName` | `String` | The name of the column to sort. |
| `sortOrder` | `https://developers.google.com/apps-script/reference/spreadsheet/sort-order` | The sort order. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-sheet#` --- The data source sheet, for chaining.

#### 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`