DataSourceFormula

Access and modify existing data source formulas. To create a new data source formula, use `https://developers.google.com/apps-script/reference/spreadsheet/range#setFormula(String)`.


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

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#cancelDataRefresh()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#` | Cancels the data refresh associated with this object if it's currently running. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#forceRefreshData()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#` | Refreshes the data of this object regardless of the current state. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#getAnchorCell()` | `https://developers.google.com/apps-script/reference/spreadsheet/range` | Returns the `https://developers.google.com/apps-script/reference/spreadsheet/range` representing the cell where this data source formula is anchored. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#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-formula#getDisplayValue()` | `String` | Returns the display value of the data source formula. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#getFormula()` | `String` | Returns the formula for this data source formula. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#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-formula#refreshData()` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#` | Refreshes the data of the object. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#setFormula(String)` | `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#` | Updates the formula. |
| `https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#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

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

*** ** * ** ***

### `getAnchorCell()`

Returns the `https://developers.google.com/apps-script/reference/spreadsheet/range` representing the cell where this data source formula is anchored.

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/range` --- The anchor cell.

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

*** ** * ** ***

### `getDisplayValue()`

Returns the display value of the data source formula.

#### Return


`String` --- The display 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`

*** ** * ** ***

### `getFormula()`

Returns the formula for this data source formula.

#### Return


`String` --- The formula.

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

*** ** * ** ***

### `setFormula(formula)`

Updates the formula.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `formula` | `String` | The new formula. |

#### Return


`https://developers.google.com/apps-script/reference/spreadsheet/data-source-formula#` --- The data source formula, 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`